DirectOrderRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/catalogapi-com/json-schema/catalogapi-com-direct-order-request-schema.json",
  "title": "DirectOrderRequest",
  "description": "Request body for placing an order directly without managing cart state.\n\nThis endpoint allows you to submit an entire order in a single API call,\nincluding items, shipping address, and payment details. The order is validated\nand placed immediately without creating or maintaining a cart session.\n\nAll items must be available and valid at the time of order placement.\nFor physical items, a complete shipping address is required.\n",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/catalogapi-com-openapi.yml#/components/schemas/DirectOrderRequest",
  "properties": {
    "external_order_id": {
      "description": "Your unique order identifier. Must be unique per customer. Used for order tracking and idempotency.",
      "type": "string"
    },
    "external_user_id": {
      "description": "Your user identifier for this order",
      "type": "string"
    },
    "items": {
      "description": "Array of items to order with payment information",
      "items": {
        "$ref": "#/$defs/DirectOrderItem"
      },
      "minItems": 1,
      "type": "array"
    },
    "metadata": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Order-level metadata (flat map with string values only). Can include PO numbers, department codes, etc.",
      "type": "object"
    },
    "shipping_address": {
      "description": "Shipping address information. Required fields depend on the items being ordered.\nPhysical items typically require full address details. Digital items may only require\nemail and name fields.\n",
      "properties": {
        "address_1": {
          "description": "Street address line 1",
          "type": "string"
        },
        "address_2": {
          "description": "Street address line 2",
          "type": "string"
        },
        "address_3": {
          "description": "Street address line 3",
          "type": "string"
        },
        "address_4": {
          "description": "Street address line 4",
          "type": "string"
        },
        "city": {
          "description": "City",
          "type": "string"
        },
        "country": {
          "description": "Country code (e.g., 'US', 'GB', 'CA')",
          "type": "string"
        },
        "email": {
          "description": "Contact email",
          "format": "email",
          "type": "string"
        },
        "given_name": {
          "description": "Recipient's first name",
          "type": "string"
        },
        "phone_number": {
          "description": "Contact phone",
          "type": "string"
        },
        "postal_code": {
          "description": "ZIP/Postal code",
          "type": "string"
        },
        "state_or_region": {
          "description": "State/Province/Region",
          "type": "string"
        },
        "surname": {
          "description": "Recipient's last name",
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "external_user_id",
    "external_order_id",
    "items"
  ],
  "type": "object",
  "$defs": {
    "DirectOrderItem": {
      "description": "Single item to order directly with payment information.\n\nEach item must include the catalog_item_id and payment details. The price_paid\nshould reflect what the end-user has paid.  Must be greater than or equal to the catalog price.\nPoints, tax, and shipping are optional depending on your business logic.\n",
      "properties": {
        "catalog_item_id": {
          "description": "Catalog item ID to order",
          "type": "integer"
        },
        "metadata": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Metadata for this line item (flat map with string values only)",
          "type": "object"
        },
        "points_paid": {
          "default": 0,
          "description": "Points paid for this item (optional)",
          "type": [
            "integer",
            "null"
          ]
        },
        "price_paid": {
          "description": "Price paid for this item (e.g., '24.99')",
          "format": "decimal",
          "type": "string"
        },
        "shipping_paid": {
          "description": "Shipping paid for this item (optional)",
          "format": "decimal",
          "type": [
            "string",
            "null"
          ]
        },
        "tax_paid": {
          "description": "Tax paid for this item (optional)",
          "format": "decimal",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "catalog_item_id",
        "price_paid"
      ],
      "title": "DirectOrderItem",
      "type": "object"
    }
  }
}