Catalog API Documentation

Browse endpoints, parameters, and live request examples.

POST /sockets/{socket_id}/orders/place_direct

Place order directly without cart

Places an order directly in a single API call without managing cart state.

This endpoint allows you to submit an entire order including items, shipping address, and payment details. The order is validated and placed immediately without creating or maintaining a cart session.

Instead of implementing each cart step, the call will:

  1. Validate all items are available in the catalog
  2. Validate shipping address requirements
  3. Create and submit the order

Important notes:

  • All items must be available at order placement time
  • Physical items require complete shipping address
  • Digital items may only require email and name
  • Returns same response format as cart-based ordering
Order

Parameters

socket_id required path (integer)

Socket identifier

Request Body

Direct order request

Properties

Field Type Required Description
external_order_id string Yes Your unique order identifier. Must be unique per customer. Used for order tracking and idempotency.
external_user_id string Yes Your user identifier for this order
items array of Yes Array of items to order with payment information
metadata object No Order-level metadata (flat map with string values only). Can include PO numbers, department codes, etc.
shipping_address object No Shipping address information. Required fields depend on the items being ordered. Physical items typically require full address details. Digital items may only require email and name fields.

Example

{
  "external_order_id": "ORDER-2025-001",
  "external_user_id": "user-456",
  "items": [
    {
      "catalog_item_id": 12345,
      "metadata": {
        "cost_center": "163-HR"
      },
      "points_paid": 4999,
      "price_paid": "49.99",
      "shipping_paid": "9.99",
      "tax_paid": "4.50"
    }
  ],
  "metadata": {
    "budget_code": "MKT-Q1-2025",
    "department": "Marketing",
    "purchase_order": "PO-2025-002"
  },
  "shipping_address": {
    "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

201 Order placed successfully
Order successfully placed 
{
  "external_order_id": "ORDER-2025-001",
  "order_number": "C234-56789-ABCDE-0001",
  "timestamp": "2025-01-15T14:30:45.123Z"
}
Response Schema
Type: object

Properties:

external_order_id
order_number
timestamp
400 Order placement failed - validation errors
Invalid decimal format in payment fields 
{
  "error_code": "PAYMENT_VALIDATION_FAILED",
  "errors": [
    {
      "error_reason": "INVALID_DECIMAL_FORMAT",
      "field": "price_paid",
      "line_item_id": "550e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "message": "Payment validation failed",
  "success": false,
  "timestamp": "2025-01-15T14:30:45.123Z"
}
Items no longer available 
{
  "error_code": "ITEMS_UNAVAILABLE",
  "message": "One or more items are not available",
  "success": false,
  "timestamp": "2025-01-15T14:30:45.123Z",
  "unavailable_items": [
    12345,
    12346
  ]
}
Missing payment information 
{
  "error_code": "MISSING_LINE_ITEM_PAYMENTS",
  "errors": [
    "All items must have corresponding payment information"
  ],
  "message": "Payment information required for all items",
  "success": false,
  "timestamp": "2025-01-15T14:30:45.123Z"
}
Payment validation failed 
{
  "error_code": "PAYMENT_VALIDATION_FAILED",
  "errors": [
    {
      "catalog_item_id": 12345,
      "error_reason": "INSUFFICIENT_PAYMENT"
    }
  ],
  "message": "Payment validation failed",
  "success": false,
  "timestamp": "2025-01-15T14:30:45.123Z"
}
Required address fields missing 
{
  "error_code": "REQUIRED_FIELDS_MISSING",
  "message": "Required fields missing: address_1, city, postal_code",
  "missing_fields": [
    "address_1",
    "city",
    "postal_code"
  ],
  "success": false,
  "timestamp": "2025-01-15T14:30:45.123Z"
}
Response Schema
Schema Reference:

Error response for order placement failures

Type: object
404 Socket not found
Example Response 
{
  "error_code": "SOCKET_NOT_FOUND",
  "message": "Socket not found",
  "success": false,
  "timestamp": "2025-01-15T14: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
409 Duplicate order
Example Response 
{
  "error_code": "DUPLICATE_ORDER",
  "message": "Order with this external_order_id already exists",
  "success": false,
  "timestamp": "2025-01-15T14:30:45.123Z"
}
Response Schema
Schema Reference:

Error response for conflict situations (409 status)

Type: object
Required fields:
success message error_code timestamp

Properties:

error_code required
message required
success required
timestamp required
422 Validation failed
Invalid catalog items 
{
  "error_code": "VALIDATION_FAILED",
  "errors": [
    "Catalog item 99999 not found"
  ],
  "message": "Invalid catalog items",
  "success": false,
  "timestamp": "2025-01-15T14: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