API Quick Start

This quickstart introduces the AfterShip Warranty API and the main claim management scenarios supported by the public API.

1. What is AfterShip Warranty API?

AfterShip Warranty API helps merchants integrate claim operations with their internal systems. You can query claims, make review decisions, start fulfillment, provide shipment information, and keep item-level tags and images in sync.

graph TD MerchantSystem(("Merchant system")) WarrantyAPI["AfterShip Warranty API"] WarrantyWebhook["AfterShip Warranty Webhook"] WarrantyCore(("AfterShip Warranty")) MerchantSystem--"1. Query and operate claims"-->WarrantyAPI WarrantyAPI--"2. Apply status, item, and shipment updates"-->WarrantyCore WarrantyCore--"3. Send claim updates"-->WarrantyWebhook WarrantyWebhook--"4. Sync latest claim state"-->MerchantSystem

2. Get the API key

AfterShip verifies API requests with the as-api-key request header.

To get an API key, visit API keys, click Create an API key, and follow the instructions.

3. API Endpoint

preparing...

All endpoints are accessible only through HTTPS.

Example:

preparing...

4. Common scenarios

The Warranty API is designed around the current claim lifecycle:

stateDiagram-v2 [*] --> under_review: Claim submitted under_review --> approved: POST /claims/{claim_id}/approve under_review --> rejected: POST /claims/{claim_id}/reject approved --> in_process: POST /claims/{claim_id}/process approved --> canceled: POST /claims/{claim_id}/cancel in_process --> completed: POST /claims/{claim_id}/resolve in_process --> canceled: POST /claims/{claim_id}/cancel rejected --> [*] completed --> [*] canceled --> [*]

Find claims to work on

Use GET /claims as the entry point to find claims that need review, fulfillment, warehouse receiving, shipment updates, or back-office item updates.

Review a claim

Use GET /claims/{claim_id} to inspect the claim. When the status is under_review, approve or reject it.

sequenceDiagram participant Client participant WarrantyAPI Client->>WarrantyAPI: GET /claims/{claim_id} WarrantyAPI-->>Client: status=under_review alt approve Client->>WarrantyAPI: POST /claims/{claim_id}/approve WarrantyAPI-->>Client: status=approved else reject Client->>WarrantyAPI: POST /claims/{claim_id}/reject WarrantyAPI-->>Client: status=rejected end

Fulfill an approved claim

After approval, call POST /claims/{claim_id}/match-resolution to check which resolution methods are supported and which stores can be used. When a resolution requires a store selection, use the returned platform and external_id in the later process request.

Then call POST /claims/{claim_id}/process with the selected resolution_method, such as replace_item, repair_item, send_repair_kit, issue_store_credit, or other. The response returns the updated Claim resource.

sequenceDiagram participant Client participant WarrantyAPI Client->>WarrantyAPI: POST /claims/{claim_id}/match-resolution WarrantyAPI-->>Client: resolution_method stores[] Client->>WarrantyAPI: POST /claims/{claim_id}/process WarrantyAPI-->>Client: status=in_process Client->>WarrantyAPI: POST /claims/{claim_id}/resolve WarrantyAPI-->>Client: status=completed

Provide shipment information

Use POST /claims/{claim_id}/shipments to provide inbound or outbound shipment information. Automatic label generation can continue asynchronously, so clients should poll GET /claims/{claim_id}/shipments/{shipment_id} until the label generation result is created or failed.

sequenceDiagram participant Client participant WarrantyAPI Client->>WarrantyAPI: POST /claims/{claim_id}/shipments WarrantyAPI-->>Client: shipment_id, label_generation_result.status=creating loop Poll until terminal label status Client->>WarrantyAPI: GET /claims/{claim_id}/shipments/{shipment_id} WarrantyAPI-->>Client: label_generation_result.status end alt label created Client->>WarrantyAPI: GET /claims/{claim_id}/shipments/{shipment_id} WarrantyAPI-->>Client: label.url, tracking_number else label failed Client->>WarrantyAPI: GET /claims/{claim_id}/shipments/{shipment_id} WarrantyAPI-->>Client: label_generation_result.failed_detail Client->>WarrantyAPI: POST /claims/{claim_id}/shipments WarrantyAPI-->>Client: merchant uploaded label shipment end

Mark items as received

Use POST /claims/{claim_id}/receive when the warehouse receives the returned item. This is a side operation and does not change the main claim status.

stateDiagram-v2 approved --> approved: POST /claims/{claim_id}/receive in_process --> in_process: POST /claims/{claim_id}/receive

Tag items or upload item images

Use GET /item-tags to fetch available item tag IDs, then call PATCH /claims/{claim_id}/items/{item_id} with either item_tags or merchant_image_urls. Send only one field family in a single patch request.

sequenceDiagram participant Client participant WarrantyAPI Client->>WarrantyAPI: GET /item-tags WarrantyAPI-->>Client: item_tags[] Client->>WarrantyAPI: PATCH /claims/{claim_id}/items/{item_id} WarrantyAPI-->>Client: updated item_tags / merchant_uploaded_image_urls