TBBN Developers

post/v1/merchants

Apply for a Merchant account for one of your Businesses (creates a 7-day temp account)

curl -X POST https://api.tbbnetwork.com/v1/merchants \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "repEmail": "you@example.com",
  "repName": "repName",
  "legalName": "Acme Co.",
  "displayName": "Acme Co.",
  "country": "US",
  "defaultCurrency": "USD",
  "businessId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Request body

Field	Type	Required
repEmail	string (email)	—
repName	string	—
legalName	string	—
displayName	string	—
country	string	—
defaultCurrency	string	—
businessId	string (uuid)	yes

Response (201)

Field	Type	Required
id	string (uuid)	—
legalName	string	—
displayName	string	—
logoUrl	string,null (uri)	—
slug	string	—
tier	SANDBOX \| STARTER \| GROWTH \| ENTERPRISE	—
status	TEMP_PENDING \| UNDER_REVIEW \| APPROVED \| SUSPENDED \| REJECTED	—
listingModeAllowed	string[]	—
matchingEnabled	boolean	—
checkoutEnabled	boolean	—
autoCloseUnreciprocatedTrades	boolean	—
counterpartyHoldDays	integernull	—
commissionRate	stringnull	—
passCheckoutFee	boolean	—
passProcessingFees	boolean	—
shipFromRegion	stringnull	—
country	string	—
defaultCurrency	string	—
createdAt	string (date-time)	—
approvedAt	string,null (date-time)	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "legalName": "Acme Co.",
  "displayName": "Acme Co.",
  "logoUrl": null,
  "slug": "example-slug",
  "tier": "SANDBOX",
  "status": "TEMP_PENDING",
  "listingModeAllowed": [
    "PRIVATE"
  ],
  "matchingEnabled": false,
  "checkoutEnabled": false,
  "autoCloseUnreciprocatedTrades": false,
  "counterpartyHoldDays": null,
  "commissionRate": null,
  "passCheckoutFee": false,
  "passProcessingFees": false,
  "shipFromRegion": null,
  "country": "US",
  "defaultCurrency": "USD",
  "createdAt": "2026-07-01T12:00:00Z",
  "approvedAt": "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/merchants/{id}

Get merchant

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

Parameters

id

path

required

Response (200)

Field	Type	Required
id	string (uuid)	—
legalName	string	—
displayName	string	—
logoUrl	string,null (uri)	—
slug	string	—
tier	SANDBOX \| STARTER \| GROWTH \| ENTERPRISE	—
status	TEMP_PENDING \| UNDER_REVIEW \| APPROVED \| SUSPENDED \| REJECTED	—
listingModeAllowed	string[]	—
matchingEnabled	boolean	—
checkoutEnabled	boolean	—
autoCloseUnreciprocatedTrades	boolean	—
counterpartyHoldDays	integernull	—
commissionRate	stringnull	—
passCheckoutFee	boolean	—
passProcessingFees	boolean	—
shipFromRegion	stringnull	—
country	string	—
defaultCurrency	string	—
createdAt	string (date-time)	—
approvedAt	string,null (date-time)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "legalName": "Acme Co.",
  "displayName": "Acme Co.",
  "logoUrl": null,
  "slug": "example-slug",
  "tier": "SANDBOX",
  "status": "TEMP_PENDING",
  "listingModeAllowed": [
    "PRIVATE"
  ],
  "matchingEnabled": false,
  "checkoutEnabled": false,
  "autoCloseUnreciprocatedTrades": false,
  "counterpartyHoldDays": null,
  "commissionRate": null,
  "passCheckoutFee": false,
  "passProcessingFees": false,
  "shipFromRegion": null,
  "country": "US",
  "defaultCurrency": "USD",
  "createdAt": "2026-07-01T12:00:00Z",
  "approvedAt": "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/merchants/{id}

Update merchant settings (ADMIN/OWNER only). Once status is APPROVED, also requires a step-up token scoped to "merchant:update" — see POST /v1/auth/step-up/confirm. A still-pending/under-review Merchant needs no step-up token.

curl -X PATCH https://api.tbbnetwork.com/v1/merchants/{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 '{
  "legalName": "Acme Co.",
  "displayName": "Acme Co.",
  "logoUrl": null,
  "slug": "example-slug",
  "country": "US",
  "defaultCurrency": "USD",
  "matchingEnabled": false,
  "checkoutEnabled": false,
  "counterpartyHoldDays": null,
  "autoCloseUnreciprocatedTrades": false,
  "commissionRate": 1,
  "passCheckoutFee": false,
  "passProcessingFees": false,
  "shipFromRegion": null,
  "checkoutEndpointUrl": null
}'

Parameters

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

Request body

Field	Type	Required
legalName	string	—
displayName	string	—
logoUrl	string,null (uri)	—
slug	string	—
country	string	—
defaultCurrency	string	—
matchingEnabled	boolean	—
checkoutEnabled	boolean	—
counterpartyHoldDays	integernull	—
autoCloseUnreciprocatedTrades	boolean	—
commissionRate	number	—
passCheckoutFee	boolean	—
passProcessingFees	boolean	—
shipFromRegion	stringnull	—
checkoutEndpointUrl	string,null (uri)	—

Response (200)

Field	Type	Required
id	string (uuid)	—
legalName	string	—
displayName	string	—
logoUrl	string,null (uri)	—
slug	string	—
tier	SANDBOX \| STARTER \| GROWTH \| ENTERPRISE	—
status	TEMP_PENDING \| UNDER_REVIEW \| APPROVED \| SUSPENDED \| REJECTED	—
listingModeAllowed	string[]	—
matchingEnabled	boolean	—
checkoutEnabled	boolean	—
autoCloseUnreciprocatedTrades	boolean	—
counterpartyHoldDays	integernull	—
commissionRate	stringnull	—
passCheckoutFee	boolean	—
passProcessingFees	boolean	—
shipFromRegion	stringnull	—
country	string	—
defaultCurrency	string	—
createdAt	string (date-time)	—
approvedAt	string,null (date-time)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "legalName": "Acme Co.",
  "displayName": "Acme Co.",
  "logoUrl": null,
  "slug": "example-slug",
  "tier": "SANDBOX",
  "status": "TEMP_PENDING",
  "listingModeAllowed": [
    "PRIVATE"
  ],
  "matchingEnabled": false,
  "checkoutEnabled": false,
  "autoCloseUnreciprocatedTrades": false,
  "counterpartyHoldDays": null,
  "commissionRate": null,
  "passCheckoutFee": false,
  "passProcessingFees": false,
  "shipFromRegion": null,
  "country": "US",
  "defaultCurrency": "USD",
  "createdAt": "2026-07-01T12:00:00Z",
  "approvedAt": "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/merchants/{id}/commission-rates

Every commission rate the Merchant has set, newest first.

curl -X GET https://api.tbbnetwork.com/v1/merchants/{id}/commission-rates \
  -H "Authorization: Bearer <session access token>" \

Parameters

id

path

required

Response (200)

Example 200 response

[
  {
    "rate": "rate",
    "effectiveFrom": "2026-07-01T12:00:00Z",
    "setByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  }
]

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/merchants/{id}/submit-application

Submit or resubmit onboarding documents during the 7-day temp window

curl -X POST https://api.tbbnetwork.com/v1/merchants/{id}/submit-application \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \

Parameters

id

path

required

Request body

Possible errors

410	Temp account expired

get/v1/merchants/{id}/application-status

Track onboarding application status

curl -X GET https://api.tbbnetwork.com/v1/merchants/{id}/application-status \
  -H "Authorization: Bearer <session access token>" \

Parameters

id

path

required

Response (200)

Field	Type	Required
status	SUBMITTED \| RESUBMISSION_REQUIRED \| UNDER_REVIEW \| APPROVED \| REJECTED \| EXPIRED	—
reviewerNotes	stringnull	—

Example 200 response

{
  "status": "SUBMITTED",
  "reviewerNotes": null
}

post/v1/merchants/{id}/users/invite

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

curl -X POST https://api.tbbnetwork.com/v1/merchants/{id}/users/invite \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "role": "ADMIN"
}'

Parameters

id

path

required

Request body

Field	Type	Required
email	string (email)	yes
role	ADMIN \| DEVELOPER \| ACCOUNT_MANAGER \| OPERATIONS \| ACCOUNTANT \| SUPPORT \| VIEWER	yes

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"
}

get/v1/merchants/{id}/invitations

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

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

Parameters

id

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/merchants/{id}/invitations/{invitationId}

Withdraw an invitation (Owner or Admin)

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

Parameters

id	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/merchants/invitations/mine

Invitations to Merchant teams waiting for you

curl -X GET https://api.tbbnetwork.com/v1/merchants/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/merchants/invitations/{invitationId}/accept

Accept an invitation and join the Merchant's team with its role

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

Parameters

invitationId

path

required

Response (201)

Field	Type	Required
merchantId	string (uuid)	—
merchantName	string	—
role	string	—

Example 201 response

{
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "merchantName": "merchantName",
  "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/merchants/invitations/{invitationId}/decline

Decline an invitation

curl -X POST https://api.tbbnetwork.com/v1/merchants/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..."
  }
}

get/v1/merchants/{id}/users

List merchant org users

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

Parameters

id

path

required

Response (200)

Field	Type	Required
data	object[]	—
nextCursor	stringnull	—

Example 200 response

{
  "data": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "role": "OWNER",
      "invitedAt": "2026-07-01T12:00:00Z",
      "acceptedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "nextCursor": null
}

patch/v1/merchants/{id}/users/{userId}/role

Change a team member's role (Owner or Admin; the Owner's role can't change)

curl -X PATCH https://api.tbbnetwork.com/v1/merchants/{id}/users/{userId}/role \
  -H "Authorization: Bearer <session access token>" \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "ADMIN"
}'

Parameters

id	path	required
userId	path	required

Request body

Field	Type	Required
role	ADMIN \| DEVELOPER \| ACCOUNT_MANAGER \| OPERATIONS \| ACCOUNTANT \| SUPPORT \| VIEWER	yes

Response (200)

Field	Type	Required
id	string (uuid)	—
merchantId	string (uuid)	—
userId	string (uuid)	—
role	OWNER \| ADMIN \| DEVELOPER \| ACCOUNT_MANAGER \| OPERATIONS \| ACCOUNTANT \| SUPPORT \| VIEWER	—
invitedAt	string (date-time)	—
acceptedAt	string,null (date-time)	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "role": "OWNER",
  "invitedAt": "2026-07-01T12:00:00Z",
  "acceptedAt": "2026-07-01T12:00:00Z"
}

delete/v1/merchants/{id}/users/{userId}

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

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

Parameters

id	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..."
  }
}

Merchants

Request body

Response (201)

Possible errors

Parameters

Response (200)

Possible errors

Parameters

Request body

Response (200)

Possible errors

Parameters

Response (200)

Possible errors

Parameters

Request body

Possible errors

Parameters

Response (200)

Parameters

Request body

Response (201)

Parameters

Response (200)

Possible errors

Parameters

Response (200)

Possible errors

Response (200)

Possible errors

Parameters

Response (201)

Possible errors

Parameters

Possible errors

Parameters

Response (200)

Parameters

Request body

Response (200)

Parameters

Possible errors