Catalog API Documentation

Browse endpoints, parameters, and live request examples.

GET /orders/{external_order_id}

Track order status and fulfillment

Retrieves detailed tracking information for a specific order including current status, shipping details, and fulfillment progress. Uses your order number as the primary lookup method.

You can optionally pass the external user id you passed when creating the order. If the order number is valid but was purchased by a different user we will return not found.

Order

Parameters

external_order_id required path (string)

The external order number to track

external_user_id query (string)

Optional user ID for additional validation

Responses

200 Order tracking information
Physical product order with shipping 
{
  "order": {
    "address_1": "123 Main Street",
    "address_2": "Apt 4B",
    "city": "New York",
    "country": "US",
    "created": "2025-01-15T10:00:00Z",
    "email": "john.doe@example.com",
    "external_order_id": "ORDER-2024-001",
    "external_user_id": "user-456",
    "fulfillments": [
      {
        "created_at": "2025-01-15T10:30:00Z",
        "fulfillment_id": "FULFILL-001",
        "fulfillment_instructions": "Leave at door if not home",
        "fulfillment_type": "physical",
        "line_item_ids": [
          "550e8400-e29b-41d4-a716-446655440001"
        ],
        "shipped_date": "2025-01-15T12:00:00Z",
        "shipper": "UPS",
        "tracking_number": "1Z999AA10123456784",
        "updated_at": "2025-01-15T14:30:00Z"
      }
    ],
    "given_name": "John",
    "is_test": false,
    "line_items": [
      {
        "product_options": {},
        "points": 500,
        "is_explicit": false,
        "category_ids": [
          10,
          25
        ],
        "retail_price": "79.99",
        "points_paid": 0,
        "item_type_id": 200,
        "availability": "In stock",
        "tag_ids": [
          35
        ],
        "is_stock_reserved": false,
        "status": "fulfilled",
        "updated_at": "2025-01-15T14:30:00Z",
        "description": "Premium noise-cancelling wireless headphones",
        "name": "Wireless Headphones",
        "brand_id": 123,
        "is_taxable": true,
        "price": "49.99",
        "model": "WH-1000X",
        "images": [
          {
            "alt": "Wireless Headphones",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/12345.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/12345.jpg"
            }
          }
        ],
        "errors": [],
        "shipping_estimate": "9.99",
        "rank": 150,
        "original_points": 600,
        "brand": "AudioTech",
        "fulfillment_type": "physical",
        "is_primary": false,
        "tax_paid": "4.99",
        "shipping_paid": "9.99",
        "options": [],
        "product_id": "PROD-001",
        "catalog_item_id": 12345,
        "price_paid": "49.99",
        "supplier_reference_id": "SUP-AT-WH500",
        "is_available": true,
        "metadata": {
          "color": "black",
          "warranty": "2-year"
        },
        "required_fields": {
          "address_1": true,
          "address_2": false,
          "address_3": false,
          "address_4": false,
          "city": true,
          "country": true,
          "email": false,
          "given_name": true,
          "phone_number": false,
          "postal_code": true,
          "state_or_region": true,
          "surname": true
        },
        "supplier_id": 1001,
        "line_item_id": "550e8400-e29b-41d4-a716-446655440001",
        "is_limited_stock": false,
        "created_at": "2025-01-15T10:00:00Z",
        "original_price": "59.99"
      }
    ],
    "order_number": "C234-56789-ABCDE-0001",
    "phone_number": "555-123-4567",
    "postal_code": "10001",
    "socket_id": 100,
    "state_or_region": "NY",
    "surname": "Doe",
    "updated": "2025-01-15T14:30:00Z"
  },
  "success": true,
  "timestamp": "2025-01-15T14:30:00Z"
}
Order placed with points 
{
  "order": {
    "address_1": "789 Elm Street",
    "city": "Chicago",
    "country": "US",
    "created": "2025-01-15T09:00:00Z",
    "email": "alice.j@example.com",
    "external_order_id": "ORDER-2024-003",
    "external_user_id": "user-321",
    "fulfillments": [
      {
        "created_at": "2025-01-15T09:30:00Z",
        "fulfillment_id": "FULFILL-003",
        "fulfillment_type": "physical",
        "line_item_ids": [
          "550e8400-e29b-41d4-a716-446655440003"
        ],
        "updated_at": "2025-01-15T14:00:00Z"
      }
    ],
    "given_name": "Alice",
    "is_test": false,
    "line_items": [
      {
        "product_options": {},
        "points": 2000,
        "is_explicit": false,
        "category_ids": [
          15,
          20
        ],
        "retail_price": "24.99",
        "points_paid": 2000,
        "item_type_id": 400,
        "availability": "In stock",
        "tag_ids": [
          45
        ],
        "is_stock_reserved": false,
        "status": "fulfilled",
        "updated_at": "2025-01-15T14:00:00Z",
        "description": "Award-winning novel",
        "name": "Best Seller Book",
        "brand_id": 789,
        "is_taxable": false,
        "price": "19.99",
        "model": "ISBN-123456789",
        "images": [
          {
            "alt": "Book Cover",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/book.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/book.jpg"
            }
          }
        ],
        "errors": [],
        "shipping_estimate": "4.99",
        "rank": 10,
        "original_points": 2000,
        "brand": "PublishCo",
        "fulfillment_type": "physical",
        "is_primary": false,
        "tax_paid": "0.00",
        "shipping_paid": "4.99",
        "options": [],
        "product_id": "BOOK-001",
        "catalog_item_id": 34567,
        "price_paid": "0.00",
        "supplier_reference_id": "PC-BOOK-001",
        "is_available": true,
        "metadata": {},
        "required_fields": {
          "address_1": true,
          "address_2": false,
          "address_3": false,
          "address_4": false,
          "city": true,
          "country": true,
          "email": false,
          "given_name": true,
          "phone_number": false,
          "postal_code": true,
          "state_or_region": true,
          "surname": true
        },
        "supplier_id": 3001,
        "line_item_id": "550e8400-e29b-41d4-a716-446655440003",
        "is_limited_stock": false,
        "created_at": "2025-01-15T09:00:00Z",
        "original_price": "19.99"
      }
    ],
    "order_number": "C234-56789-ABCDE-0003",
    "phone_number": "+1-555-555-5555",
    "postal_code": "60601",
    "socket_id": 100,
    "state_or_region": "IL",
    "surname": "Johnson",
    "updated": "2025-01-15T14:00:00Z"
  },
  "success": true,
  "timestamp": "2025-01-15T14:30:00Z"
}
Virtual product order (gift card/code) 
{
  "order": {
    "address_1": "456 Oak Avenue",
    "city": "Los Angeles",
    "country": "US",
    "created": "2025-01-15T11:00:00Z",
    "email": "jane.smith@example.com",
    "external_order_id": "ORDER-2024-002",
    "external_user_id": "user-789",
    "fulfillments": [
      {
        "created_at": "2025-01-15T11:00:00Z",
        "delivered_date": "2025-01-15T11:05:00Z",
        "fulfillment_id": "FULFILL-002",
        "fulfillment_type": "digital",
        "line_item_ids": [
          "550e8400-e29b-41d4-a716-446655440002"
        ],
        "updated_at": "2025-01-15T11:05:00Z",
        "virtual_code_link": "https://redeem.example.com/gc/ABC123XYZ",
        "virtual_code_pin": "1234"
      }
    ],
    "given_name": "Jane",
    "is_test": false,
    "line_items": [
      {
        "product_options": {},
        "points": 10000,
        "is_explicit": false,
        "category_ids": [
          5,
          10
        ],
        "retail_price": "100.00",
        "points_paid": 0,
        "item_type_id": 300,
        "availability": "Always available",
        "tag_ids": [],
        "is_stock_reserved": false,
        "status": "fulfilled",
        "updated_at": "2025-01-15T11:05:00Z",
        "description": "Digital gift card",
        "name": "$100 Gift Card",
        "brand_id": 456,
        "is_taxable": false,
        "price": "100.00",
        "model": "GC-100-DIGITAL",
        "images": [
          {
            "alt": "Gift Card Image",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/gc.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/gc.jpg"
            }
          }
        ],
        "errors": [],
        "shipping_estimate": "0.00",
        "rank": 50,
        "original_points": 10000,
        "brand": "MegaStore",
        "fulfillment_type": "digital",
        "is_primary": false,
        "tax_paid": "0.00",
        "shipping_paid": "0.00",
        "options": [],
        "product_id": "GC-100",
        "catalog_item_id": 23456,
        "price_paid": "100.00",
        "supplier_reference_id": "MS-GC-100",
        "is_available": true,
        "metadata": {},
        "required_fields": {
          "address_1": false,
          "address_2": false,
          "address_3": false,
          "address_4": false,
          "city": false,
          "country": false,
          "email": true,
          "given_name": true,
          "phone_number": false,
          "postal_code": false,
          "state_or_region": false,
          "surname": true
        },
        "supplier_id": 2001,
        "line_item_id": "550e8400-e29b-41d4-a716-446655440002",
        "is_limited_stock": false,
        "created_at": "2025-01-15T11:00:00Z",
        "original_price": "100.00"
      }
    ],
    "order_number": "C234-56789-ABCDE-0002",
    "phone_number": "+1-555-987-6543",
    "postal_code": "90001",
    "socket_id": 100,
    "state_or_region": "CA",
    "surname": "Smith",
    "updated": "2025-01-15T11:05:00Z"
  },
  "success": true,
  "timestamp": "2025-01-15T14:30:00Z"
}
Response Schema
Schema Reference:

Response containing order tracking information

Type: object
Required fields:
success timestamp order

Properties:

order ref: Order required
success required
timestamp required
401 Authentication failed
Example Response 
{
  "error_code": "AUTHENTICATION_FAILED",
  "message": "Invalid or expired API token",
  "success": false,
  "timestamp": "2025-01-15T14:30:00Z"
}
Response Schema
Schema Reference:

Standard error response format

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required
404 Order not found
Order does not exist 
{
  "error_code": "ORDER_NOT_FOUND",
  "message": "Order not found",
  "success": false,
  "timestamp": "2025-01-15T14:30:00Z"
}
Order exists but external_user_id doesn't match 
{
  "error_code": "ORDER_NOT_FOUND",
  "message": "Order not found",
  "success": false,
  "timestamp": "2025-01-15T14:30:00Z"
}
Response Schema
Schema Reference:

Standard error response format

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required