Catalog API Documentation

Browse endpoints, parameters, and live request examples.

POST /sockets/{socket_id}/cart/{external_user_id}/validate

Validate cart for checkout

Validates that all items in the cart are still available in the catalog and checks that all required fields are present. This should be called before proceeding to order placement.

Optionally locks the cart to prevent further modifications before order placement. Items that are no longer available will be flagged with errors but remain in the cart.

Cart

Parameters

socket_id required path (integer)

Socket identifier

external_user_id required path (string)

External user identifier

Request Body

Validate cart request

Properties

Field Type Required Description
lock boolean No Whether to lock the cart after successful validation. Set to true when you are about to place an order and want to make sure no edits can be made.

Example

{
  "lock": true
}

Responses

200 Cart validated successfully
Cart validated and locked for checkout 
{
  "cart": {
    "address_1": "123 Main Street",
    "address_2": "Apt 5A",
    "address_3": null,
    "address_4": null,
    "cart_version": "550e8400-e29b-41d4-a716-446655440050",
    "city": "New York",
    "country": "US",
    "currency": "USD",
    "email": "john.doe@example.com",
    "given_name": "John",
    "is_locked": true,
    "line_items": [
      {
        "product_options": {},
        "points": 24999,
        "is_explicit": false,
        "category_ids": [
          10,
          25
        ],
        "retail_price": "349.99",
        "item_type_id": 200,
        "availability": "IN_STOCK",
        "tag_ids": [
          35,
          78
        ],
        "is_stock_reserved": true,
        "stock_reserved_until": "2023-12-01T16:00:45.123Z",
        "description": "High-end noise-canceling wireless headphones",
        "name": "Premium Wireless Headphones",
        "brand_id": 456,
        "is_taxable": true,
        "price": "249.99",
        "model": "AP-WH-PREMIUM",
        "images": [
          {
            "alt": "Premium Wireless Headphones",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/12345.jpg",
              "image_150_3_2": "https://cdn.example.com/img/150c/12345.jpg",
              "image_300_1_1": "https://cdn.example.com/img/300/12345.jpg",
              "image_300_3_2": "https://cdn.example.com/img/300c/12345.jpg",
              "image_500_1_1": "https://cdn.example.com/img/500/12345.jpg",
              "image_500_3_2": "https://cdn.example.com/img/500c/12345.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/12345.jpg",
              "image_75_3_2": "https://cdn.example.com/img/75c/12345.jpg"
            }
          }
        ],
        "errors": [],
        "available": true,
        "shipping_estimate": "7.99",
        "rank": 100,
        "original_points": 29999,
        "brand": "AudioPro",
        "fulfillment_type": "SHIP",
        "is_primary": false,
        "options": [],
        "product_id": "premium-headphones-001",
        "catalog_item_id": 12345,
        "supplier_reference_id": "SUP-AP-PREMIUM",
        "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": 1001,
        "line_item_id": "22687a62-27f9-4b60-9a8c-af394729d423",
        "is_limited_stock": false,
        "original_price": "299.99"
      }
    ],
    "metadata": {},
    "phone_number": "555-123-4567",
    "postal_code": "10001",
    "state_or_region": "NY",
    "surname": "Doe",
    "total": "272.49",
    "total_line_items": 1,
    "unique_item_count": 1
  },
  "errors": [],
  "success": true,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Cart validated but not locked 
{
  "cart": {
    "address_1": "456 Oak Avenue",
    "address_2": null,
    "address_3": null,
    "address_4": null,
    "cart_version": "550e8400-e29b-41d4-a716-446655440051",
    "city": "Los Angeles",
    "country": "US",
    "currency": "USD",
    "email": "jane.smith@example.com",
    "given_name": "Jane",
    "is_locked": false,
    "line_items": [
      {
        "product_options": {},
        "points": 14999,
        "is_explicit": false,
        "category_ids": [
          15,
          20
        ],
        "retail_price": "199.99",
        "item_type_id": 200,
        "availability": "IN_STOCK",
        "tag_ids": [
          40,
          55
        ],
        "is_stock_reserved": false,
        "stock_reserved_until": null,
        "description": "Wireless Bluetooth speaker with excellent sound quality",
        "name": "Bluetooth Speaker",
        "brand_id": 567,
        "is_taxable": true,
        "price": "149.99",
        "model": "BT-SPEAKER-001",
        "images": [
          {
            "alt": "Bluetooth Speaker",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/67890.jpg",
              "image_150_3_2": "https://cdn.example.com/img/150c/67890.jpg",
              "image_300_1_1": "https://cdn.example.com/img/300/67890.jpg",
              "image_300_3_2": "https://cdn.example.com/img/300c/67890.jpg",
              "image_500_1_1": "https://cdn.example.com/img/500/67890.jpg",
              "image_500_3_2": "https://cdn.example.com/img/500c/67890.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/67890.jpg",
              "image_75_3_2": "https://cdn.example.com/img/75c/67890.jpg"
            }
          }
        ],
        "errors": [],
        "available": true,
        "shipping_estimate": "7.99",
        "rank": 200,
        "original_points": 17999,
        "brand": "AudioTech",
        "fulfillment_type": "SHIP",
        "is_primary": false,
        "options": [],
        "product_id": "bluetooth-speaker-001",
        "catalog_item_id": 67890,
        "supplier_reference_id": "SUP-BT-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": 1002,
        "line_item_id": "33798b73-38fa-5c71-0b9d-bf405840e534",
        "is_limited_stock": false,
        "original_price": "179.99"
      }
    ],
    "metadata": {},
    "phone_number": "555-987-6543",
    "postal_code": "90001",
    "state_or_region": "CA",
    "surname": "Smith",
    "total": "149.99",
    "total_line_items": 1,
    "unique_item_count": 1
  },
  "errors": [],
  "success": true,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Response containing the current state of a user's cart

Type: object
Required fields:
success timestamp cart

Properties:

cart ref: Cart required
errors
matched_entities
success required
timestamp required
400 Validation failed
Cart is already locked 
{
  "error_code": "CART_VALIDATION_FAILED",
  "failed_items": {},
  "message": "Cart is already locked",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Cart is empty 
{
  "error_code": "CART_VALIDATION_FAILED",
  "failed_items": {},
  "message": "Cart is empty",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Some items are no longer available 
{
  "cart": {
    "address_1": null,
    "address_2": null,
    "address_3": null,
    "address_4": null,
    "cart_version": "550e8400-e29b-41d4-a716-446655440052",
    "city": null,
    "country": null,
    "currency": "USD",
    "email": null,
    "given_name": null,
    "is_locked": false,
    "line_items": [
      {
        "product_options": {},
        "points": 24999,
        "is_explicit": false,
        "category_ids": [
          10,
          25
        ],
        "retail_price": "349.99",
        "item_type_id": 200,
        "availability": "OUT_OF_STOCK",
        "tag_ids": [
          35
        ],
        "is_stock_reserved": false,
        "stock_reserved_until": null,
        "description": "High-quality wireless headphones",
        "name": "Premium Headphones",
        "brand_id": 123,
        "is_taxable": true,
        "price": "249.99",
        "model": "AT-PH100",
        "images": [
          {
            "alt": "Premium Headphones",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/12345.jpg",
              "image_150_3_2": "https://cdn.example.com/img/150c/12345.jpg",
              "image_300_1_1": "https://cdn.example.com/img/300/12345.jpg",
              "image_300_3_2": "https://cdn.example.com/img/300c/12345.jpg",
              "image_500_1_1": "https://cdn.example.com/img/500/12345.jpg",
              "image_500_3_2": "https://cdn.example.com/img/500c/12345.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/12345.jpg",
              "image_75_3_2": "https://cdn.example.com/img/75c/12345.jpg"
            }
          }
        ],
        "errors": [
          "Item is no longer available in catalog"
        ],
        "available": false,
        "shipping_estimate": "7.99",
        "rank": 100,
        "original_points": 29999,
        "brand": "AudioTech",
        "fulfillment_type": "SHIP",
        "is_primary": false,
        "options": [],
        "product_id": "PROD-12345",
        "catalog_item_id": 12345,
        "supplier_reference_id": "SUP-PH-100",
        "is_available": false,
        "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": 1001,
        "line_item_id": "22687a62-27f9-4b60-9a8c-af394729d423",
        "is_limited_stock": false,
        "original_price": "299.99"
      }
    ],
    "metadata": {},
    "phone_number": null,
    "postal_code": null,
    "state_or_region": null,
    "surname": null,
    "total": "249.99",
    "total_line_items": 1,
    "unique_item_count": 1
  },
  "error_code": "ITEMS_UNAVAILABLE",
  "errors": [
    "Item 'Premium Headphones' is no longer available"
  ],
  "failed_items": {
    "22687a62-27f9-4b60-9a8c-af394729d423": [
      "ITEM_UNAVAILABLE"
    ]
  },
  "message": "Some items in your cart are no longer available",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Missing required address fields 
{
  "cart": {
    "address_1": null,
    "address_2": null,
    "address_3": null,
    "address_4": null,
    "cart_version": "550e8400-e29b-41d4-a716-446655440053",
    "city": null,
    "country": null,
    "currency": "USD",
    "email": null,
    "given_name": "John",
    "is_locked": false,
    "line_items": [
      {
        "product_options": {},
        "points": 9999,
        "is_explicit": false,
        "category_ids": [
          100
        ],
        "retail_price": "99.99",
        "item_type_id": 300,
        "availability": "IN_STOCK",
        "tag_ids": [
          50
        ],
        "is_stock_reserved": false,
        "stock_reserved_until": null,
        "description": "Digital gift card for catalog purchases",
        "name": "Gift Card",
        "brand_id": 999,
        "is_taxable": false,
        "price": "99.99",
        "model": "GC-DIGITAL",
        "images": [
          {
            "alt": "Gift Card",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/giftcard.jpg",
              "image_150_3_2": "https://cdn.example.com/img/150c/giftcard.jpg",
              "image_300_1_1": "https://cdn.example.com/img/300/giftcard.jpg",
              "image_300_3_2": "https://cdn.example.com/img/300c/giftcard.jpg",
              "image_500_1_1": "https://cdn.example.com/img/500/giftcard.jpg",
              "image_500_3_2": "https://cdn.example.com/img/500c/giftcard.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/giftcard.jpg",
              "image_75_3_2": "https://cdn.example.com/img/75c/giftcard.jpg"
            }
          }
        ],
        "errors": [
          "Missing required address fields: email, phone_number"
        ],
        "available": true,
        "shipping_estimate": "0.00",
        "rank": 200,
        "original_points": 9999,
        "brand": "Store Brand",
        "fulfillment_type": "DIGITAL",
        "is_primary": false,
        "options": [],
        "product_id": "gift-card-001",
        "catalog_item_id": 11111,
        "supplier_reference_id": "SUP-GC-001",
        "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": true,
          "postal_code": false,
          "state_or_region": false,
          "surname": true
        },
        "supplier_id": 2000,
        "line_item_id": "44909c84-49fb-6d82-1cae-cf516951f645",
        "is_limited_stock": false,
        "original_price": "99.99"
      }
    ],
    "metadata": {},
    "phone_number": null,
    "postal_code": null,
    "state_or_region": null,
    "surname": "Doe",
    "total": "99.99",
    "total_line_items": 1,
    "unique_item_count": 1
  },
  "error_code": "CART_VALIDATION_FAILED",
  "errors": [
    "Cart validation failed. Missing required address fields: email, phone_number"
  ],
  "failed_items": {
    "44909c84-49fb-6d82-1cae-cf516951f645": [
      "MISSING_REQUIRED_ADDRESS_FIELDS"
    ]
  },
  "message": "Cart validation failed. Missing required address fields: email, phone_number",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Price has increased since item was added 
{
  "cart": {
    "address_1": null,
    "address_2": null,
    "address_3": null,
    "address_4": null,
    "cart_version": "550e8400-e29b-41d4-a716-446655440052",
    "city": null,
    "country": null,
    "currency": "USD",
    "email": null,
    "given_name": null,
    "is_locked": false,
    "line_items": [
      {
        "product_options": {},
        "points": 24999,
        "is_explicit": false,
        "category_ids": [
          10,
          25
        ],
        "retail_price": "349.99",
        "item_type_id": 200,
        "availability": "IN_STOCK",
        "tag_ids": [
          35,
          78
        ],
        "is_stock_reserved": false,
        "stock_reserved_until": null,
        "description": "High-end noise-canceling wireless headphones",
        "name": "Premium Wireless Headphones",
        "brand_id": 456,
        "is_taxable": true,
        "price": "249.99",
        "model": "AP-WH-PREMIUM",
        "images": [
          {
            "alt": "Premium Wireless Headphones",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/12345.jpg",
              "image_150_3_2": "https://cdn.example.com/img/150c/12345.jpg",
              "image_300_1_1": "https://cdn.example.com/img/300/12345.jpg",
              "image_300_3_2": "https://cdn.example.com/img/300c/12345.jpg",
              "image_500_1_1": "https://cdn.example.com/img/500/12345.jpg",
              "image_500_3_2": "https://cdn.example.com/img/500c/12345.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/12345.jpg",
              "image_75_3_2": "https://cdn.example.com/img/75c/12345.jpg"
            }
          }
        ],
        "errors": [
          "Price has increased from 249.99 to 299.99"
        ],
        "available": true,
        "shipping_estimate": "7.99",
        "rank": 100,
        "original_points": 29999,
        "brand": "AudioPro",
        "fulfillment_type": "SHIP",
        "is_primary": false,
        "options": [],
        "product_id": "premium-headphones-001",
        "catalog_item_id": 12345,
        "supplier_reference_id": "SUP-AP-PREMIUM",
        "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": 1001,
        "line_item_id": "22687a62-27f9-4b60-9a8c-af394729d423",
        "is_limited_stock": false,
        "original_price": "299.99"
      }
    ],
    "metadata": {},
    "phone_number": null,
    "postal_code": null,
    "state_or_region": null,
    "surname": null,
    "total": "249.99",
    "total_line_items": 1,
    "unique_item_count": 1
  },
  "error_code": "CART_VALIDATION_FAILED",
  "errors": [
    "Cart validation failed. Item validation errors: Price has increased from 249.99 to 299.99"
  ],
  "failed_items": {
    "22687a62-27f9-4b60-9a8c-af394729d423": [
      "PRICE_CHANGED"
    ]
  },
  "message": "Cart validation failed. Item validation errors: Price has increased from 249.99 to 299.99",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Stock reservation has expired 
{
  "cart": {
    "address_1": null,
    "address_2": null,
    "address_3": null,
    "address_4": null,
    "cart_version": "550e8400-e29b-41d4-a716-446655440054",
    "city": null,
    "country": null,
    "currency": "USD",
    "email": null,
    "given_name": null,
    "is_locked": false,
    "line_items": [
      {
        "product_options": {},
        "points": 199999,
        "is_explicit": false,
        "category_ids": [
          50,
          75
        ],
        "retail_price": "2199.99",
        "item_type_id": 150,
        "availability": "OUT_OF_STOCK",
        "tag_ids": [
          15,
          90
        ],
        "is_stock_reserved": false,
        "stock_reserved_until": null,
        "description": "Limited edition gaming console with exclusive features",
        "name": "Limited Edition Gaming Console",
        "brand_id": 777,
        "is_taxable": true,
        "price": "1999.99",
        "model": "GT-CONSOLE-LE",
        "images": [
          {
            "alt": "Limited Edition Gaming Console",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/console.jpg",
              "image_150_3_2": "https://cdn.example.com/img/150c/console.jpg",
              "image_300_1_1": "https://cdn.example.com/img/300/console.jpg",
              "image_300_3_2": "https://cdn.example.com/img/300c/console.jpg",
              "image_500_1_1": "https://cdn.example.com/img/500/console.jpg",
              "image_500_3_2": "https://cdn.example.com/img/500c/console.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/console.jpg",
              "image_75_3_2": "https://cdn.example.com/img/75c/console.jpg"
            }
          }
        ],
        "errors": [
          "Stock reservation has expired"
        ],
        "available": false,
        "shipping_estimate": "19.99",
        "rank": 50,
        "original_points": 199999,
        "brand": "GameTech",
        "fulfillment_type": "SHIP",
        "is_primary": false,
        "options": [],
        "product_id": "gaming-console-limited",
        "catalog_item_id": 88888,
        "supplier_reference_id": "SUP-GT-CONSOLE",
        "is_available": false,
        "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": 3000,
        "line_item_id": "55abc733-28fb-7d91-2dbe-df617062f756",
        "is_limited_stock": true,
        "original_price": "1999.99"
      }
    ],
    "metadata": {},
    "phone_number": null,
    "postal_code": null,
    "state_or_region": null,
    "surname": null,
    "total": "1999.99",
    "total_line_items": 1,
    "unique_item_count": 1
  },
  "error_code": "STOCK_RESERVATIONS_EXPIRED",
  "errors": [
    "Cart validation failed. Item validation errors: Stock reservation has expired"
  ],
  "failed_items": {
    "55abc733-28fb-7d91-2dbe-df617062f756": [
      "RESERVATION_EXPIRED"
    ]
  },
  "message": "Cart validation failed. Item validation errors: Stock reservation has expired",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Error response for cart validation failures

Type: object
404 Socket or cart not found
Example Response 
{
  "error_code": "NOT_FOUND",
  "message": "The requested resource was not found.",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Error response when requested resource is not found

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required