Merchants

Create and manage merchant accounts, stores, Stripe Connect onboarding, and team members. A merchant is the top-level commerce entity that owns one or more stores.

Authentication

All merchant endpoints require a valid JWT or API key. The authenticated user becomes the owner of merchants they create.

Endpoints

POST/merchantsCreate a merchant

GET/merchantsList merchants for the authenticated user

GET/merchants/:idGet merchant details

PATCH/merchants/:idUpdate merchant profile

POST/merchants/:id/storesAdd a store to a merchant

GET/merchants/:id/storesList stores for a merchant

POST/merchants/:id/onboardInitiate Stripe Connect onboarding

GET/merchants/:id/onboard/statusCheck Stripe onboarding status

POST/merchants/:id/team/membersInvite a team member

GET/merchants/:id/team/membersList team members

PATCH/merchants/:id/team/members/:memberIdChange a member's role (admin or owner)

DELETE/merchants/:id/team/members/:memberIdRemove a member, or leave the team yourself

GET/merchants/:id/team/meYour own role on this merchant

Create a Merchant

POST/merchantsCreate a merchant

Request Body

{
"name": "Acme Electronics",
"slug": "acme-electronics",
"businessType": "company",
"country": "US"
}

Field	Type	Required	Description
`name`	string	Yes	Business name (max 255 chars)
`slug`	string	Yes	URL-safe identifier (max 100 chars)
`businessType`	string	No	`individual` or `company`
`country`	string	No	Two-letter ISO country code

The merchant is created with the authenticated user as owner.

Update a Merchant

PATCH/merchants/:idUpdate merchant profile

Request Body

{
"name": "Acme Electronics LLC",
"businessType": "retail",
"status": "active"
}

Field	Type	Required	Description
`name`	string	No	Business name (max 255 chars)
`businessType`	string	No	`individual`, `company`, `restaurant`, `retail`, `services`, `events`, or `digital`
`country`	string	No	Two-letter ISO country code
`status`	string	No	`active`, `suspended`, or `pending`

Stores

POST/merchants/:id/storesAdd a store to a merchant

GET/merchants/:id/storesList stores for a merchant

Request Body

{
"name": "Acme US Store",
"domain": "shop.acme.com",
"currency": "USD",
"timezone": "America/New_York"
}

Field	Type	Required	Description
`name`	string	Yes	Store name (max 255 chars)
`domain`	string	No	Custom domain (max 255 chars)
`currency`	string	No	Three-letter ISO currency code (default `USD`)
`timezone`	string	No	IANA timezone (max 50 chars)

Stripe Connect Onboarding

POST/merchants/:id/onboardInitiate Stripe Connect onboarding

GET/merchants/:id/onboard/statusCheck onboarding status

POST /merchants/:id/onboard returns a Stripe Connect Express onboarding URL. Redirect the merchant to complete KYC/KYB. Poll the status endpoint to determine when the account is ready to accept payments and receive payouts.

Onboarding gating

Payouts are only available once onboarding status reports the account as fully verified. Gate payout UI on the status endpoint.

Team Members

POST/merchants/:id/team/membersInvite a team member

GET/merchants/:id/team/membersList team members

PATCH/merchants/:id/team/members/:memberIdChange a member's role (admin or owner)

DELETE/merchants/:id/team/members/:memberIdRemove a member, or leave the team yourself

GET/merchants/:id/team/meYour own role on this merchant

Request Body

{
"userId": "usr_abc123",
"role": "admin"
}

Field	Type	Required	Description
`userId`	string	Yes	The user to add to the merchant team
`role`	string	Yes	`owner`, `admin`, `manager`, `member`, or `viewer`

Roles are enforced on every merchant-scoped API route (a 403 names the role an action needs):

Role	Can do
`viewer`	Read every merchant endpoint
`member`	Day-to-day writes: products, orders, payment links, checkouts, customers, loyalty
`manager`	Refunds, order cancellation, product deletion, campaign sends, x402 endpoints, webhook retries
`admin`	Payouts, credit lines, webhooks, integrations, store settings, onboarding, team management (up to `admin`)
`owner`	Everything, including managing owners and admins

Only admins and owners manage the team, and nobody can grant a role above their own. Anyone can leave a team with DELETE /merchants/:id/team/members/:memberId on their own membership. A merchant always keeps at least one owner: the last owner cannot be removed or demoted. Changing a merchant's status is reserved for Gully Pay staff.