Create a Shipping Claim via API

This guide walks through the full flow for creating a shipping protection claim programmatically using the Commerce API.

Commerce API Reference

1. Check if the order is protected

   Call GET /orders/{orderId} and look for isShippingProtected: true in the response. If the value is false, the order is not eligible for a shipping claim.

   • orderId — the Corso-assigned order identifier
   • sourceOrderId — the Shopify order ID

   {
     "orderId": 18372912,
     "sourceOrderId": "842810",
     "isShippingProtected": true,
     ...
   }

2. Check for an existing shipping claim

   Before creating a new claim, call GET /shipping-claims and filter by sourceOrderId or orderId from the previous step. If a claim already exists for the order, do not create a duplicate.

3. Create the shipping claim

   If the order is protected and no claim exists, call POST /shipping-claims. The request body must include the lineItems that are part of the claim—not necessarily all line items on the order, just the ones affected by the shipping issue (e.g. lost or damaged items). See the full request body and field reference in the API docs.

4. Check the claim status

   Use the shippingClaimId returned from the create response to call GET /shipping-claims/{shippingClaimId}. The response includes the current status and resolution details.

   {
     "shippingClaimId": 456789,
     "status": "Open",
     "reason": "Lost",
     ...
   }

Looking up a claim later

If you need to check the status of a shipping claim at a later date, call GET /shipping-claims and filter by sourceOrderId to find claims associated with a specific order. Then use the shippingClaimId from the response to call GET /shipping-claims/{shippingClaimId} for the full claim details, including current status and resolution.