Customer Support Integrations
Most questions a support team gets about returns, warranties, and shipping protection come down to "where is my claim?" These endpoints let a helpdesk (or any internal support tool) show an agent everything Corso knows about the customer on a ticket, without the agent leaving the ticket to search Corso.
When to Use These Endpoints
Use them to build a customer panel beside a ticket. The usual flow is:
- A ticket arrives. Your helpdesk knows the customer's email, and often the order the ticket is about.
- Look the customer up in Corso. Fetch their claims, shipping protection claims, registrations, and orders by email, or by order when the ticket is linked to one.
- Show the agent what matters. Each claim's status, what was requested and issued, return label and tracking, plus an "Open in Corso" link.
- Keep the ticket current. Subscribe to webhooks so the panel updates when a claim changes, rather than polling.
Looking Up a Customer by Email
When all your helpdesk has is the customer's email address, request each resource with customerEmail:
curl --request GET \
--url 'https://api.corso.com/v1/claims?customerEmail=customer%40example.com' \
--header 'authorization: Bearer eyJhbyfQ...adQssw5c'
| Endpoint | What customerEmail matches |
|---|---|
GET /claims | The email the customer filed the return or warranty claim with. This can differ from the order email. |
GET /shipping-claims | The email on the order the shipping protection claim was filed against. |
GET /registrations | The email the customer registered their product with. |
GET /orders | The email on the order. |
Emails match exactly, so pass the address as your helpdesk received it. Every list returns newest first and paginates with first and after, so the first page is usually all an agent needs.
To narrow orders to one the customer named in their message, add orderNameOrNumber (for example #1580). It is only accepted alongside customerEmail.
Looking Up by Order
When a ticket is already linked to an order, filter by the order instead. Pass sourceOrderId with your platform's order ID (for Shopify, the numeric order ID), or orderId with the Corso order ID:
curl --request GET \
--url 'https://api.corso.com/v1/claims?sourceOrderId=7425696170134' \
--header 'authorization: Bearer eyJhbyfQ...adQssw5c'
GET /orders, GET /claims, and GET /shipping-claims all accept sourceOrderId. GET /claims and GET /shipping-claims also accept orderId. An order lookup returns isShippingProtected, which tells an agent whether the customer can file a shipping protection claim at all.
What to Show an Agent
A claim carries everything an agent usually needs to answer a customer without opening Corso:
| Question | Where to find it |
|---|---|
| What is the status? | status on the claim, and status / statusDetail on each of its claimLineItems. |
| What did they ask for? | requestSummary while the claim is open, and requestedResolutionMethod on each line item. |
| What did they get? | resolutionSummary once the claim is finalized: refunds, gift cards, and replacement orders. |
| Where is the return? | shipments: labelUrl, qrCodeUrl, carrierTrackingUrl, and carrierTrackingStatus for each return. |
| How do I change it? | merchantAppUrl links to the claim in the Corso merchant app. |
Shipping protection claims follow the same shape with their own status, reason, resolutionSummary, and merchantAppUrl. Orders and registrations carry an merchantAppUrl too.
Approving, denying, and finalizing return and warranty claims happens in Corso, not through the API. Link agents there with merchantAppUrl, which opens the claim directly for anyone signed in to the store.
Filing a Shipping Protection Claim
An agent can file a shipping protection claim for a customer straight from the ticket with POST /shipping-claims. Look the order up first to get its Corso orderId and the lineItemId of each affected item:
curl --request POST \
--url 'https://api.corso.com/v1/shipping-claims' \
--header 'authorization: Bearer eyJhbyfQ...adQssw5c' \
--header 'content-type: application/json' \
--data '{
"orderId": 18372912,
"reason": "Lost",
"noteFromMerchant": "Filed from ticket #48213",
"lineItems": [{ "lineItemId": 42, "quantity": 1 }],
"notifyCustomer": true
}'
Set notifyCustomer to true to send the customer Corso's pre-configured claim email, or leave it off when the agent is already replying on the ticket.
Keeping Tickets Current
Rather than polling, subscribe a webhook endpoint in Corso Admin to the topics your panel shows:
claim/created,claim/updated, andclaim/finalizedfor returns and warranties.shipping_claim/created,shipping_claim/updated, andshipping_claim/finalizedfor shipping protection.registration/createdfor product registrations.
Each payload is the same resource the list endpoints return, including customerEmail and merchantAppUrl, so you can match it to an open ticket by email or order and refresh the panel in place. See Webhooks for headers, signature verification, and payload examples.
Credentials
A support integration uses the same client credentials as the rest of the Commerce API; see Authenticating. If one set of credentials covers several stores, every lookup searches all of them, and each result's storeId says which store it belongs to.