Catalog API Documentation

Browse endpoints, parameters, and live request examples.

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

Set shipping address for cart

Sets or updates the shipping address for the cart. The cart will be created if it doesn’t exist. All address fields are optional but recommended for accurate shipping calculations and order fulfillment.

Email validation: If an email address is provided, it must be in a valid format (must contain @ sign with no spaces). Invalid email formats will return a 422 error. Empty email fields or omitted email fields are allowed.

Some items may require specific address fields based on their fulfillment type. Check the item’s required_fields to ensure all necessary information is provided.

Cart

Parameters

socket_id required path (integer)

Socket identifier

external_user_id required path (string)

External user identifier

Request Body

Shipping address

Properties

Field Type Required Description
address_1 string No Street address line 1
address_2 string No Street address line 2
address_3 string No Street address line 3
address_4 string No Street address line 4
city string No City
country string No Country code (e.g., 'US', 'GB', 'CA')
email string No Contact email. If provided and not empty, must be a valid email format with @ sign and no spaces. Returns 422 if invalid. Empty string is allowed.
given_name string No Recipient's first name
phone_number string No Contact phone
postal_code string No ZIP/Postal code
state_or_region string No State/Province/Region
surname string No Recipient's last name

Example

{
  "address_1": "123 Main Street",
  "address_2": "Apt 4B",
  "city": "New York",
  "country": "US",
  "email": "john.doe@example.com",
  "given_name": "John",
  "phone_number": "555-123-4567",
  "postal_code": "10001",
  "state_or_region": "NY",
  "surname": "Doe"
}

Responses

200 Address set successfully
Complete address with all fields 
{
  "cart": {
    "address_1": "123 Main Street",
    "address_2": "Apt 4B",
    "address_3": "Building C",
    "address_4": "Floor 2",
    "cart_version": "550e8400-e29b-41d4-a716-446655440020",
    "city": "New York",
    "country": "US",
    "currency": "USD",
    "email": "john.doe@example.com",
    "given_name": "John",
    "is_locked": false,
    "line_items": [],
    "metadata": {},
    "phone_number": "555-123-4567",
    "postal_code": "10001",
    "state_or_region": "NY",
    "surname": "Doe",
    "total": "249.99",
    "total_line_items": 0,
    "unique_item_count": 0
  },
  "errors": [],
  "success": true,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Minimal address (name and city only) 
{
  "cart": {
    "cart_version": "550e8400-e29b-41d4-a716-446655440021",
    "city": "Los Angeles",
    "country": "US",
    "currency": "USD",
    "given_name": "Jane",
    "is_locked": false,
    "line_items": [],
    "metadata": {},
    "state_or_region": "CA",
    "surname": "Smith",
    "total": "0.00",
    "total_line_items": 0,
    "unique_item_count": 0
  },
  "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 Cart is locked
Example Response 
{
  "error_code": "CART_LOCKED",
  "message": "Cart is locked",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
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 Socket 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
422 Invalid address data (e.g., invalid email format)
Example Response 
{
  "error_code": "UNPROCESSABLE_ENTITY",
  "message": "email: must have the @ sign and no spaces",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Error response when entity cannot be processed

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required