Create Order

Creates a new order in Carriyo with the specified line items and customer details.

Order Creation Flow

When you create an order:

  1. Carriyo validates the request and creates the order
  2. Fulfillment orders are generated based on your specifications or automatic allocation
  3. Inventory is reserved for the allocated items
  4. Webhooks are triggered to notify your systems

Fulfillment Order Allocation

You can control how fulfillment orders are created:

  • Automatic: Omit fulfillment_orders and Carriyo allocates based on inventory and rules
  • Manual: Specify fulfillment_orders to control which items go to which locations

Line Items

Each line item represents a product in the order with:

  • Product identification (SKU, product ID)
  • Quantity ordered
  • Pricing information
  • Custom attributes

Response

The API returns the complete order object including:

  • Generated order_id for future reference
  • Fulfillment orders with their allocations
  • Initial order status
SecurityOAuth2-Production or OAuth2-Demo
Request
header Parameters
x-api-key
required
string

Your Carriyo API key for authentication.

tenant-id
required
string

Your unique tenant identifier in Carriyo.

Content-Type
string
Default: application/json
Request Body schema: application/json
required
merchant
required
string

The merchant identifier for this order.

partner_order_reference
string

Your system's unique order reference for correlation.

language
string

Language code for customer communications (e.g., "en", "ar").

order_date
string <date-time>

The date when the order was placed (ISO 8601 format).

sales_channel
string

The sales channel where the order originated (e.g., "web", "mobile", "store").

Array of objects (Carriyo Metadata)

Custom key-value metadata for the order.

object (Address)
object (Address)
object (Address)
object (Order Payment)
taxes_included
boolean

Whether prices include taxes.

duties_included
boolean

Whether prices include duties.

Array of objects (Discount Application)

Discounts applied to the order.

required
Array of objects (Line Item)

Products ordered with quantities and prices.

Array of objects (Fulfillment Order Request)

Optional explicit fulfillment order specifications.

Array of objects (Shipping Line)

Shipping methods and costs.

Responses
201

Order created successfully.

400

Invalid request payload.

post/orders
Request samples
application/json
{
  • "merchant": "string",
  • "partner_order_reference": "string",
  • "language": "string",
  • "order_date": "2019-08-24T14:15:22Z",
  • "sales_channel": "string",
  • "carriyo_metadata": [
    ],
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "customer": {
    },
  • "payment": {
    },
  • "taxes_included": true,
  • "duties_included": true,
  • "discount_applications": [
    ],
  • "line_items": [
    ],
  • "fulfillment_orders": [
    ],
  • "shipping_lines": [
    ]
}
Response samples
application/json
{
  • "tenant": "string",
  • "order_id": "string",
  • "merchant": "string",
  • "partner_order_reference": "string",
  • "language": "string",
  • "order_date": "2019-08-24T14:15:22Z",
  • "sales_channel": "string",
  • "creation_source": {
    },
  • "update_source": {
    },
  • "carriyo_metadata": [
    ],
  • "status": "open",
  • "auto_allocation_failed": true,
  • "cancellation_reason": "CUSTOMER_CANCELLATION",
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "customer": {
    },
  • "payment": {
    },
  • "redacted": true,
  • "taxes_included": true,
  • "duties_included": true,
  • "discount_applications": [
    ],
  • "line_items": [
    ],
  • "fulfillment_orders": [
    ],
  • "shipping_lines": [
    ],
  • "error_details": [
    ],
  • "creation_date": "2019-08-24T14:15:22Z",
  • "update_date": "2019-08-24T14:15:22Z"
}