Get an order by ID - v3

curl --request GET \
  --url https://api.snappy.com/public-api/v3/orders/{orderId} \
  --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"
  }
}

Orders

Get order by ID

Use this endpoint to retrieve a single order by its identifier with full detail - line items, recipient, shipping address, fulfillments with tracking information, tags, and metadata. Use this when you need detail beyond what’s returned by GET /v3/orders (which returns the same shape) - typically for a single-order detail view or to refresh tracking information.

Required fields:

orderId - the order identifier, passed as a path parameter.

Optional parameters:

Snappy-Account-Id header - optional account scoping.
Snappy-Company-Id header - optional company scoping.

Please note:

Returns 404 if no order exists for the supplied orderId, or if it exists but belongs to a different Company. Existence is intentionally hidden across Companies.
fulfillments is an empty array ([]) when the order has not yet been shipped or when tracking information is unavailable.
cancellationDetails is populated only when status is cancelled; null otherwise.
metadata is null when no metadata was supplied at order creation.
PII fields (recipient name, tracking info) are masked under the orders:read:masked scope and returned in full under orders:read:unmasked.

Permissions

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

GET

orders

{orderId}

Get an order by ID - v3

curl --request GET \
  --url https://api.snappy.com/public-api/v3/orders/{orderId} \
  --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"
  }
}

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"

Path Parameters

orderId

string

required

The unique identifier of the order to retrieve.

Pattern: ^[A-Za-z0-9]{8,}$

Example:

"G7nR4bD9mK"

Response

Order.

JSON:API single-resource envelope for an order.

data

object

required

Order details including line items, recipient, shipping address, fulfillments, and tracking information.

Show child attributes

Last modified on June 17, 2026

Get orders

Cancel order