API

Create order

Create an order in Yuzu.

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.
`targetTeamId`	string	Optional. For 3PL API keys, the managed merchant team that should own the order.
`order.orderNumber`	string	Required. Human-readable order number.
`order.orderDate`	string	Optional ISO timestamp. Defaults to the ingest time if omitted.
`order.note`	string	Standard order note or gift message, available through Yuzu's built-in Note variable.
`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.

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.

3PL merchant targeting

A 3PL team can add targetTeamId to create the order inside a managed merchant team. The rest of the request uses the same schema described on this page.

{
  "source": "warehouse-east",
  "sourceId": "WE-1001",
  "targetTeamId": "org_exampleMerchant123456789",
  "order": {
    "orderNumber": "#1001"
  }
}

The target must be a merchant managed by the authenticated 3PL team. Read Send orders to merchants before using this field in production.

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": "Hi Jill,\n\nHappy birthday!\n\nFrom Sam",
      "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": {
        "videoMessageUrl": "https://store.example.com/giftie/123",
        "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",
  "note": "Hi Jill,\n\nHappy birthday!\n\nFrom Sam",
  "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": {
    "videoMessageUrl": "https://store.example.com/giftie/123",
    "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.

Errors and retries

Handle Yuzu API failures safely.

Fetch order

Retrieve a Yuzu order by order ID or order key.