Use the Yuzu 3PL Partner API to create and manage a Yuzu merchant team for each client, route orders into the correct team, track onboarding, and move a merchant live when testing is complete.
Before you start
Your Yuzu team must be configured as a 3PL team.
Create an API key while the 3PL team is active in Yuzu. See Create a Yuzu API key and choose an App ID.
Keep the key on your server. Do not put it in browser code, emails, tickets, or shared client configuration.
The API base URL is
https://app.yuzu.so.
Authenticate requests
Send the 3PL team API key in the X-API-Key header:
curl https://app.yuzu.so/api/auth/whoami \ -H "X-API-Key: yk_xxxxxxxxxxxxxxxx"
A successful response returns authMethod: "api-key" and the team ID resolved from the key. A key created in a 3PL team can manage only that team's merchants.
Understand the team model
3PL team: your parent team. It owns the API key, merchant roster, routing rules, and onboarding task templates.
Merchant team: a child team for one client. Its orders, templates, users, onboarding checklist, and lifecycle status are kept separate from other merchants.
Onboarding: orders can be received, routed, rendered, and reviewed, but automatic printing is blocked.
Live: automatic printing is enabled for new orders after the merchant goes live.
The 3PL Partner API is separate from 3PL mode in Yuzu Print Extension. Use the partner API for server-to-server merchant management and order routing. Use 3PL mode in Yuzu Print Extension when a warehouse browser must select a merchant-specific API key from the merchant shown in a WMS.
Create a merchant team
POST /api/teams/merchants
{
"name": "Avery Row",
"email": "[email protected]"
}email is optional. If present, Yuzu also sends that address an admin invitation to the new merchant team.
The response is 201 Created and includes the created team plus invitationSent:
{
"team": {
"id": "org_...",
"name": "Avery Row",
"type": "merchant",
"parent_team_id": "org_...",
"status": "onboarding"
},
"invitationSent": true
}Creating a merchant also creates a default order flow and seeds its onboarding checklist. Admins of the parent 3PL team are added to the merchant automatically.
List and manage merchants
GET /api/teams/merchantsPOST /api/teams/merchants/:merchantTeamId/invitations
{ "email": "[email protected]" }PUT /api/teams/merchants/:merchantTeamId
{ "accountManagerUserId": "user_..." }Use null for accountManagerUserId to clear it. The account manager must be a member of the parent 3PL team.
Each merchant returned by the list endpoint includes its order count and onboarding totals:
{
"id": "org_...",
"name": "Avery Row",
"status": "onboarding",
"account_manager_user_id": null,
"orderCount": 12,
"onboarding": {
"total": 7,
"completed": 4,
"openThreePlTasks": 1,
"openMerchantTasks": 2
}
}
Send an order to a merchant
Set targetTeamId to the managed merchant team's ID. Explicit targeting is recommended for direct API integrations because it is predictable and easy to debug.
POST /api/orders
{
"source": "ifglobal-wms",
"sourceId": "WMS-1042",
"targetTeamId": "org_...",
"order": {
"orderNumber": "1042",
"customer": {
"firstName": "Jane",
"lastName": "Doe",
"email": "[email protected]"
},
"lineItems": [
{
"name": "Product name",
"sku": "SKU-1",
"quantity": 1,
"price": { "amount": 3999, "currency": "GBP" }
}
],
"orderTotal": { "amount": 3999, "currency": "GBP" }
}
}targetTeamIdmust be a merchant managed by the authenticated 3PL team. Other team IDs are rejected.If
targetTeamIdis omitted, the order stays in the parent 3PL team.sourceandsourceIdidentify the order within the target team. Sending the same pair again updates the existing order.Deduplication does not cross teams. Adding or changing
targetTeamIdcreates a different order instead of moving an existing one.Orders sent while a merchant is onboarding do not print automatically. This makes it safe to connect the production feed before go-live.
If an order was sent to the wrong team, update the misrouted order to status: "ignored" with PUT /api/orders/:orderIdOrKey, then resend it with the correct targetTeamId.
Route multiple document types when printing
If one order produces multiple document types, give each document a stable tag in its Yuzu flow, such as insert and pack-by. When calling the print endpoint, pass an override for each tag:
POST /api/orders/:orderIdOrKey/print
{
"overrides": [
{
"printer": "printer-id-for-inserts",
"tray": "tray-id-for-a5",
"filters": { "document.tag": "insert" }
},
{
"printer": "printer-id-for-pack-by-notes",
"tray": "tray-id-for-a6",
"filters": { "document.tag": "pack-by" }
}
]
}This lets the API response describe every planned print and gives the warehouse system enough information to tell the operator how many documents to expect. For browser-triggered printing, see Set up tag-based printer routing in Yuzu Print Extension and Understand Yuzu Print Extension notifications.
Use routing rules for connected apps
Stored routing rules are optional. They are useful when orders come from a connected app and must be assigned by order content. Direct API integrations should normally use targetTeamId.
GET /api/teams/routing-rules?targetTeamId=org_...POST /api/teams/routing-rules
{
"appId": "...",
"targetTeamId": "org_...",
"condition": "order.variables.channel === 'avery-row'"
}DELETE /api/teams/routing-rules/:ruleId
Track onboarding
Every merchant gets system tasks for connecting a sales channel, publishing a template, configuring routing, receiving an order, and completing a test print. System tasks complete automatically when the underlying setup happens.
GET /api/teams/merchants/:merchantTeamId/onboarding-tasksPOST /api/teams/merchants/:merchantTeamId/onboarding-tasks
{
"title": "Sign the print rate card",
"assignedParty": "merchant"
}PUT /api/teams/merchants/:merchantTeamId/onboarding-tasks/:taskId
{ "completed": true }DELETE /api/teams/merchants/:merchantTeamId/onboarding-tasks/:taskIdOnly custom tasks can be completed or deleted manually. assignedParty is either three_pl or merchant.
Define custom steps for future merchants with:
GET /api/teams/onboarding-task-templates POST /api/teams/onboarding-task-templates PUT /api/teams/onboarding-task-templates/:templateId DELETE /api/teams/onboarding-task-templates/:templateId
Request bodies use camelCase fields such as assignedParty and sortOrder. Stored response records use snake_case fields such as assigned_party and sort_order.
Move a merchant live
After the checklist is complete and a test print is verified:
POST /api/teams/merchants/:merchantTeamId/go-live
Going live enables automatic printing for orders received from that point onward. It does not retroactively print orders received during onboarding. The endpoint is idempotent, so calling it for an already-live merchant returns the team unchanged.
Handle errors
400: invalid request or a target team not managed by this 3PL.401: missing, invalid, or revoked API key.403: the authenticated team cannot use a 3PL-only endpoint.404: merchant or resource not found under this 3PL.5xx: transient server error; retry with exponential backoff and a request idempotency strategy based onsourceplussourceId.