Order Management

Track order delivery statuses and request order refunds

Order Tracking

Order tracking only works for Amazon orders right now.

Integration Steps

1. Obtain Crossmint API key

   Create a project in the Crossmint Console, obtain a server-side API key from the Overview page, and make sure to save it for later use.

2. Fetch orderId

   Obtain the orderId from the response of the Create Order endpoint.

3. Track order

   curl

   curl -X GET "https://staging.crossmint.com/api/unstable/orders/${orderId}/tracking" \
   -H "X-API-KEY: ${API_KEY}" \
   -H "Content-Type: application/json"
   

   Example Response

   [
       {
           "status": "shipped",
           "packageTracking": {
               "carrierName": "Amazon",
               "carrierTrackingNumber": "TBA123456789"
           },
           "deliveryTimeRange": {
               "lowerBound": "2025-08-16T12:28:34.97Z",
               "upperBound": "2025-08-16T18:28:34.97Z"
           }
       }
   ]
   

   • Status delivered is only guaranteed for Amazon packages at the moment.
   • If the package is in delivered state, lowerBound is equal to upperBound and it’s just the time the package arrived.

Order Refunds

Crossmint supports requests for refunds. As part of their request they can specify the reason they want a refund. Crossmint will process their request and email them with a shipping label to return the product in order to receive the refund.

Integration Steps

1. Obtain Crossmint API key

   Create a project in the Crossmint Console, obtain a server-side API key from the Overview page, and make sure to save it for later use.

2. Identify product

   • Fetch an order’s products via the Get Order API
   • Identify a specific product via its index in the lineItems array, i.e. 0.
3. Submit refund request

   A user can only specify one product per refund request and the reason they are submiting the refund.

   curl

   curl -X POST "https://staging.crossmint.com/api/unstable/orders/${orderId}/refunds" \
   -H "X-API-KEY: ${API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
       "lineItem": 0,
       "reason": "I want to return this product and get a refund as it is defective"
   }'
   

   Example Response

   {
       "orderId": "order_123456789",
       "lineItem": 0,
       "reason": "I want to return this product and get a refund as it is defective",
       "status": "refund-request-initiated"
   }
   
4. Track refund request status

   Track the status value returned from the following endpoint. To fetch a specific product’s refund status specify a lineItem index value as a query parameter, otherwise fetch them all, by default.

   curl

   curl -X GET "https://staging.crossmint.com/api/unstable/orders/${orderId}/refunds" \
   -H "X-API-KEY: ${API_KEY}" \
   -H "Content-Type: application/json"
   

   Example Response

   [
       {
           "orderId": "order_123456789",
           "lineItem": 1,
           "reason": "I want to return this product and get a refund as it is defective",
           "status": "refund-request-accepted"
       },
       {
           "orderId": "order_123456789",
           "lineItem": 2,
           "reason": "Item arrived damaged",
           "status": "refund-request-completed"
       }
   ]
   

   Potential status values:

   • refund-request-initiated: Refund request has been submitted
   • refund-request-accepted: Refund request has been approved
   • refund-request-rejected: Refund request has been denied
   • refund-request-completed: Refund has been processed and completed
5. Return product and receive refund

   Crossmint will send a return shipping label to the email that was used to complete the order when the status from Step 4 is refund-request-accepted. Once the product is successfully returned, the status from Step 4 will be set to refund-request-completed and the user will receive the refund to the wallet that paid for the order.