Order keys

Every order has a Yuzu order ID and one or more order keys. The Yuzu order ID is the UUID returned as id. An order key is a stable compound identifier that links an external source to that order.

Order keys are built from a source and a source ID.

{source}-{sourceId}

Use a sourceId that is stable and unique inside the source you are using. If you retry or resync with the same source and source ID, Yuzu updates the same order instead of creating a duplicate.

Team API keys

For orders created with a team API key, Yuzu scopes the submitted source to your organization. If your organization ID is org_exampleTeam123456789, you create an order with source: "warehouse-east", and the external order ID is WE-1001, the returned order key is:

org_exampleTeam123456789/warehouse-east-WE-1001

For API-key orders, choose source IDs that are unique within your team and source namespace, such as api, shopify, wms, or warehouse-east.

Orders created manually in Yuzu or through web workflows can also use team-scoped sources. For example, an order created from a web workflow may have a key shaped like:

org_exampleTeam123456789/web-12345

App integrations

For app-authenticated integrations, the source is the installed app ID. That means the same external source ID can exist in two different connected apps without colliding:

a2cb2c3d-4e5f-6g7h-8i9j-0k1l2m3n4o5p-1234567890

For example, a Shopify order key is not shopify-10000000000001. It uses the installed Shopify app ID:

a2cb2c3d-4e5f-6g7h-8i9j-0k1l2m3n4o5p-1234567890

Find an installed app ID in Yuzu by opening Apps, selecting the app, and copying the ID from the right-hand slideover.

For app-authenticated orders, the source ID only needs to be unique within that connected app.

Multiple keys

An order can have multiple order keys if it has been enriched or linked by multiple apps or systems. For example, the same order may have one key from a Shopify app and another from an API import.

Print requests and PDF fetch requests accept order UUIDs and order keys. When you send an order key in a JSON body, such as orderIds, send it exactly as returned by Yuzu. If you use an order key in a URL path, URL-encode it because keys can contain /, :, and other path-sensitive characters.