TBBN Developers

post/v1/businesses

Create a Business, owned by the authenticated Marketplace member

curl -X POST https://api.tbbnetwork.com/v1/businesses \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Co.",
  "description": "A short description of this resource.",
  "type": "INDIVIDUAL",
  "legalName": "Acme Co.",
  "registrationNumber": "registrationNumber",
  "taxId": "taxId",
  "legalCountry": "US"
}'

Request body

Field	Type	Required
name	string	yes
description	string	—
type	INDIVIDUAL \| REGISTERED	yes
legalName	string	—
registrationNumber	string	—
taxId	string	—
legalCountry	string	—

Response (201)

Field	Type	Required
id	string (uuid)	—
ownerUserId	string (uuid)	—
name	string	—
description	stringnull	—
status	ACTIVE \| SUSPENDED \| DELETED	—
type	INDIVIDUAL \| REGISTERED	—
legalName	stringnull	—
registrationNumber	stringnull	—
taxId	stringnull	—
legalCountry	stringnull	—
logoUrl	stringnull	—
websiteUrl	stringnull	—
supportEmail	stringnull	—
supportPhone	stringnull	—
privacyPolicyUrl	stringnull	—
termsUrl	stringnull	—
openingHours	object	—
verificationStatus	PENDING \| VERIFIED \| REJECTED	—
verificationReviewedAt	string,null (date-time)	—
verificationReviewedBy	stringnull	—
verificationNotes	stringnull	—
connectAccount	BusinessConnectAccount	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "ownerUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Acme Co.",
  "description": null,
  "status": "ACTIVE",
  "type": "INDIVIDUAL",
  "legalName": null,
  "registrationNumber": null,
  "taxId": null,
  "legalCountry": null,
  "logoUrl": null,
  "websiteUrl": null,
  "supportEmail": null,
  "supportPhone": null,
  "privacyPolicyUrl": null,
  "termsUrl": null,
  "openingHours": null,
  "verificationStatus": "PENDING",
  "verificationReviewedAt": "2026-07-01T12:00:00Z",
  "verificationReviewedBy": null,
  "verificationNotes": null,
  "connectAccount": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "stripeConnectedAccountId": null,
    "onboardingStatus": "NOT_STARTED",
    "detailsSubmitted": false,
    "country": null,
    "businessType": "individual",
    "representativeMatchedAt": "2026-07-01T12:00:00Z",
    "representativeMismatch": null,
    "createdAt": "2026-07-01T12:00:00Z",
    "updatedAt": "2026-07-01T12:00:00Z"
  },
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/businesses

List the authenticated Marketplace member's own Businesses

curl -X GET https://api.tbbnetwork.com/v1/businesses \
  -H "Authorization: Bearer <session access token>" \

Parameters

ownerUserId

query

optional

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "ownerUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Co.",
    "description": null,
    "status": "ACTIVE",
    "type": "INDIVIDUAL",
    "legalName": null,
    "registrationNumber": null,
    "taxId": null,
    "legalCountry": null,
    "logoUrl": null,
    "websiteUrl": null,
    "supportEmail": null,
    "supportPhone": null,
    "privacyPolicyUrl": null,
    "termsUrl": null,
    "openingHours": null,
    "verificationStatus": "PENDING",
    "verificationReviewedAt": "2026-07-01T12:00:00Z",
    "verificationReviewedBy": null,
    "verificationNotes": null,
    "connectAccount": {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "stripeConnectedAccountId": null,
      "onboardingStatus": "NOT_STARTED",
      "detailsSubmitted": false,
      "country": null,
      "businessType": "individual",
      "representativeMatchedAt": "2026-07-01T12:00:00Z",
      "representativeMismatch": null,
      "createdAt": "2026-07-01T12:00:00Z",
      "updatedAt": "2026-07-01T12:00:00Z"
    },
    "createdAt": "2026-07-01T12:00:00Z",
    "updatedAt": "2026-07-01T12:00:00Z"
  }
]

get/v1/businesses/{id}

Get a Business

curl -X GET https://api.tbbnetwork.com/v1/businesses/{id} \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

id

path

required

Response (200)

Field	Type	Required
id	string (uuid)	—
ownerUserId	string (uuid)	—
name	string	—
description	stringnull	—
status	ACTIVE \| SUSPENDED \| DELETED	—
type	INDIVIDUAL \| REGISTERED	—
legalName	stringnull	—
registrationNumber	stringnull	—
taxId	stringnull	—
legalCountry	stringnull	—
logoUrl	stringnull	—
websiteUrl	stringnull	—
supportEmail	stringnull	—
supportPhone	stringnull	—
privacyPolicyUrl	stringnull	—
termsUrl	stringnull	—
openingHours	object	—
verificationStatus	PENDING \| VERIFIED \| REJECTED	—
verificationReviewedAt	string,null (date-time)	—
verificationReviewedBy	stringnull	—
verificationNotes	stringnull	—
connectAccount	BusinessConnectAccount	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "ownerUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Acme Co.",
  "description": null,
  "status": "ACTIVE",
  "type": "INDIVIDUAL",
  "legalName": null,
  "registrationNumber": null,
  "taxId": null,
  "legalCountry": null,
  "logoUrl": null,
  "websiteUrl": null,
  "supportEmail": null,
  "supportPhone": null,
  "privacyPolicyUrl": null,
  "termsUrl": null,
  "openingHours": null,
  "verificationStatus": "PENDING",
  "verificationReviewedAt": "2026-07-01T12:00:00Z",
  "verificationReviewedBy": null,
  "verificationNotes": null,
  "connectAccount": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "stripeConnectedAccountId": null,
    "onboardingStatus": "NOT_STARTED",
    "detailsSubmitted": false,
    "country": null,
    "businessType": "individual",
    "representativeMatchedAt": "2026-07-01T12:00:00Z",
    "representativeMismatch": null,
    "createdAt": "2026-07-01T12:00:00Z",
    "updatedAt": "2026-07-01T12:00:00Z"
  },
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

patch/v1/businesses/{id}

Update a Business (owner or Admin). Once verificationStatus is VERIFIED, changing who it legally is (name, legal name, registration number, tax id, legal country) also requires a step-up token scoped to "business:update" — see POST /v1/auth/step-up/confirm. Brand and contact details (logoUrl, websiteUrl, supportEmail, supportPhone, privacyPolicyUrl, termsUrl — https links; an empty string clears one) never need one; the Business's Merchants and Spaces show them unless they set their own.

curl -X PATCH https://api.tbbnetwork.com/v1/businesses/{id} \
  -H "Authorization: Bearer <session access token>" \
  -H "X-TBBN-Step-Up-Token: <step-up-token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Co.",
  "description": "A short description of this resource.",
  "legalName": "Acme Co.",
  "registrationNumber": "registrationNumber",
  "taxId": "taxId",
  "legalCountry": "US",
  "logoUrl": "https://example.com/resource",
  "websiteUrl": "https://example.com/resource",
  "supportEmail": "supportEmail",
  "supportPhone": "+1-555-0173",
  "privacyPolicyUrl": "https://example.com/resource",
  "termsUrl": "https://example.com/resource",
  "openingHours": {
    "timeZone": "America/Denver",
    "days": [
      {
        "day": 1,
        "open": false,
        "opensAt": "09:00",
        "closesAt": "17:00"
      }
    ]
  }
}'

Parameters

id	path	required
X-TBBN-Step-Up-Token	header	optional

Request body

Field	Type	Required
name	string	—
description	string	—
legalName	string	—
registrationNumber	string	—
taxId	string	—
legalCountry	string	—
logoUrl	string	—
websiteUrl	string	—
supportEmail	string	—
supportPhone	string	—
privacyPolicyUrl	string	—
termsUrl	string	—
openingHours	OpeningHours	—

Response (200)

Field	Type	Required
id	string (uuid)	—
ownerUserId	string (uuid)	—
name	string	—
description	stringnull	—
status	ACTIVE \| SUSPENDED \| DELETED	—
type	INDIVIDUAL \| REGISTERED	—
legalName	stringnull	—
registrationNumber	stringnull	—
taxId	stringnull	—
legalCountry	stringnull	—
logoUrl	stringnull	—
websiteUrl	stringnull	—
supportEmail	stringnull	—
supportPhone	stringnull	—
privacyPolicyUrl	stringnull	—
termsUrl	stringnull	—
openingHours	object	—
verificationStatus	PENDING \| VERIFIED \| REJECTED	—
verificationReviewedAt	string,null (date-time)	—
verificationReviewedBy	stringnull	—
verificationNotes	stringnull	—
connectAccount	BusinessConnectAccount	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "ownerUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Acme Co.",
  "description": null,
  "status": "ACTIVE",
  "type": "INDIVIDUAL",
  "legalName": null,
  "registrationNumber": null,
  "taxId": null,
  "legalCountry": null,
  "logoUrl": null,
  "websiteUrl": null,
  "supportEmail": null,
  "supportPhone": null,
  "privacyPolicyUrl": null,
  "termsUrl": null,
  "openingHours": null,
  "verificationStatus": "PENDING",
  "verificationReviewedAt": "2026-07-01T12:00:00Z",
  "verificationReviewedBy": null,
  "verificationNotes": null,
  "connectAccount": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "stripeConnectedAccountId": null,
    "onboardingStatus": "NOT_STARTED",
    "detailsSubmitted": false,
    "country": null,
    "businessType": "individual",
    "representativeMatchedAt": "2026-07-01T12:00:00Z",
    "representativeMismatch": null,
    "createdAt": "2026-07-01T12:00:00Z",
    "updatedAt": "2026-07-01T12:00:00Z"
  },
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

delete/v1/businesses/{id}

Soft-delete a Business (owner only)

curl -X DELETE https://api.tbbnetwork.com/v1/businesses/{id} \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Parameters

id

path

required

Response (200)

Field	Type	Required
id	string (uuid)	—
ownerUserId	string (uuid)	—
name	string	—
description	stringnull	—
status	ACTIVE \| SUSPENDED \| DELETED	—
type	INDIVIDUAL \| REGISTERED	—
legalName	stringnull	—
registrationNumber	stringnull	—
taxId	stringnull	—
legalCountry	stringnull	—
logoUrl	stringnull	—
websiteUrl	stringnull	—
supportEmail	stringnull	—
supportPhone	stringnull	—
privacyPolicyUrl	stringnull	—
termsUrl	stringnull	—
openingHours	object	—
verificationStatus	PENDING \| VERIFIED \| REJECTED	—
verificationReviewedAt	string,null (date-time)	—
verificationReviewedBy	stringnull	—
verificationNotes	stringnull	—
connectAccount	BusinessConnectAccount	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "ownerUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Acme Co.",
  "description": null,
  "status": "ACTIVE",
  "type": "INDIVIDUAL",
  "legalName": null,
  "registrationNumber": null,
  "taxId": null,
  "legalCountry": null,
  "logoUrl": null,
  "websiteUrl": null,
  "supportEmail": null,
  "supportPhone": null,
  "privacyPolicyUrl": null,
  "termsUrl": null,
  "openingHours": null,
  "verificationStatus": "PENDING",
  "verificationReviewedAt": "2026-07-01T12:00:00Z",
  "verificationReviewedBy": null,
  "verificationNotes": null,
  "connectAccount": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "stripeConnectedAccountId": null,
    "onboardingStatus": "NOT_STARTED",
    "detailsSubmitted": false,
    "country": null,
    "businessType": "individual",
    "representativeMatchedAt": "2026-07-01T12:00:00Z",
    "representativeMismatch": null,
    "createdAt": "2026-07-01T12:00:00Z",
    "updatedAt": "2026-07-01T12:00:00Z"
  },
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/businesses/{businessId}/business-users

Invite someone to the team with a role (owner or Admin)

curl -X POST https://api.tbbnetwork.com/v1/businesses/{businessId}/business-users \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": "ADMIN",
  "branchIds": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ]
}'

Parameters

businessId

path

required

Request body

Field	Type	Required
email	string (email)	—
userId	string (uuid)	—
role	ADMIN \| ACCOUNT_MANAGER \| OPERATIONS \| ACCOUNTANT \| DEVELOPER \| SUPPORT \| RECEPTION \| VIEWER	yes
branchIds	string[]	—

Response (201)

Field	Type	Required
id	string (uuid)	—
email	string,null (email)	—
invitedUserId	string,null (uuid)	—
role	string	—
branchIds	string[]	—
status	PENDING \| ACCEPTED \| DECLINED \| REVOKED	—
state	PENDING \| EXPIRED \| ACCEPTED \| DECLINED \| REVOKED	—
createdAt	string (date-time)	—
expiresAt	string (date-time)	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "email": "you@example.com",
  "invitedUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": "role",
  "branchIds": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "status": "PENDING",
  "state": "PENDING",
  "createdAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/businesses/{businessId}/business-users

List a Business's team (owner or Admin)

curl -X GET https://api.tbbnetwork.com/v1/businesses/{businessId}/business-users \
  -H "Authorization: Bearer <session access token>" \

Parameters

businessId

path

required

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "role": "ADMIN",
    "branchIds": [
      "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
    ],
    "invitedBy": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "invitedAt": "2026-07-01T12:00:00Z",
    "acceptedAt": "2026-07-01T12:00:00Z"
  }
]

get/v1/businesses/{businessId}/invitations

The team's invitations waiting for an answer (owner or Admin)

curl -X GET https://api.tbbnetwork.com/v1/businesses/{businessId}/invitations \
  -H "Authorization: Bearer <session access token>" \

Parameters

businessId

path

required

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "email": "you@example.com",
    "invitedUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "role": "role",
    "branchIds": [
      "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
    ],
    "status": "PENDING",
    "state": "PENDING",
    "createdAt": "2026-07-01T12:00:00Z",
    "expiresAt": "2026-07-01T12:00:00Z"
  }
]

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

delete/v1/businesses/{businessId}/invitations/{invitationId}

Withdraw an invitation (owner or Admin)

curl -X DELETE https://api.tbbnetwork.com/v1/businesses/{businessId}/invitations/{invitationId} \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Parameters

businessId	path	required
invitationId	path	required

Response (200)

Field	Type	Required
id	string (uuid)	—
email	string,null (email)	—
invitedUserId	string,null (uuid)	—
role	string	—
branchIds	string[]	—
status	PENDING \| ACCEPTED \| DECLINED \| REVOKED	—
state	PENDING \| EXPIRED \| ACCEPTED \| DECLINED \| REVOKED	—
createdAt	string (date-time)	—
expiresAt	string (date-time)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "email": "you@example.com",
  "invitedUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": "role",
  "branchIds": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "status": "PENDING",
  "state": "PENDING",
  "createdAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/businesses/invitations/mine

Invitations to Business teams waiting for you

curl -X GET https://api.tbbnetwork.com/v1/businesses/invitations/mine \
  -H "Authorization: Bearer <session access token>" \

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "team": "BUSINESS",
    "teamId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "teamName": "teamName",
    "logoUrl": null,
    "role": "role",
    "invitedBy": null,
    "createdAt": "2026-07-01T12:00:00Z",
    "expiresAt": "2026-07-01T12:00:00Z"
  }
]

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/businesses/invitations/{invitationId}/accept

Accept an invitation and join the team with its role

curl -X POST https://api.tbbnetwork.com/v1/businesses/invitations/{invitationId}/accept \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Parameters

invitationId

path

required

Response (201)

Field	Type	Required
businessId	string (uuid)	—
businessName	string	—
role	string	—

Example 201 response

{
  "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "businessName": "businessName",
  "role": "role"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/businesses/invitations/{invitationId}/decline

Decline an invitation

curl -X POST https://api.tbbnetwork.com/v1/businesses/invitations/{invitationId}/decline \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Parameters

invitationId

path

required

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

patch/v1/businesses/{businessId}/business-users/{userId}

Change a team member's role or locations (owner or Admin)

curl -X PATCH https://api.tbbnetwork.com/v1/businesses/{businessId}/business-users/{userId} \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "ADMIN",
  "branchIds": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ]
}'

Parameters

businessId	path	required
userId	path	required

Request body

Field	Type	Required
role	ADMIN \| ACCOUNT_MANAGER \| OPERATIONS \| ACCOUNTANT \| DEVELOPER \| SUPPORT \| RECEPTION \| VIEWER	—
branchIds	string[]	—

Response (200)

Field	Type	Required
id	string (uuid)	—
businessId	string (uuid)	—
userId	string (uuid)	—
role	ADMIN \| ACCOUNT_MANAGER \| OPERATIONS \| ACCOUNTANT \| DEVELOPER \| SUPPORT \| RECEPTION \| VIEWER	—
branchIds	string[]	—
invitedBy	string,null (uuid)	—
invitedAt	string (date-time)	—
acceptedAt	string,null (date-time)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": "ADMIN",
  "branchIds": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "invitedBy": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "invitedAt": "2026-07-01T12:00:00Z",
  "acceptedAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

delete/v1/businesses/{businessId}/business-users/{userId}

Remove a team member (owner or Admin; the owner can't be removed)

curl -X DELETE https://api.tbbnetwork.com/v1/businesses/{businessId}/business-users/{userId} \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Parameters

businessId	path	required
userId	path	required

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/businesses/{businessId}/branches

Add a Branch (location) to a Business (owner only)

curl -X POST https://api.tbbnetwork.com/v1/businesses/{businessId}/branches \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Co.",
  "addressLine1": "addressLine1",
  "addressLine2": "addressLine2",
  "city": "city",
  "region": "CA",
  "postalCode": "postalCode",
  "country": "US",
  "latitude": 1,
  "longitude": 1
}'

Parameters

businessId

path

required

Request body

Field	Type	Required
name	string	yes
addressLine1	string	yes
addressLine2	string	—
city	string	yes
region	string	—
postalCode	string	—
country	string	yes
latitude	number	—
longitude	number	—

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)	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Acme Co.",
  "addressLine1": "addressLine1",
  "addressLine2": null,
  "city": "city",
  "region": null,
  "postalCode": null,
  "country": "US",
  "spaceStatus": "NOT_ENABLED",
  "createdAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/businesses/{businessId}/branches

List a Business's Branches

curl -X GET https://api.tbbnetwork.com/v1/businesses/{businessId}/branches \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

businessId

path

required

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Co.",
    "addressLine1": "addressLine1",
    "addressLine2": null,
    "city": "city",
    "region": null,
    "postalCode": null,
    "country": "US",
    "spaceStatus": "NOT_ENABLED",
    "createdAt": "2026-07-01T12:00:00Z"
  }
]

patch/v1/branches/{id}

Update a Branch (owner only)

curl -X PATCH https://api.tbbnetwork.com/v1/branches/{id} \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Co.",
  "addressLine1": "addressLine1",
  "addressLine2": "addressLine2",
  "city": "city",
  "region": "CA",
  "postalCode": "postalCode",
  "country": "US",
  "latitude": 1,
  "longitude": 1
}'

Parameters

id

path

required

Request body

Field	Type	Required
name	string	yes
addressLine1	string	yes
addressLine2	string	—
city	string	yes
region	string	—
postalCode	string	—
country	string	yes
latitude	number	—
longitude	number	—

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)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Acme Co.",
  "addressLine1": "addressLine1",
  "addressLine2": null,
  "city": "city",
  "region": null,
  "postalCode": null,
  "country": "US",
  "spaceStatus": "NOT_ENABLED",
  "createdAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

delete/v1/branches/{id}

Remove a Branch (owner only)

curl -X DELETE https://api.tbbnetwork.com/v1/branches/{id} \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

Parameters

id

path

required

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/branches/{id}/space-status

Toggle a Branch's Space eligibility flag (owner only). Hook only — no Space product logic exists yet.

curl -X POST https://api.tbbnetwork.com/v1/branches/{id}/space-status \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "spaceStatus": "NOT_ENABLED"
}'

Parameters

id

path

required

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)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Acme Co.",
  "addressLine1": "addressLine1",
  "addressLine2": null,
  "city": "city",
  "region": null,
  "postalCode": null,
  "country": "US",
  "spaceStatus": "NOT_ENABLED",
  "createdAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

post/v1/businesses/{businessId}/merchant-links

Link a Merchant account to a Business (owner only, many-to-many)

curl -X POST https://api.tbbnetwork.com/v1/businesses/{businessId}/merchant-links \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Parameters

businessId

path

required

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)	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "ACTIVE",
  "linkedAt": "2026-07-01T12:00:00Z",
  "unlinkedAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/businesses/{businessId}/merchant-links

List a Business's linked Merchant accounts

curl -X GET https://api.tbbnetwork.com/v1/businesses/{businessId}/merchant-links \
  -H "Authorization: Bearer <session access token>" \

Parameters

businessId

path

required

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "ACTIVE",
    "linkedAt": "2026-07-01T12:00:00Z",
    "unlinkedAt": "2026-07-01T12:00:00Z"
  }
]

post/v1/businesses/{businessId}/merchant-links/{linkId}/revoke

Revoke a Business<->Merchant link (owner only)

curl -X POST https://api.tbbnetwork.com/v1/businesses/{businessId}/merchant-links/{linkId}/revoke \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \

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)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "ACTIVE",
  "linkedAt": "2026-07-01T12:00:00Z",
  "unlinkedAt": "2026-07-01T12:00:00Z"
}

Possible errors

Any other failure (validation, auth, rate limiting, a resource that doesn't exist) returns this same envelope with a non-2xx status — error.code is stable and safe to branch on; error.requestId is worth logging and including in a support request.

Example error response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A human-readable description of what went wrong.",
    "requestId": "req_01hxyz..."
  }
}

get/v1/business-merchant-links

The Businesses a Merchant is linked to. Requires that Merchant's own credential.

curl -X GET https://api.tbbnetwork.com/v1/business-merchant-links \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

merchantId

query

required

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "ACTIVE",
    "linkedAt": "2026-07-01T12:00:00Z",
    "unlinkedAt": "2026-07-01T12:00:00Z"
  }
]