Create an order with line items. Currency is required: use trusted source facts or CRM product prices; never guess or convert. Idempotent by externalId: re-sending the same request returns the existing order. Counts toward the plan's monthly order limit (403 PLAN_LIMIT_EXCEEDED when reached). The result echoes the operating workspace. Use search_products first. For a promo code use quote_order_promotion, then send promotion.code and promotion.expectedTotal. CRM alone calculates discounts, net totals, usage limits and free shipping. Do not invent a discount, send a legacy discountAmount, or promise free shipping from your own arithmetic.
View input schema
{
"type": "object",
"properties": {
"promotion": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{2,63}$",
"description": "CRM-managed promo code, 3–64 letters, digits, hyphens or underscores; case-insensitive. Must be enabled for this connection's source; a personal or capture code also needs the buyer email it was issued to."
},
"expectedTotal": {
"description": "Net merchandise total the buyer was shown, as a decimal string with up to two decimals (for example \"199.90\"), in the order currency. If the CRM now calculates a different amount the request is refused with price_changed.",
"type": "string",
"pattern": "^\\d{1,10}(?:\\.\\d{1,2})?$"
}
},
"required": [
"code"
],
"additionalProperties": false,
"description": "Ask the CRM to validate and calculate this promo code. Do not supply promoCode, discountAmount or shippingThresholdAmount alongside it. An optional expectedTotal refuses a changed quote; the server always owns the actual discount."
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"pattern": "^[A-Z]{3}$",
"description": "Required ISO 4217 currency code from the source facts or selected CRM product prices. Never guess or convert between currencies."
},
"customer": {
"description": "Optional buyer snapshot (name/email/phone, or a storefront customer externalId). Omit for an anonymous order.",
"type": "object",
"properties": {
"email": {
"type": "string",
"maxLength": 255,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"externalId": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"firstName": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"lastName": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"phone": {
"type": "string",
"minLength": 1,
"maxLength": 50
},
"shippingAddress": {
"type": "object",
"properties": {
"city": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"line1": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"line2": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"postalCode": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"region": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"required": [
"city",
"country",
"line1"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"delivery": {
"description": "How the buyer asked to receive the order: carrier, branch/courier/pickup, branch text, recipient, cash-on-delivery and a delivery note. This is the buyer's choice at checkout — it does not dispatch anything. Record what actually ships with POST /orders/{externalId}/shipments.",
"type": "object",
"properties": {
"branch": {
"description": "Branch or parcel locker as the buyer named it, e.g. \"відділення №5\" or \"поштомат 12345\". Free text: the CRM resolves it against the live branch list of the carrier when creating a waybill.",
"type": "string",
"maxLength": 200
},
"branchRef": {
"description": "The carrier's own identifier for the branch or parcel locker, as returned by GET /api/v1/carriers/{carrier}/warehouses. The same value the shipment-label endpoint calls warehouseRef. Sent, this removes all guessing; omitted, the CRM falls back to matching `branch` as text.",
"type": "string",
"maxLength": 64
},
"building": {
"description": "House number for courier delivery, structured rather than inside the address line because carriers validate it on its own (Nova Poshta accepts up to 11 characters matching digits plus an optional Cyrillic letter or block, e.g. \"12Б\" or \"12/4\").",
"type": "string",
"maxLength": 35
},
"carrier": {
"description": "Carrier slug the buyer chose, from GET /capabilities (e.g. \"nova_poshta\", \"ukrposhta\", \"pickup\"). This is a preference, not a dispatch — the shipment endpoint still records what actually ships.",
"type": "string",
"maxLength": 120
},
"cityRef": {
"description": "The carrier's own identifier for the destination city, as returned by GET /api/v1/carriers/{carrier}/cities. Required alongside branchRef or streetRef for a waybill to be created from the order alone.",
"type": "string",
"maxLength": 64
},
"cod": {
"description": "True when the buyer pays on delivery (cash on delivery).",
"type": "boolean"
},
"comment": {
"description": "Delivery note from the buyer, e.g. \"дзвонити після 18:00\". Not the order notes.",
"type": "string",
"maxLength": 1000
},
"flat": {
"description": "Apartment or office number for courier delivery.",
"type": "string",
"maxLength": 35
},
"method": {
"description": "How the parcel reaches the buyer: \"branch\" (carrier office/locker), \"courier\" (to the address) or \"pickup\" (buyer collects from you).",
"type": "string",
"enum": [
"branch",
"courier",
"pickup"
]
},
"phone": {
"description": "Recipient phone, when it differs from the buyer's own contact phone.",
"type": "string",
"maxLength": 50
},
"recipientName": {
"description": "Who receives the parcel, when that is not the buyer (a gift, an office).",
"type": "string",
"maxLength": 200
},
"streetRef": {
"description": "The carrier's own identifier for the street, as returned by GET /api/v1/carriers/{carrier}/streets. Courier delivery only; pair it with `building`.",
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
},
"externalId": {
"type": "string",
"minLength": 1,
"maxLength": 160,
"description": "A stable unique id for this order in your system — the idempotency key. Re-sending the same externalId returns the existing order instead of creating a duplicate (e.g. 'mcp-<uuid>')."
},
"items": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"discount": {
"default": 0,
"description": "Percentage discount on this line (0-100). Default 0.",
"type": "number",
"minimum": 0,
"maximum": 100
},
"productName": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Line item name, snapshotted onto the order. Use search_products to quote a real catalog product's name. Required."
},
"quantity": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Quantity ordered (integer, at least 1)."
},
"sku": {
"description": "Product SKU snapshot (from search_products). Optional.",
"type": "string",
"maxLength": 120
},
"unitPrice": {
"anyOf": [
{
"type": "string",
"pattern": "^\\d+(\\.\\d{1,2})?$"
},
{
"type": "number",
"minimum": 0
}
],
"description": "Price per unit in the order currency, as a decimal (e.g. 199.99). Snapshotted onto the line."
}
},
"required": [
"productName",
"quantity",
"unitPrice"
],
"additionalProperties": false
},
"description": "Order line items (1-100). Each snapshots productName/sku/unitPrice."
},
"notes": {
"description": "Internal note stored on the order. For a delivery instruction from the buyer use delivery.comment instead.",
"type": "string",
"maxLength": 5000
}
},
"required": [
"currency",
"externalId",
"items"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}