List orders - v3

curl --request GET \
  --url https://api.snappy.com/public-api/v3/orders \
  --header 'X-Api-Key: <api-key>'

{
  "data": [
    {
      "id": "G7nR4bD9mK",
      "createdAt": "2026-05-27T10:30:00.000Z",
      "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": "inTransit",
          "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": {
        "key1": "value1",
        "key2": "value2"
      },
      "idempotencyKey": "order-2026-05-13-abc"
    }
  ],
  "links": {
    "first": "/v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=1",
    "next": "/v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=2",
    "prev": null
  }
}

Orders

Get orders

Use this endpoint to retrieve a paginated list of orders for the calling Company. Use this when you want to browse orders, look up orders matching specific idempotency keys, or sync recent order activity to your system.

Filtering options:

filter[status] - exact match on order status. One of active (in progress or delivered) or cancelled.
filter[idempotencyKey] - comma-separated list of idempotency keys. Returns orders matching any of the supplied keys.
filter[createdAt][gte] - return orders created at or after this ISO 8601 timestamp.
filter[createdAt][lte] - return orders created at or before this ISO 8601 timestamp.
Snappy-Account-Id header - optional account scoping.
Snappy-Company-Id header - optional company scoping.

Pagination and sorting:

page[number] - 1-indexed page number (default 1).
page[size] - number of orders per page (max 300, default 100).
sort - -createdAt (default, newest first) or createdAt (oldest first).

Please note:

Uses page-number pagination (not cursor, unlike product list endpoints). The response includes a top-level links object with first, next, and prev URLs.
The filter[idempotencyKey] filter is useful for looking up orders created by specific replays. Follow the order with GET /v3/orders/{orderId} if you need additional detail beyond what’s in the list response.
Both Direct Fulfillment orders and Triggered Gifting orders are returned by this endpoint - they share the same response shape.
PII masking applies based on the scope used for the request.

Permissions

Requires: orders:read:masked or orders:read:unmasked

GET

orders

List orders - v3

curl --request GET \
  --url https://api.snappy.com/public-api/v3/orders \
  --header 'X-Api-Key: <api-key>'

{
  "data": [
    {
      "id": "G7nR4bD9mK",
      "createdAt": "2026-05-27T10:30:00.000Z",
      "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": "inTransit",
          "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": {
        "key1": "value1",
        "key2": "value2"
      },
      "idempotencyKey": "order-2026-05-13-abc"
    }
  ],
  "links": {
    "first": "/v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=1",
    "next": "/v3/products/655277e68e0719000d6c3fd5/variants?page[size]=100&page[number]=2",
    "prev": null
  }
}

Authorizations

X-Api-Key

string

header

required

Company Level Authentication

Include your API key in the X-Api-Key header for every request:

X-Api-Key: YOUR_API_KEY

Headers

snappy-account-id

string

Optional account identifier for swag validation/filtering.

Example:

"acc123456"

snappy-company-id

string

Optional company identifier for swag validation/filtering.

Example:

"cmp123456"

Query Parameters

page[number]

integer

default:1

Page number, starting at 1. Defaults to 1 when omitted.

Required range: x >= 1

Example:

1

page[size]

integer

default:100

Page size. Must be between 1 and 300. Defaults to 100 when omitted.

Required range: 1 <= x <= 300

Example:

100

sort

enum<string>

default:-createdAt

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

Available options:

createdAt,

-createdAt

Example:

"-createdAt"

filter[status]

enum<string>

Filter by order status.

Available options:

active,

cancelled

Example:

"active"

filter[idempotencyKey]

string[]

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

Minimum array length: 1

Minimum string length: 1

Example:

["idem-abc", "idem-def"]

filter[createdAt]

object

Filter by order creation timestamp. Accepts full ISO timestamps via filter[createdAt][gte] and filter[createdAt][lte].

Show child attributes

Response

Page of orders plus pagination links.

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

data

object[]

required

Orders matching the query, ordered per sort.

Show child attributes

links

object

required

Top-level JSON:API-style pagination links for paginated list responses. first, next, and prev are all required and all nullable. prev is null on cursor-paginated endpoints (backward navigation not supported).

Show child attributes

Last modified on June 17, 2026

Place order

Get order by ID