API
Create order
Create an order in Yuzu.
Create order
Create or update an order in Yuzu from an external system.
POST https://app.yuzu.so/api/orders
Headers
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Request body
| Field | Type | Description |
|---|---|---|
source | string | Optional source namespace. Defaults to api. Use a stable value such as shopify, wms, or warehouse-east. |
sourceId | string or number | Required. Unique order ID inside that source. Reuse it for retries and updates. |
order.orderNumber | string | Required. Human-readable order number. |
order.orderDate | string | Optional ISO timestamp. Defaults to the ingest time if omitted. |
order.customer | object | Customer identity and summary fields. |
order.shippingAddress | object | Shipping address used by templates and flows. |
order.billingAddress | object | Billing address. |
order.lineItems | array | Products included in the order. |
order.orderTotal | object | Total order value as { "amount": number, "currency": "USD" }. |
order.variables | object | Per-order values available to templates and flows. |
order.tags | array | Tags to resolve and attach to the order. |
order.overrides | object | Optional template, printer, and tray overrides. |
Idempotency
Yuzu identifies API-created orders by source and sourceId, namespaced to your team. Repeating a request with the same pair updates or merges into the existing order instead of creating a duplicate.
Store either the returned id or one of the returned orderKeys. Read Order keys before choosing source and sourceId values.
Common nested fields
Customer fields:
| Field | Description |
|---|---|
id | Optional customer ID from your source system. |
firstName, lastName, email | Customer identity fields. |
orderCount | Customer order count from your system. |
lifetimeValue, averageOrderValue | Price objects with amount and currency. |
Address fields:
| Field | Description |
|---|---|
firstName, lastName, company | Recipient or billing contact. |
address1, address2, address3 | Street address fields. |
city, state, postalCode, country | Locality fields. Use country codes such as US when possible. |
latitude, longitude | Optional numeric coordinates. |
Line item fields:
| Field | Description |
|---|---|
name | Required product name. |
quantity | Required number. |
sku | Optional SKU. |
external_id | Optional stable line item ID from your source system. |
price | Price object with amount and currency. |
image_url | Optional product image URL. |
variant | Optional variant object with id, sku, title, or image fields. |
Example request
curl --request POST 'https://app.yuzu.so/api/orders' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{
"source": "warehouse-east",
"sourceId": "WE-1001",
"order": {
"orderNumber": "#1001",
"orderDate": "2026-05-19T12:00:00.000Z",
"note": "Leave by the side door",
"customer": {
"id": "gid://shopify/Customer/9981",
"firstName": "Jill",
"lastName": "Blogs",
"email": "jill@blogs.com",
"orderCount": 3,
"lifetimeValue": {
"amount": 1,
"currency": "USD"
},
"averageOrderValue": {
"amount": 1,
"currency": "USD"
}
},
"billingAddress": {
"firstName": "Jill",
"lastName": "Blogs",
"company": "Blog Inc.",
"address1": "456 Joe Road",
"address2": "",
"address3": "",
"city": "Joesville",
"state": "Delaware",
"postalCode": "54321",
"country": "US"
},
"shippingAddress": {
"firstName": "Jill",
"lastName": "Blogs",
"address1": "123 Joe Road",
"address2": "",
"city": "Joesville",
"state": "DE",
"postalCode": "12345",
"country": "US"
},
"lineItems": [
{
"external_id": "line-item-1",
"name": "Example product",
"quantity": 1,
"sku": "SKU-0001",
"price": {
"amount": 1,
"currency": "USD"
}
}
],
"orderTotal": {
"amount": 1,
"currency": "USD"
},
"variables": {
"giftMessage": "Happy birthday, Sam",
"warehouse": "east"
},
"tags": [
{
"label": "VIP"
}
],
"overrides": {
"template": "template_id_here",
"printer": "printer_id_here",
"tray": "Tray 1"
}
}
}'
Response
Successful requests return 201 Created and the created or updated order.
{
"id": "a2cb2c3d-4e5f-6g7h-8i9j-123a45c67890",
"orderKeys": [
"org_exampleTeam123456789/warehouse-east-WE-1001"
],
"orderNumber": "#1001",
"orderDate": "2026-05-19T12:00:00.000Z",
"status": "ready",
"customer": {
"firstName": "Jill",
"lastName": "Blogs",
"email": "jill@blogs.com",
"orderCount": 3,
"lifetimeValue": {
"amount": 1,
"currency": "USD"
},
"averageOrderValue": {
"amount": 1,
"currency": "USD"
}
},
"shippingAddress": {
"firstName": "Jill",
"lastName": "Blogs",
"address1": "123 Joe Road",
"city": "Joesville",
"state": "DE",
"postalCode": "12345",
"country": "US"
},
"lineItems": [
{
"name": "Example product",
"quantity": 1,
"sku": "SKU-0001",
"price": {
"amount": 1,
"currency": "USD"
},
"external_id": "line-item-1"
}
],
"orderTotal": {
"amount": 1,
"currency": "USD"
},
"tags": [
{
"id": "tag_id_here",
"label": "VIP",
"color": "#000000"
}
],
"variables": {
"giftMessage": "Happy birthday, Sam",
"warehouse": "east"
},
"createdAt": "2026-05-19T12:00:01.000Z",
"updatedAt": "2026-05-19T12:00:01.000Z"
}
Common status codes:
| Status | Meaning |
|---|---|
201 | Order created or updated. |
400 | Invalid request body. |
401 | Missing, malformed, or invalid API key. |
403 | API key cannot access the requested team resource. |
5xx | Temporary service issue. Retry with backoff. |