Manage merchant teams

Use a parent 3PL API key for every request on this page.

List merchants

GET https://app.yuzu.so/api/teams/merchants

The response includes each merchant's lifecycle status, account manager, order count, and onboarding progress.

[
  {
    "id": "org_exampleMerchant123456789",
    "name": "Example Merchant",
    "type": "merchant",
    "parent_team_id": "org_exampleThreePl123456789",
    "status": "onboarding",
    "account_manager_user_id": null,
    "orderCount": 12,
    "onboarding": {
      "total": 5,
      "completed": 3,
      "openThreePlTasks": 1,
      "openMerchantTasks": 1
    }
  }
]

Store the merchant id. You use it as targetTeamId when creating orders.

Create a merchant

POST https://app.yuzu.so/api/teams/merchants

{
  "name": "Example Merchant",
  "email": "operations@example.com"
}

Yuzu creates the merchant in onboarding, seeds its onboarding tracker and default order flow, and adds the parent team's admins to the merchant team. A successful request returns 201 Created.

{
  "team": {
    "id": "org_exampleMerchant123456789",
    "name": "Example Merchant",
    "type": "merchant",
    "parent_team_id": "org_exampleThreePl123456789",
    "status": "onboarding"
  },
  "invitationSent": true
}

invitationSent can be false even when the team was created. Check it before telling the merchant that an invitation was sent.

Invite another merchant admin

POST https://app.yuzu.so/api/teams/merchants/{merchantTeamId}/invitations

{
  "email": "another.user@example.com"
}

The invited user joins the merchant team as an administrator. Successful requests return 201 Created with { "invitationSent": true }.

Assign an account manager

First list the parent 3PL team's members:

GET https://app.yuzu.so/api/teams/members

Use the selected member's userId when updating the merchant:

PUT https://app.yuzu.so/api/teams/merchants/{merchantTeamId}

{
  "accountManagerUserId": "user_example123"
}

The account manager must belong to the parent 3PL team. Send null to clear the assignment.

Take a merchant live

Take the merchant live after the onboarding tracker is complete and the test print has passed.

POST https://app.yuzu.so/api/teams/merchants/{merchantTeamId}/go-live

The operation is idempotent. Its response contains the updated team, including went_live_at and went_live_by.

Go-live enables automatic printing for new eligible orders. It does not automatically print orders received during onboarding; review and print those orders manually if required.

Status codes