Skip to main content
GET
/
v3
/
orders
List orders
curl --request GET \
  --url https://api.snappy.com/v3/orders \
  --header 'X-Api-Key: <api-key>'
{
  "data": [
    {
      "id": "G7nR4bD9mK",
      "status": "active",
      "fulfillmentStatus": "unfulfilled",
      "tags": [],
      "cancellationDetails": {
        "cancelledAt": "2026-05-27T15:57:00.000Z",
        "cancellationReason": "customer_requested"
      },
      "lineItems": [
        {
          "variantId": "v_abc12345",
          "quantity": 1,
          "title": "Premium Gift Card"
        }
      ],
      "fulfillments": [
        {
          "fulfillmentLineItems": [
            {
              "variantId": "v_abc12345",
              "quantity": 1,
              "title": "Premium Gift Card"
            }
          ],
          "id": "tr_abc123",
          "status": "in_transit",
          "trackingCompany": "UPS",
          "trackingInfo": {
            "number": "1Z9999W99999999999",
            "url": "https://www.ups.com/track?tracknum=1Z9999W99999999999"
          }
        }
      ],
      "recipient": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+15555555555"
      },
      "shippingAddress": {
        "address1": "123 Main St",
        "address2": "Suite A",
        "city": "New York",
        "provinceCode": "NY",
        "countryCode": "US",
        "postalCode": "10001"
      },
      "metadata": {
        "externalRecipientId": "crm-user-987",
        "campaign": "q4-vip"
      },
      "idempotencyKey": "order-2026-05-13-abc"
    }
  ],
  "links": {
    "first": "/v3/collections/abc/products?page[size]=100",
    "next": "/v3/collections/abc/products?page[cursor]=cursor_abc123&page[size]=100",
    "prev": "<string>"
  }
}

Authorizations

X-Api-Key
string
header
required

Partner API key. Finalized per partner integration agreement.

Headers

Snappy-Account-Id
string

Optional account identifier for scoping/validation/filtering.

Snappy-Company-Id
string

Optional company identifier for scoping/validation/filtering.

Query Parameters

page[number]
integer
default:1

1-indexed page number. Defaults to 1.

Required range: x >= 1
page[size]
integer
default:100

Number of orders to return per page (max 300, default 100).

Required range: 1 <= x <= 300
sort
enum<string>
default:-createdAt

Sort order. -createdAt (default) returns newest first; createdAt returns oldest first.

Available options:
createdAt,
-createdAt
filter[status]
enum<string>

Filter by order status. active: orders that are in progress or have been delivered. cancelled: orders that were cancelled.

Available options:
active,
cancelled
filter[idempotencyKey]
string[]

Comma-separated list of idempotency keys. Returns orders matching any of the supplied keys.

Minimum array length: 1
filter[createdAt][gte]
string<date-time>

Return orders created at or after this ISO 8601 timestamp.

filter[createdAt][lte]
string<date-time>

Return orders created at or before this ISO 8601 timestamp.

Response

Page of orders plus pagination links.

JSON:API list envelope. Returns the page of orders plus pagination links.

data
object[]
required

Top-level JSON:API-style pagination links for paginated list responses. first is always present. next is null on the final page. prev is null on the first page (and on cursor-paginated endpoints where backward navigation is not supported).

Last modified on June 3, 2026