Catalog API Documentation

Browse endpoints, parameters, and live request examples.

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

Convert cart to order

Converts the user’s cart into a confirmed order and initiates fulfillment. The cart must be validated and locked before this operation. Upon success, the cart is cleared and order tracking information is provided.

Cart

Parameters

socket_id required path (integer)

Socket identifier

external_user_id required path (string)

External user identifier

Request Body

Order placement request

Properties

Field Type Required Description
cart_version string Yes Cart version UUID to ensure cart hasn't changed
external_order_id string Yes External order ID for tracking
line_item_payments array of Yes Payment information for each line item in the cart
metadata object No New metadata for the cart (replaces existing)

Example

{
  "cart_version": "550e8400-e29b-41d4-a716-446655440000",
  "external_order_id": "ORDER-2024-001",
  "line_item_payments": [
    {
      "line_item_id": "550e8400-e29b-41d4-a716-446655440001",
      "points_paid": 500,
      "price_paid": "24.99"
    },
    {
      "line_item_id": "550e8400-e29b-41d4-a716-446655440002",
      "price_paid": "19.99"
    }
  ],
  "metadata": {
    "budget_code": "MKT-Q1-2024",
    "department": "Marketing",
    "purchase_order": "PO-2024-002",
    "session_id": "sess_xyz789"
  }
}

Responses

201 Order placed successfully
Order with points payment 
{
  "external_order_id": "PTS-ORDER-2024-002",
  "order_number": "CAT-20231201-164530-D4E5F6",
  "timestamp": "2023-12-01T16:45:30.567Z"
}
Order successfully placed 
{
  "external_order_id": "ORDER-2024-001",
  "order_number": "CAT-20231201-153045-A1B2C3",
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Type: object

Properties:

external_order_id
order_number
timestamp
400 Order placement failed
Cart not locked 
{
  "error_code": "CART_NOT_LOCKED",
  "message": "Cart must be validated and locked before placing order",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Cart version mismatch 
{
  "error_code": "CART_VERSION_MISMATCH",
  "message": "Cart version does not match current cart",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Payment validation failed - invalid decimal format 
{
  "error_code": "PAYMENT_VALIDATION_FAILED",
  "failed_items": [
    {
      "error_reason": "INVALID_DECIMAL_FORMAT",
      "field": "price_paid",
      "line_item_id": "550e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "message": "Payment validation failed",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Missing payment information 
{
  "error_code": "MISSING_LINE_ITEM_PAYMENTS",
  "message": "Payment information missing for one or more line items",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Payment validation failed - insufficient payment 
{
  "error_code": "PAYMENT_VALIDATION_FAILED",
  "failed_items": [
    {
      "catalog_item_id": 12345,
      "error_reason": "INSUFFICIENT_PAYMENT"
    }
  ],
  "message": "Payment validation failed",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Required address fields missing 
{
  "error_code": "REQUIRED_FIELDS_MISSING",
  "message": "Required fields missing: email, phone_number",
  "missing_fields": [
    "email",
    "phone_number"
  ],
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Error response for order placement failures

Type: object
404 Cart not found
Cart does not exist 
{
  "error_code": "CART_VALIDATION_FAILED",
  "message": "Cart not found",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Error response for order placement failures

Type: object
422 Cart validation issues
Items no longer available 
{
  "error_code": "CART_VALIDATION_FAILED",
  "failed_items": [
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "message": "Cart validation failed. Item validation errors: Item is no longer available in catalog",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Price has increased 
{
  "error_code": "CART_VALIDATION_FAILED",
  "failed_items": [
    "550e8400-e29b-41d4-a716-446655440003"
  ],
  "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 expired 
{
  "error_code": "CART_VALIDATION_FAILED",
  "failed_items": [
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "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 order placement failures

Type: object