post/v1/businesses
Create a Business, owned by the authenticated Marketplace member
Request body
| Field | Type | Required |
|---|
| name | string | yes |
| description | string | — |
Response (201)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| ownerUserId | string (uuid) | — |
| name | string | — |
| description | stringnull | — |
| status | ACTIVE | SUSPENDED | DELETED | — |
| verificationStatus | PENDING | VERIFIED | REJECTED | — |
| verificationReviewedAt | string,null (date-time) | — |
| verificationReviewedBy | stringnull | — |
| verificationNotes | stringnull | — |
| createdAt | string (date-time) | — |
| updatedAt | string (date-time) | — |
get/v1/businesses
List the authenticated Marketplace member's own Businesses
get/v1/businesses/{id}
Get a Business
Response (200)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| ownerUserId | string (uuid) | — |
| name | string | — |
| description | stringnull | — |
| status | ACTIVE | SUSPENDED | DELETED | — |
| verificationStatus | PENDING | VERIFIED | REJECTED | — |
| verificationReviewedAt | string,null (date-time) | — |
| verificationReviewedBy | stringnull | — |
| verificationNotes | stringnull | — |
| createdAt | string (date-time) | — |
| updatedAt | string (date-time) | — |
patch/v1/businesses/{id}
Update a Business (owner only)
Request body
| Field | Type | Required |
|---|
| name | string | yes |
| description | string | — |
Response (200)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| ownerUserId | string (uuid) | — |
| name | string | — |
| description | stringnull | — |
| status | ACTIVE | SUSPENDED | DELETED | — |
| verificationStatus | PENDING | VERIFIED | REJECTED | — |
| verificationReviewedAt | string,null (date-time) | — |
| verificationReviewedBy | stringnull | — |
| verificationNotes | stringnull | — |
| createdAt | string (date-time) | — |
| updatedAt | string (date-time) | — |
delete/v1/businesses/{id}
Soft-delete a Business (owner only)
Response (200)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| ownerUserId | string (uuid) | — |
| name | string | — |
| description | stringnull | — |
| status | ACTIVE | SUSPENDED | DELETED | — |
| verificationStatus | PENDING | VERIFIED | REJECTED | — |
| verificationReviewedAt | string,null (date-time) | — |
| verificationReviewedBy | stringnull | — |
| verificationNotes | stringnull | — |
| createdAt | string (date-time) | — |
| updatedAt | string (date-time) | — |
get/v1/businesses/pending-verification
Ops-only in practice (Phase 34, fronted by apps/ops-console); no RBAC guard yet — see docs/security/rbac-strategy.md.
post/v1/businesses/{id}/verification
Unauthenticated by design (Phase 34) — interim ops-console review action; see BusinessesService.setVerification's doc comment.
Request body
| Field | Type | Required |
|---|
| status | PENDING | VERIFIED | REJECTED | yes |
| notes | string | — |
| reviewedBy | string | — |
Response (201)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| ownerUserId | string (uuid) | — |
| name | string | — |
| description | stringnull | — |
| status | ACTIVE | SUSPENDED | DELETED | — |
| verificationStatus | PENDING | VERIFIED | REJECTED | — |
| verificationReviewedAt | string,null (date-time) | — |
| verificationReviewedBy | stringnull | — |
| verificationNotes | stringnull | — |
| createdAt | string (date-time) | — |
| updatedAt | string (date-time) | — |
post/v1/businesses/{businessId}/business-users
Invite a team member with a role (ADMIN+, Phase 34)
Request body
| Field | Type | Required |
|---|
| userId | string (uuid) | yes |
| role | OWNER | ADMIN | DEVELOPER | ACCOUNT_MANAGER | yes |
Response (201)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| userId | string (uuid) | — |
| role | OWNER | ADMIN | DEVELOPER | ACCOUNT_MANAGER | — |
| invitedBy | string,null (uuid) | — |
| invitedAt | string (date-time) | — |
| acceptedAt | string,null (date-time) | — |
get/v1/businesses/{businessId}/business-users
List a Business's team (ADMIN+)
patch/v1/businesses/{businessId}/business-users/{userId}
Change a team member's role (ADMIN+)
Parameters
| businessId | path | required |
| userId | path | required |
Request body
| Field | Type | Required |
|---|
| role | OWNER | ADMIN | DEVELOPER | ACCOUNT_MANAGER | yes |
Response (200)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| userId | string (uuid) | — |
| role | OWNER | ADMIN | DEVELOPER | ACCOUNT_MANAGER | — |
| invitedBy | string,null (uuid) | — |
| invitedAt | string (date-time) | — |
| acceptedAt | string,null (date-time) | — |
delete/v1/businesses/{businessId}/business-users/{userId}
Remove a team member (ADMIN+; cannot remove the owner)
Parameters
| businessId | path | required |
| userId | path | required |
post/v1/businesses/{businessId}/branches
Add a Branch (location) to a Business (owner only)
Request body
| Field | Type | Required |
|---|
| name | string | yes |
| addressLine1 | string | yes |
| addressLine2 | string | — |
| city | string | yes |
| region | string | — |
| postalCode | string | — |
| country | string | yes |
Response (201)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| name | string | — |
| addressLine1 | string | — |
| addressLine2 | stringnull | — |
| city | string | — |
| region | stringnull | — |
| postalCode | stringnull | — |
| country | string | — |
| spaceStatus | NOT_ENABLED | SPACE_ENABLED | — |
| createdAt | string (date-time) | — |
get/v1/businesses/{businessId}/branches
List a Business's Branches
patch/v1/branches/{id}
Update a Branch (owner only)
Request body
| Field | Type | Required |
|---|
| name | string | yes |
| addressLine1 | string | yes |
| addressLine2 | string | — |
| city | string | yes |
| region | string | — |
| postalCode | string | — |
| country | string | yes |
Response (200)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| name | string | — |
| addressLine1 | string | — |
| addressLine2 | stringnull | — |
| city | string | — |
| region | stringnull | — |
| postalCode | stringnull | — |
| country | string | — |
| spaceStatus | NOT_ENABLED | SPACE_ENABLED | — |
| createdAt | string (date-time) | — |
delete/v1/branches/{id}
Remove a Branch (owner only)
post/v1/branches/{id}/space-status
Toggle a Branch's Space eligibility flag (owner only). Phase 23 hook only — no Space product logic exists yet.
Request body
| Field | Type | Required |
|---|
| spaceStatus | NOT_ENABLED | SPACE_ENABLED | yes |
Response (200)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| name | string | — |
| addressLine1 | string | — |
| addressLine2 | stringnull | — |
| city | string | — |
| region | stringnull | — |
| postalCode | stringnull | — |
| country | string | — |
| spaceStatus | NOT_ENABLED | SPACE_ENABLED | — |
| createdAt | string (date-time) | — |
post/v1/businesses/{businessId}/merchant-links
Link a Merchant account to a Business (owner only, many-to-many)
Request body
| Field | Type | Required |
|---|
| merchantId | string (uuid) | yes |
Response (201)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| merchantId | string (uuid) | — |
| status | ACTIVE | REVOKED | — |
| linkedAt | string (date-time) | — |
| unlinkedAt | string,null (date-time) | — |
get/v1/businesses/{businessId}/merchant-links
List a Business's linked Merchant accounts
post/v1/businesses/{businessId}/merchant-links/{linkId}/revoke
Revoke a Business<->Merchant link (owner only)
Parameters
| businessId | path | required |
| linkId | path | required |
Response (200)
| Field | Type | Required |
|---|
| id | string (uuid) | — |
| businessId | string (uuid) | — |
| merchantId | string (uuid) | — |
| status | ACTIVE | REVOKED | — |
| linkedAt | string (date-time) | — |
| unlinkedAt | string,null (date-time) | — |
get/v1/business-merchant-links
Reverse lookup — a Merchant's linked Businesses. Deliberately not nested under /v1/merchants/* — that prefix is routed to merchant-service by api-gateway's ROUTES table (prefix match), so a route nested there would never reach business-service.