Catalog API Documentation

Browse endpoints, parameters, and live request examples.

PUT /sockets/{socket_id}/cart/{external_user_id}/metadata

Update cart metadata

Sets or replaces the metadata for the cart. Creates the cart if it doesn’t exist. Metadata must be a flat map with string keys and string values only. Passing an empty object clears all metadata.

Cart

Parameters

socket_id required path (integer)

Socket/catalog identifier

external_user_id required path (string)

External user identifier

Request Body

Update metadata request

Properties

Field Type Required Description
metadata object Yes New metadata for the cart (replaces existing)

Example

{
  "metadata": {
    "budget_code": "MKT-Q1-2024",
    "department": "Marketing",
    "purchase_order": "PO-2024-002",
    "session_id": "sess_xyz789"
  }
}

Responses

200 Metadata updated successfully
All metadata cleared 
{
  "data": {
    "cart_version": "550e8400-e29b-41d4-a716-446655440012",
    "currency": "USD",
    "external_user_id": "user-123456",
    "is_locked": false,
    "line_items": [],
    "metadata": {},
    "socket_id": 10001,
    "total_line_items": 0,
    "unique_item_count": 0
  },
  "success": true,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Metadata successfully updated 
{
  "data": {
    "cart_version": "550e8400-e29b-41d4-a716-446655440011",
    "currency": "USD",
    "external_user_id": "user-123456",
    "is_locked": false,
    "line_items": [],
    "metadata": {
      "approval_status": "pending",
      "cost_center": "WEf333-001",
      "manager_id": "2938749823670",
      "project_code": "PROJ-2024-001"
    },
    "socket_id": 10001,
    "total_line_items": 0,
    "unique_item_count": 0
  },
  "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 metadata or cart is locked
Cart is locked 
{
  "error_code": "CART_LOCKED",
  "message": "Cart is locked",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Invalid metadata keys 
{
  "error_code": "INVALID_METADATA_KEYS",
  "message": "Metadata keys must be strings",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Invalid metadata type 
{
  "error_code": "INVALID_METADATA",
  "message": "Metadata must be a map/object",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Invalid metadata values 
{
  "error_code": "INVALID_METADATA_VALUES",
  "message": "Metadata values must be strings",
  "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 not found
Example Response 
{
  "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