Create Order

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

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

Delivery Method

Each fulfillment order can have one of three delivery methods:

  • DELIVERY — Standard delivery to the customer's address (delivery_address + delivery_schedule)
  • COLLECTION — Customer collects from a pickup point (customer_collection_address + customer_collection_schedule)
  • DIGITAL — No physical delivery; fulfilled digitally

The top-level delivery_method, delivery_type, delivery_address, delivery_schedule, customer_collection_address, and customer_collection_schedule are request-only convenience fields — they are propagated to each auto-allocated fulfillment order and persisted there, but are not stored on the Order itself. To set them per fulfillment order, provide them inside each entry of the fulfillment_orders array.

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 (id, sku, product_id, barcode)
  • Quantity ordered
  • Pricing information (unit_price, unit_cost, taxes, duties, discount allocations)
  • Physical attributes (weight, dimension, dangerous_goods, battery)

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
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.

delivery_method
string (Delivery Method)

The delivery method to apply to all auto-allocated fulfillment orders.

Request-only field — stored on each fulfillment order, not on the Order.

Enum: "DELIVERY" "COLLECTION" "DIGITAL"
delivery_type
string

The delivery service level (e.g., standard, express, same_day). Configurable per tenant. Only applicable when delivery_method is DELIVERY.

Request-only field — stored on each fulfillment order, not on the Order.

object (Address)

The address where the order should be delivered. Used when delivery_method is DELIVERY.

Request-only field — stored on each fulfillment order, not on the Order.

object (Fulfillment Order Schedule)

The scheduled delivery window. Only applicable when delivery_method is DELIVERY.

Request-only field — stored on each fulfillment order, not on the Order.

object (Address)

The address from which the customer will collect the order (e.g., a store, locker, or pickup point). Only applicable when delivery_method is COLLECTION.

Request-only field — stored on each fulfillment order, not on the Order.

object (Fulfillment Order Schedule)

The window during which the customer can collect the order. Only applicable when delivery_method is COLLECTION.

Request-only field — stored on each fulfillment order, not on the Order.

object (Address)

Carriyo address object used for customer, billing, delivery and customer-collection addresses.

You can either pass a fully free-form address (contact_name, address1, city, country, etc.) or reference a pre-configured location in Carriyo using partner_location_id, partner_location_name, or partner_location_code.

object (Address)

The customer's contact and address details.

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. When omitted, Carriyo auto-allocates fulfillment orders based on inventory and rules.

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": [
    ],
  • "delivery_method": "DELIVERY",
  • "delivery_type": "string",
  • "delivery_address": {
    },
  • "delivery_schedule": {
    },
  • "customer_collection_address": {
    },
  • "customer_collection_schedule": {
    },
  • "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",
  • "billing_address": {
    },
  • "customer": {
    },
  • "customer_key": "string",
  • "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"
}