Catalog API Documentation

Browse endpoints, parameters, and live request examples.

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

Add line items to cart

Adds one or more line items to the cart with a unique UUID. Each line item represents one unit of a product and can have its own metadata for personalization, tracking, and downstream order processing.

Cart

Parameters

socket_id required path (integer)

Socket identifier

external_user_id required path (string)

External user identifier

Request Body

Add items request

Properties

Field Type Required Description
items array of Yes Array of items to add to cart

Example

{
  "items": [
    {
      "catalog_item_id": 12345,
      "line_item_id": "custom-id-123",
      "metadata": {
        "cost_center": "WEf333-001",
        "manager_id": "2938749823670"
      }
    }
  ]
}

Responses

200 Items added successfully
Example Response 
{
  "cart": {
    "address_1": "123 Main Street",
    "address_2": "Apt 4B",
    "address_3": null,
    "address_4": null,
    "cart_version": "550e8400-e29b-41d4-a716-446655440010",
    "city": "Springfield",
    "country": "US",
    "currency": "USD",
    "email": "john.smith@example.com",
    "given_name": "John",
    "is_locked": false,
    "line_items": [
      {
        "product_options": {
          "10000013": [
            {
              "order": "1",
              "slug": "color",
              "translations": [
                {
                  "language": "en-US",
                  "option_name": "Color",
                  "value_name": "Navy"
                }
              ],
              "value": "navy"
            },
            {
              "order": "2",
              "slug": "size",
              "translations": [
                {
                  "language": "en-US",
                  "option_name": "Size",
                  "value_name": "Medium"
                }
              ],
              "value": "medium"
            }
          ]
        },
        "points": 26158,
        "is_explicit": false,
        "category_ids": [
          201,
          202
        ],
        "retail_price": "349.99",
        "item_type_id": 1,
        "availability": "IN_STOCK",
        "tag_ids": [
          101,
          102,
          103
        ],
        "is_stock_reserved": false,
        "stock_reserved_until": null,
        "description": "Professional-grade outdoor jacket designed for all weather conditions",
        "name": "All-Weather Outdoor Jacket",
        "brand_id": 123,
        "is_taxable": true,
        "price": "261.58",
        "model": "JACKET-001",
        "images": [
          {
            "alt": "All-Weather Outdoor Jacket - Front View",
            "is_primary": true,
            "order": 1,
            "urls": {
              "image_150_1_1": "https://cdn.example.com/img/150/jacket-front.jpg",
              "image_150_3_2": "https://cdn.example.com/img/150c/jacket-front.jpg",
              "image_300_1_1": "https://cdn.example.com/img/300/jacket-front.jpg",
              "image_300_3_2": "https://cdn.example.com/img/300c/jacket-front.jpg",
              "image_500_1_1": "https://cdn.example.com/img/500/jacket-front.jpg",
              "image_500_3_2": "https://cdn.example.com/img/500c/jacket-front.jpg",
              "image_75_1_1": "https://cdn.example.com/img/75/jacket-front.jpg",
              "image_75_3_2": "https://cdn.example.com/img/75c/jacket-front.jpg"
            }
          }
        ],
        "errors": [],
        "shipping_estimate": "7.99",
        "rank": 1,
        "original_points": 29999,
        "brand": "OutdoorGearPro",
        "fulfillment_type": "SHIP",
        "is_primary": false,
        "options": [],
        "product_id": "3ddd1114-1114-1114-1114-111411141114",
        "catalog_item_id": 10000013,
        "supplier_reference_id": "OGP-JACKET-001",
        "is_available": true,
        "metadata": {
          "gift_message": "Happy Birthday!",
          "personalization": "John Smith"
        },
        "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": 789,
        "line_item_id": "550e8400-e29b-41d4-a716-446655440001",
        "is_limited_stock": false,
        "original_price": "299.99"
      }
    ],
    "metadata": {},
    "phone_number": "555-123-4567",
    "postal_code": "62701",
    "state_or_region": "IL",
    "surname": "Smith",
    "total": "269.57",
    "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 Invalid request
Cart limit exceeded 
{
  "error_code": "CART_LIMIT_EXCEEDED",
  "message": "Cart cannot exceed 100 items",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Invalid metadata format 
{
  "error_code": "INVALID_METADATA",
  "message": "Metadata values must be strings",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Missing items array 
{
  "error_code": "INVALID_REQUEST",
  "message": "Request must include 'items' array",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Error response for invalid requests

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required
404 Socket or item not found
Some items not found 
{
  "error_code": "ITEMS_NOT_FOUND",
  "items": [
    12345,
    67890
  ],
  "message": "Some items not found",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Socket not found 
{
  "error_code": "SOCKET_NOT_FOUND",
  "message": "Socket 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