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>'

const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch('https://api.snappy.com/public-api/v3/orders/{orderId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.snappy.com/public-api/v3/orders/{orderId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.snappy.com/public-api/v3/orders/{orderId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.snappy.com/public-api/v3/orders/{orderId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

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.

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.
Returns 409 when the order is still being prepared. Retry the request shortly.
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.
shippingAddress is populated in full for physical orders. For digital orders (e.g. gift cards, where the variant’s shippingRequired is false), only countryCode is present - the other address fields are omitted since there’s no physical delivery.
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>'

const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};

fetch('https://api.snappy.com/public-api/v3/orders/{orderId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.snappy.com/public-api/v3/orders/{orderId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.snappy.com/public-api/v3/orders/{orderId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.snappy.com/public-api/v3/orders/{orderId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

{
  "message": "Product not found.",
  "errorCode": "404_PROD_001",
  "errors": [
    {
      "message": "Product with id 'q1w2e3r4t5' was not found",
      "path": "pathParameters.productId",
      "errorCode": "404_PROD_001"
    }
  ]
}

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

Must be provided to retrieve swag products.

Example:

"acc123456"

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

Authentication

Marketplace

Gifting

Administration

Get order by ID

Required fields:

Optional parameters:

Please note:

Permissions

Authorizations

Company Level Authentication

Headers

Path Parameters

Response