TBBN.Merchant Platform docs
WORKING

Sellers

post/merchant/sellers/verify

Merchant-facing: register or match a seller after the MERCHANT has verified them. See docs/business/glossary.md "Identity federation" — sellers never call this directly.

Parameters

optional

Request body

FieldTypeRequired
namestringyes
verifiedEmailstring (email)yes
verifiedPhonestringyes
merchantSellerRefstringyes
merchantIdstring (uuid)yes

Response (200)

FieldTypeRequired
sellerIdstring (uuid)
requiresConfirmationboolean
post/merchant/sellers/headless

Merchant-facing: create a headless Seller (Phase 27) — a trade participant with no linked TBBN account, gated by the calling Merchant's plan tier.

Parameters

optional

Request body

FieldTypeRequired
merchantIdstring (uuid)yes
merchantSellerRefstringyes
namestringnull

Response (200)

FieldTypeRequired
idstring (uuid)
userIdstring,null (uuid)
primaryEmailstringnull
primaryPhonestringnull
reputationScoreintegernull
post/v1/oauth-clients

Register a Merchant's account-linking OAuth client (Phase 28)

Parameters

optional

Request body

FieldTypeRequired
merchantIdstring (uuid)yes
redirectUrisstring[]yes

Response (200)

FieldTypeRequired
idstring (uuid)
merchantIdstring (uuid)
clientIdstring
clientSecretstring
redirectUrisstring[]
statusACTIVE | REVOKED
createdAtstring (date-time)
get/v1/oauth-clients

List a Merchant's OAuth clients

Parameters

merchantIdqueryrequired

Response (200)

post/v1/oauth-clients/{id}/rotate-secret

Rotate an OAuth client's secret — the clientId is unchanged

Parameters

idpathrequired
optional

Response (200)

FieldTypeRequired
idstring (uuid)
merchantIdstring (uuid)
clientIdstring
clientSecretstring
redirectUrisstring[]
statusACTIVE | REVOKED
createdAtstring (date-time)
delete/v1/oauth-clients/{id}

Revoke an OAuth client

Parameters

idpathrequired
get/v1/link/oauth/clients/{clientId}

Public client metadata — used by apps/account-dashboard's consent screen to validate redirect_uri and render "Merchant X wants to link your TBBN profile" before showing Approve/Deny.

Parameters

clientIdpathrequired

Response (200)

FieldTypeRequired
clientIdstring
redirectUrisstring[]
merchantDisplayNamestringnull
post/v1/link/oauth/consent

Step 1 of the OAuth account-linking handshake (Phase 28) — the logged-in member approves. Creates a short-lived, single-use authorization code; the caller (the consent page) performs the actual redirect.

Request body

FieldTypeRequired
clientIdstringyes
redirectUristring (uri)yes
scopestringyes
codeChallengestring
codeChallengeMethodS256
merchantSellerRefstringyes

Response (200)

FieldTypeRequired
codestring
post/v1/link/oauth/token

Step 2 of the OAuth account-linking handshake — the Merchant's backend exchanges the code for a link. No access/refresh token is issued; this only ever establishes a seller_merchant_links row. See docs/business/conflict-resolution-log.md item 22.

Request body

FieldTypeRequired
grant_typeauthorization_codeyes
codestringyes
client_idstringyes
client_secretstringyes
redirect_uristring (uri)yes
code_verifierstring

Response (200)

FieldTypeRequired
sellerIdstring (uuid)
linkedboolean
get/v1/sellers/{id}

Resolve a marketplace member with all linked merchant accounts (internal/ops use)

Parameters

idpathrequired

Response (200)

FieldTypeRequired
idstring (uuid)
userIdstring,null (uuid)
primaryEmailstringnull
primaryPhonestringnull
reputationScoreintegernull
post/v1/sellers/{id}/unlink

Ops-only unlink of a merchant link (fraud/dispute remediation)

Parameters

idpathrequired
optional

Request body

FieldTypeRequired
merchantIdstring (uuid)yes