TBBN Developers

API Reference

TBBN Platform API — v0.1.0

TBBN infrastructure API — the identity federation, listing exchange, matching, offer/trade-session management, and checkout-orchestration surface your platform integrates against: Auth, Merchants, Businesses, API Keys, Sellers/Identity, Listings, Catalog, Media, Directory, Search, Trade Engine (settlement), Currency, Localization, Matching, Recommendations, Offers, Trade Sessions, Checkout, Billing, Notifications, Webhooks, Reputation, Analytics, Space, and Sandbox.

Production — sandbox vs. live is determined by which API key prefix you present (sk_sandbox_... or sk_live_...), not a different host or URL.: https://api.tbbnetwork.com

Resources

Every area of the API, with its endpoint count.

All endpoints

post/v1/auth/merchant/otp/requestRequest email OTP for merchant rep login

post/v1/auth/merchant/otp/verifyVerify merchant rep OTP and issue a session

post/v1/auth/merchant/switchMove a merchant session to another Merchant the person is on

post/v1/auth/merchant/accessOpen a Merchant from your TBBN sign-in

get/v1/auth/account/workplacesThe Businesses and Merchants you own or work for

post/v1/auth/member/registerDirect self-registration for a Marketplace profile — the primary way anyone joins TBBN now.

post/v1/auth/member/otp/verifyComplete self-registration and issue a session

post/v1/auth/seller/otp/requestRequest OTP for a marketplace member's direct TBBN Marketplace login

post/v1/auth/seller/otp/verifyVerify marketplace member OTP and issue a session

post/v1/auth/seller/magic-link/requestRequest a passwordless magic link for a marketplace member

get/v1/auth/seller/magic-link/consumeConsume a magic link token, issuing a session

post/v1/auth/refreshRotate a refresh token for a new access token

post/v1/auth/logoutRevoke the current session

get/v1/auth/meWho the credential belongs to. With an API key: the Merchant it's for and whether it's a test key (livemode false) — a quick way to check a key works. With a sign-in token: the signed-in account.

post/v1/auth/step-up/requestSend a fresh verification code to the signed-in caller's own account email. Sensitive actions (account deletion, editing an already-verified Business, Merchant or Space) need this code confirmed first, on top of the session.

post/v1/auth/step-up/confirmVerify the step-up code and receive a short-lived (5 minute), single-action token. Pass it back as X-TBBN-Step-Up-Token on the one request it was scoped for — a step-up token is never a substitute for that route's own principal/role check, only an added re-authentication layer on top of it.

get/v1/auth/account/exportDownload everything TBBN holds about the signed-in member, as JSON

post/v1/auth/account/deleteDelete the signed-in member's account

put/v1/auth/account/avatarSet the signed-in member's profile photo

delete/v1/auth/account/avatarRemove the signed-in member's profile photo

put/v1/auth/account/locationSave the signed-in member's approximate location

delete/v1/auth/account/locationClear the signed-in member's saved location

get/v1/auth/account/work-email/providersWhich school or work account sign-ins can verify an email (google, microsoft).

post/v1/auth/account/work-email/startStarts verifying a school or work email by signing in to that account. Send the member to url; they come back to tbbnetwork.com/account/work-email with code and state.

post/v1/auth/account/work-email/finishFinishes the sign-in as the same member who started it and adds the address to their account as verified. Only an address whose domain the organization owns is accepted.

post/v1/businessesCreate a Business, owned by the authenticated Marketplace member

get/v1/businessesList the authenticated Marketplace member's own Businesses

get/v1/businesses/{id}Get a Business

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.

delete/v1/businesses/{id}Soft-delete a Business (owner only)

post/v1/businesses/{businessId}/business-usersInvite someone to the team with a role (owner or Admin)

get/v1/businesses/{businessId}/business-usersList a Business's team (owner or Admin)

get/v1/businesses/{businessId}/invitationsThe team's invitations waiting for an answer (owner or Admin)

delete/v1/businesses/{businessId}/invitations/{invitationId}Withdraw an invitation (owner or Admin)

get/v1/businesses/invitations/mineInvitations to Business teams waiting for you

post/v1/businesses/invitations/{invitationId}/acceptAccept an invitation and join the team with its role

post/v1/businesses/invitations/{invitationId}/declineDecline an invitation

patch/v1/businesses/{businessId}/business-users/{userId}Change a team member's role or locations (owner or Admin)

delete/v1/businesses/{businessId}/business-users/{userId}Remove a team member (owner or Admin; the owner can't be removed)

post/v1/businesses/{businessId}/branchesAdd a Branch (location) to a Business (owner only)

get/v1/businesses/{businessId}/branchesList a Business's Branches

patch/v1/branches/{id}Update a Branch (owner only)

delete/v1/branches/{id}Remove a Branch (owner only)

post/v1/branches/{id}/space-statusToggle a Branch's Space eligibility flag (owner only). Hook only — no Space product logic exists yet.

post/v1/businesses/{businessId}/merchant-linksLink a Merchant account to a Business (owner only, many-to-many)

get/v1/businesses/{businessId}/merchant-linksList a Business's linked Merchant accounts

post/v1/businesses/{businessId}/merchant-links/{linkId}/revokeRevoke a Business<->Merchant link (owner only)

get/v1/business-merchant-linksThe Businesses a Merchant is linked to. Requires that Merchant's own credential.

post/v1/reputation/reviewsSubmit a 1-5 star review of a Merchant or a Space Branch — must be tied to a real completed trade session or Space booking the reviewer was actually a party to.

get/v1/reputation/merchants/{id}/reviewsA Merchant's reviews plus aggregate rating

get/v1/reputation/branches/{id}/reviewsA Space Branch's reviews plus aggregate rating

get/v1/reputation/businesses/{id}/reviews-summaryAggregate rating across every Merchant and Branch linked to a Business.

post/v1/merchantsApply for a Merchant account for one of your Businesses (creates a 7-day temp account)

get/v1/merchants/{id}Get merchant

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.

get/v1/merchants/{id}/commission-ratesEvery commission rate the Merchant has set, newest first.

post/v1/merchants/{id}/submit-applicationSubmit or resubmit onboarding documents during the 7-day temp window

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

post/v1/merchants/{id}/users/inviteInvite someone to the team with a role (Owner or Admin)

get/v1/merchants/{id}/invitationsThe team's invitations waiting for an answer (Owner or Admin)

delete/v1/merchants/{id}/invitations/{invitationId}Withdraw an invitation (Owner or Admin)

get/v1/merchants/invitations/mineInvitations to Merchant teams waiting for you

post/v1/merchants/invitations/{invitationId}/acceptAccept an invitation and join the Merchant's team with its role

post/v1/merchants/invitations/{invitationId}/declineDecline an invitation

get/v1/merchants/{id}/usersList merchant org users

patch/v1/merchants/{id}/users/{userId}/roleChange a team member's role (Owner or Admin; the Owner's role can't change)

delete/v1/merchants/{id}/users/{userId}Remove a team member (Owner or Admin; the Owner can't be removed)

post/v1/api-keysCreate an API key (ADMIN/OWNER only; production keys require ADMIN+ approval)

get/v1/api-keysList API keys (never returns the full key, only the prefix)

post/v1/api-keys/{id}/rotateRotate a key (old key marked ROTATED, still valid for a grace window)

delete/v1/api-keys/{id}Revoke a key immediately

post/merchant/sellers/verifyMerchant-facing: register or match a seller after the MERCHANT has verified them. See the Glossary guide "Identity federation" — sellers never call this directly.

post/merchant/sellers/headlessMerchant-facing: create a headless Seller — a trade participant with no linked TBBN account, gated by the calling Merchant's plan tier.

post/merchant/sellers/link-codeRedeem a customer's TBBN link code — the one-time code they made in their TBBN account (Linked stores → Link a store) and entered in their account on your site. Links their TBBN account to your store as the OAuth handshake does, under your reference for them (merchant_seller_ref, optional — without it the link is keyed by their TBBN seller id). A code works once, for 30 minutes; a failed link (409) leaves it usable.

post/v1/oauth-clientsRegister a Merchant's account-linking OAuth client

get/v1/oauth-clientsList a Merchant's OAuth clients

post/v1/oauth-clients/{id}/rotate-secretRotate an OAuth client's secret — the clientId is unchanged

delete/v1/oauth-clients/{id}Revoke an OAuth client

get/v1/link/oauth/clients/{clientId}Public client metadata — used by TBBN's account consent screen to validate redirect_uri and render "Merchant X wants to link your TBBN profile" before showing Approve/Deny.

post/v1/link/oauth/consentStep 1 of the OAuth account-linking handshake — the logged-in member approves. Creates a short-lived, single-use authorization code; the caller (the consent page) performs the actual redirect.

post/v1/link/oauth/tokenExchange an account-linking authorization code for the link — from your server, within 5 minutes, once. Returns the seller's id; no access or refresh token is issued. See the Seller account linking guide.

get/v1/sellers/me/linksList the stores the signed-in member's account is linked to

post/v1/sellers/me/link-codesMake a one-time link code (30 minutes) the signed-in member gives a store to link their account. At most five unused at once.

get/v1/sellers/me/storefrontThe signed-in member's storefront address (tbbnetwork.com/store/{slug}) and bio; the address is made from their name the first time.

patch/v1/sellers/me/storefrontChange the storefront's address or bio

get/v1/sellers/me/linkable-storesStores where a member connects their TBBN account on the store's own site

delete/v1/sellers/me/links/{merchantId}Unlink the signed-in member from a store

get/v1/sellersList your linked sellers, newest link first

post/v1/sellers/{id}/unlinkUnlink one of your sellers. Your live listings for that seller come down; refused (409) while a trade through your store is in progress.

get/merchant/listingsYour own catalogue — every listing you've sent, in any status but deleted (live, in a trade, taken down, sold, held for review, removed by TBBN), newest first, with counts per status. Search titles and your own references with q. A team member signed in to the dashboard can always read it; changing a listing needs a role with the catalogue permission.

post/merchant/listingsCreate or sync a listing. Upserts on (merchantId, merchantListingRef) — a repeat call with the same ref updates the existing listing rather than creating a duplicate. A listing sync is counted when this creates or changes a listing; sending it again unchanged is free. See the integration walkthrough's "Sync your listings".

put/merchant/listings/{id}Update a listing by id (partial — only supplied fields change)

delete/merchant/listings/{id}Soft-delete a listing

post/merchant/listings/{id}/availabilityReport an availability change for one of your listings — SOLD or UNAVAILABLE when it sells or goes out of stock elsewhere, ACTIVE when it's available again. TBBN sets RESERVED itself while the item is part of a trade.

put/merchant/listings/{id}/wantsReplace a listing's wants array (full replace, not merge) — see the Glossary guide "Wants"

get/v1/listings/{id}/wantsRead a listing's wants array

get/v1/merchant/feed-sourceThis merchant's catalog feed configuration — see the Catalog feed guide.

post/v1/merchant/feed-sourceCreate or replace this merchant's feed source config

post/v1/merchant/feed-source/fetch-nowManual fetch, doesn't wait for the 24h scheduled cycle — same escape hatch Google/Meta's own scheduled-feed UIs both offer.

get/v1/listings/{id}Get a listing

get/v1/listingsDirectory-lite listing read across all visibilities the caller is entitled to — full ranked search lives in Search/Matching

post/v1/listings/individualCreate a listing of your own as a signed-in member (no merchant). The seller is always the signed-in member.

get/v1/listings/mineEvery listing the signed-in member created, in every status except deleted. The public listing read returns only what is available; this is how an owner sees their Pending and Sold items.

post/v1/listings/individual/{id}/availabilitySet one of your own listings to Available (ACTIVE), Pending (RESERVED) or Sold. Only the member who created the listing may change it; merchant-synced listings are managed on the merchant's platform.

put/v1/listings/individual/{id}Edit one of your own listings

delete/v1/listings/individual/{id}Remove one of your own listings

get/v1/platform/statusLaunch state of the platform and any per-country overrides

get/v1/platform/marketsCountries with their own site on tbbnetwork.com

get/v1/platform/availabilityWhere TBBN is available, and which services each country has

get/v1/platform/countries/{country}What TBBN offers in a country right now — identity verification, business verification, merchant accounts, Space hosting, payments, payouts, marketplace listings — plus the per-country form configuration (labels and required fields) every onboarding form reads.

get/v1/platform/pricingWhat TBBN charges in a country — plans, usage rates, top-ups and Space fees

get/v1/blog/postsPublished blog posts, sorted and filtered

get/v1/blog/taxonomyCategories and tags used on published posts, with post counts

get/v1/blog/indexEvery published post's address and dates, for sitemaps and feeds

get/v1/blog/posts/{slug}One published post, with related posts

get/v1/blog/posts/{slug}/commentsA post's comments, with replies under the comment they answer

post/v1/blog/posts/{slug}/commentsComment on a post, or reply to a comment

put/v1/blog/posts/{slug}/likeLike a post (liking twice changes nothing)

delete/v1/blog/posts/{slug}/likeTake back a like

post/v1/blog/posts/{slug}/viewCount a read of a post (send once a visit)

post/v1/blog/posts/{slug}/shareCount a share of a post

delete/v1/blog/comments/{id}Delete your own comment

get/v1/blog/manage/meYour blog role (AUTHOR or EDITOR) and publishing name; 403 if you don't write for the blog

patch/v1/blog/manage/meSet the name you publish under

get/v1/blog/manage/postsPosts you can manage — your own as an author, every post as an editor

post/v1/blog/manage/postsStart a post (as a draft)

get/v1/blog/manage/posts/{id}A post you can manage, in full

patch/v1/blog/manage/posts/{id}Edit a post

delete/v1/blog/manage/posts/{id}Delete a post, with its likes and comments (editors; authors only their drafts)

post/v1/blog/manage/posts/{id}/publishPublish a post now, or schedule it with at

post/v1/blog/manage/posts/{id}/unpublishTake a post off the blog (back to a draft, or archived if it was public)

get/v1/blog/manage/commentsComments to moderate on the posts you manage

patch/v1/blog/manage/comments/{id}Hide a comment, or show it again

get/v1/agreements/{kind}/currentThe current version of an agreement (business-profile, merchant, space-host, trade-terms)

get/v1/agreements/statusWhich agreements the signed-in person has accepted at their current version

post/v1/agreements/{kind}/acceptAccept the current version of an agreement. Idempotent per person and version.

get/v1/identity/statusThe signed-in person's identity verification status — unverified, pending, verified or needs attention — whether verification is offered in their country, and their latest attempt. A pending attempt is refreshed from the provider on read.

post/v1/identity/sessionsStart an identity check (government ID + selfie). Returns the hosted page to send the person to; they come back to the return URL when done and the status endpoint reflects the outcome. Only where the country access matrix offers identity verification.

post/v1/waitlist/demo-requestsRequest a product demo (public — no credential required)

get/v1/catalog/categoriesList all top-level categories in the taxonomy

get/v1/catalog/categories/{category}/subcategoriesList subcategories under a category

get/v1/catalog/brandsList brands, optionally scoped to a category and/or subcategory

post/v1/media/ingestCopy listing images from public https:// addresses (JPEG, PNG, WebP or GIF, decided from the image itself, so an address needs no file extension; at most 5 per call; each is resized to fit 1600px and stored as WebP) into TBBN-hosted URLs for a listing's images array. Every image is tried. If any can't be imported, the call returns 400 IMAGE_IMPORT_FAILED with details.images listing each one — ok, or the stage that failed (address, download, size, decode, store), whether retrying may work, and why — and details.retryable true when every failure is worth retrying. A refusal is not kept against your Idempotency-Key, so once the cause is fixed a retry with the same key runs again.

post/v1/media/uploadUpload a photo through TBBN, base64 in data — for when a direct upload to the presigned URL from POST /v1/media/upload-url isn't possible. The photo is resized to fit 1600px and stored as WebP. Same callers as upload-url.

post/v1/media/upload-urlGet a short-lived upload URL for an image. The browser uploads the file directly to it. PUT the file to `uploadUrl` with the same Content-Type, then use `publicUrl` wherever an image URL is needed (e.g. a Listing's images array).

get/v1/directory/listingsPublic global-directory listing read. Only GLOBAL/BOTH-visibility listings ever appear here — PRIVATE and ENTERPRISE never do. See the Glossary guide "Global vs Private vs Both vs Enterprise".

get/v1/listings/{id}/visitA shopper's link to a store's own item page (the listing's merchantItemUrl): redirects there (302) and counts a store visit, billed to the store at the store-visit price — once per shopper per listing per day; crawlers and link previews are never counted. Link to this rather than to merchantItemUrl directly. v is the site's own visitor id, when it has one. 404 when the listing has no https store page.

get/v1/directory/storefronts/{slug}A member's public storefront: their name, bio, photo, whether they've verified their identity, reputation, completed swaps and general location, and the items they listed themselves (never a store's listings of their items) — public ones only, 24 a page.

get/v1/directory/listings/{id}Get a single listing from the public global directory

post/v1/search/listingsPlain filtered/keyword listing search, no compatibility scoring (compatibility scoring lives in Matching). query does a case-insensitive contains match across title, brand, subcategory, and model; minTradeValue/maxTradeValue filter on the computed TradeValue = OriginalPrice + RequestedAmount - WillingToPay.

post/v1/trade-engine/settlementCompute a trade's settlement — each side's value and who owes whom (TradeValue = OriginalPrice + RequestedAmount - WillingToPay per listing). All listings in a trade must share one currency; a trade mixing currencies is rejected.

get/v1/currency/supportedList supported currency codes

post/v1/currency/convertConvert an amount between supported currencies using static reference rates. Estimate only — never authoritative for settlement (see TradeEngine, which rejects cross-currency trades outright rather than trusting these rates).

get/v1/localization/countriesList supported countries

get/v1/localization/languagesList supported languages

get/v1/localization/locateWhere the caller's connection seems to be: country, and region and city when known. For filling a place in the background; ask the person when city is null. A signed-in member can pass their device's coordinates to get the city there instead.

post/v1/localization/normalize-phoneNormalize a phone number to a canonical format

post/v1/matching/candidatesThe best swap candidates for one of your listings, within its visibility (PRIVATE, GLOBAL or BOTH), ranked by Trade Compatibility Score — only listings open to swaps (TRADE or BOTH), in the same currency, from other sellers. A SALE listing has none.

post/v1/matching/scoreDirect pairwise Trade Compatibility Score for two known listings — used to preview compatibility before sending an offer

get/v1/recommendations/sellers/{sellerId}Personalized "for you" feed for a seller: the best trade candidates across all of the seller's active listings, each shown once.

post/v1/offersCreate an offer. listingIdsA is the existing listing(s) being offered ON, owned by toSellerId; listingIdsB is the listing(s) offered IN EXCHANGE, owned by fromSellerId.

get/v1/offersList offers for a seller

post/v1/offers/quoteThe trade quote for a proposed offer — what each trader pays, at which store — to show the sender before sending. Pass its fingerprint to POST /v1/offers. problems lists any store that hasn't finished its trade setup; such an offer can't be sent.

get/v1/offers/{id}/quoteAn offer's trade quote — locked once the offer is accepted, otherwise the current one — and whether each party has confirmed it. If the current quote differs from the one confirmed, both confirmations are cleared.

post/v1/offers/{id}/quote/acknowledgeA party confirms they've seen the offer's current quote — needed from the sender again when the quote changed after sending, or after 72 hours. Refused with 409 QUOTE_CHANGED if the fingerprint isn't the current one.

get/v1/offers/{id}Get an offer. A PENDING offer past its expiresAt is lazily transitioned to EXPIRED on read.

post/v1/offers/{id}/acceptAccept a PENDING offer — only the recipient (toSellerId) may accept, confirming the quote they were shown (GET /v1/offers/{id}/quote) by its fingerprint. Accepting locks the quote: the trade's checkouts are opened from it. Refused with 409 QUOTE_CHANGED if the quote has changed, or QUOTE_AWAITING_SENDER if the sender's confirmation is for an older quote or more than 72 hours old. The trade session follows shortly after (offer.accepted, then trade.created).

post/v1/offers/{id}/rejectReject a PENDING offer — only the recipient (toSellerId) may reject

post/v1/offers/{id}/cancelCancel a DRAFT or PENDING offer — only the sender (fromSellerId) may cancel

post/v1/offers/{id}/counterCounter a PENDING offer — only the recipient may counter. Creates a brand-new offer with sender/recipient roles swapped and moves the original offer to COUNTERED; the two are linked only via the offer.countered event, not a foreign key.

get/v1/trade-sessionsList trade sessions for a seller (as either sellerA or sellerB). Trade sessions are always system-generated from an accepted offer, never created directly via this API.

get/v1/trade-sessions/recordsYour trade records, for your books

get/v1/trade-sessions/{id}Get a trade session

post/v1/trade-sessions/{id}/cancelCancel a trade session — carries no consequence to either party. Only a party to the trade (sellerA or sellerB) may cancel, and only before the session reaches a terminal status, or — on a MERCHANT_CHECKOUT trade — before either checkout has been paid; once one has, the trade can only be closed with close-unreciprocated, after the hold. Releases any RESERVED reservations as a side effect.

post/v1/trade-sessions/{id}/close-unreciprocatedCloses a trade where one checkout was paid and the other never was. Each trader checks out with the store of the items they receive, so the unpaid checkout is one trader's items that the other trader never paid for. Either trader may close it — only once the hold has elapsed since the paid checkout (a floor — they may wait longer). `note` is required and is kept on the session; the trade can never be resumed or completed after this. Releases the unpaid checkout's items back to their seller; the paid checkout stands, and that trader receives what they paid for.

post/v1/trade-sessions/{id}/excuse-fulfillmentA Merchant whose own trade checkout was never paid excuses itself from it, once the hold has elapsed since the other checkout was paid: its items are released back to its seller and the trade closes. The other checkout stands. Merchant-credential only (no actingSellerId — this is a Merchant action, not a Seller one). `note` is required.

post/v1/trade-sessions/{id}/external-settlementReport how a matching-only side settled on your own platform

post/v1/trade-sessions/{id}/external-settlement/extendExtend a matching-only side's report deadline once

post/v1/trade-sessions/{id}/acknowledge-hold-termsRecords that the caller's side was shown and agreed to this trade's real hold terms (see GET :id's `holdTerms` field) before completing checkout on a MERCHANT_CHECKOUT trade.

post/v1/trade-sessions/{id}/scheduling/confirmPeer-to-peer trade completion — either party confirms the exchange happened on their side. Once both sides have confirmed, the session moves to COMPLETED.

post/v1/trade-sessions/{id}/scheduling/failEither party reports the peer-to-peer exchange failed (no-show, item mismatch)

post/v1/trade-sessions/{id}/space-proposalsPropose a Space to meet at for a peer-to-peer trade

get/v1/trade-sessions/{id}/space-proposalsList a trade's meeting-place proposals, newest first

post/v1/trade-sessions/{id}/space-proposals/{proposalId}/declineDecline the other trader's meeting-place proposal

post/v1/trade-sessions/{id}/space-proposals/{proposalId}/acceptAccept the other trader's meeting-place proposal

post/v1/checkout/webhooks/paymentMerchant-facing payment status callback (mirrors the payment.completed/payment.failed webhook catalog entries). `side` is your side — the side whose items your checkout sells; the trader paying there is the other side's, receiving those items. A completed payment clears your side to ship them immediately, independent of the other checkout. If this is the first checkout paid, starts the counterparty hold (trade.counterparty_hold_started) rather than waiting on the other checkout at all. Rejected once the trade session has reached a terminal status (including CLOSED_UNRECIPROCATED) — a closed trade can never be paid into again.

post/v1/checkout/webhooks/fulfillmentMerchant-facing fulfillment status callback, per-side: `started` requires only that this same `side`'s own payment is COMPLETE, regardless of the other side. The whole trade session auto-completes once both sides report `completed` — no separate step needed. Rejected once the session has reached a terminal status.

get/v1/checkout/paymentsGet both sides' payment records for a trade session

get/v1/conversationsYour conversations about members' listings — items you asked about, and your own items people asked you about — newest first.

get/v1/inboxEvery conversation you're in — about items, on your trades, and with Spaces, as a guest or a host — newest first, with what's unread in each.

get/v1/inbox/summaryHow many messages you haven't read, in total and by kind

get/v1/conversations/unread-countHow many of your conversations have messages you haven't read

get/v1/conversations/listings/{listingId}Your conversation about a listing, if you've started one

post/v1/conversations/listings/{listingId}Ask the person who listed an item about it. Carries on your conversation about it if you have one. A member's own listing only — not a store's.

get/v1/conversations/{id}A conversation and its messages, oldest first. Reading it marks it read for you.

post/v1/conversations/{id}/messagesReply in a conversation about a listing

post/v1/messagesSend a message on a trade — the sender is derived from the caller's own session

get/v1/messages/{tradeSessionId}List a trade's visible messages, oldest first — caller must be one of its two sellers

post/v1/messages/{id}/reportReport a message. It is hidden while TBBN reviews it. Caller must be a party to the message's trade.

post/v1/billing/subscriptionsCreate a Business's SaaS subscription

get/v1/billing/subscriptions/{businessId}Get a Business's current active SaaS subscription

post/v1/billing/subscriptions/{businessId}/change-tierChange a Business's subscription tier

post/v1/billing/subscriptions/{businessId}/cancelCancel a Business's subscription

post/v1/billing/subscriptions/{businessId}/confirm-payment-methodPay-As-You-Go card capture, step 2 — save the payment method Stripe.js resolved the SetupIntent to

get/v1/billing/pricing/{businessId}What TBBN charges this Business, in its billing currency

get/v1/billing/merchant/summaryYour Merchant's plan — its Business's — and this period's usage: for each service, your own count (rawCount), your Business's total across its Merchants (businessCount, what the allowance is measured against) and the plan's allowance (included; null means unlimited). Works with an API key or a merchant dashboard session whose role can see billing or analytics. Without a paid plan, the tier is SANDBOX and the period is the calendar month.

get/v1/billing/usage/{businessId}A Business's current (or specified) billing-period metered usage, aggregated across every Merchant linked to it, including the cross-merchant multiplier breakdown and priced overage per event type. See the Pricing reference.

get/v1/billing/invoices/{businessId}A Business's invoices

get/v1/billing/statements/{businessId}Consolidated Business billing statement — merchantPlan (owed) and spaceEarnings (already paid out, net of commission) as two separate sections, never merged into one number.

get/v1/notificationsYour notifications, newest first — what happened and where it opens

get/v1/notifications/unread-countHow many of your notifications are unread

post/v1/notifications/read-allMark all your notifications read

post/v1/notifications/{id}/readMark a notification read

get/v1/notifications/unsubscribePublic unsubscribe-center status (no auth) — pre-fills which categories an email is already opted out of. `token` (from an emailed unsubscribe link) only improves this prefill UX; without a valid one the form just shows nothing pre-ticked, since unsubscribe itself never requires one.

post/v1/notifications/unsubscribeOpt an email out of the given categories (no auth — this is how every public unsubscribe link works, logged in or not). SECURITY mail can never be opted out of. Submitting an empty array re-subscribes to everything.

get/v1/notifications/preferencesThe authenticated, stronger override the public unsubscribe form doesn't expose — the caller's own email is resolved server-side from their principal, never client-supplied.

patch/v1/notifications/preferencesSet the authenticated caller's own category opt-outs, plus the allNonEssentialEmailOptOut master switch (checked first, ahead of any per-category opt-out, and automatically covers a category added in the future).

post/v1/webhooks/subscriptionsSubscribe to events. events is an array of event-type strings (e.g. offer.accepted) or ["*"] for every event. See the Events & webhook catalog guide for the full list. The signing secret is returned with the subscription. The url must be a public https address.

get/v1/webhooks/subscriptionsList a merchant's webhook subscriptions

patch/v1/webhooks/subscriptions/{id}Rename a webhook subscription, move it to a new address or change its events. The signing secret is kept, so your receiver needs no change.

post/v1/webhooks/subscriptions/{id}/disableDisable a webhook subscription — no request body; ownership is derived from the subscription itself plus the calling merchant's own credential, not a body claim.

get/v1/webhooks/deliveriesList webhook deliveries for one of your subscriptions. subscriptionId is required.

post/v1/webhooks/deliveries/{id}/replayReplay a delivery — must be idempotent on the merchant's receiving end, since the original attempt(s) may also have succeeded after all retries appeared exhausted.

post/v1/webhooks/business-subscriptionsRegister a Business webhook — fires on Space booking lifecycle events (space_booking.created/consent_required/consented/paid/cancelled/completed/no_show) and, with includeMerchantEvents, on the trade, offer, listing and checkout events of every Merchant the Business runs. Requires the Owner, an Admin or a Developer on the Business. The url must be a public https address.

get/v1/webhooks/business-subscriptionsList a Business's webhook subscriptions

patch/v1/webhooks/business-subscriptions/{id}Rename a Business webhook, move it to a new address, change its events or whether it carries your Merchants' events. The signing secret is kept.

post/v1/webhooks/business-subscriptions/{id}/disableDisable a Business webhook subscription — no request body; ownership is derived from the subscription itself plus the caller's own session, not a body claim.

get/v1/webhooks/business-deliveriesList Business webhook deliveries for one of your subscriptions. subscriptionId is required.

post/v1/webhooks/business-deliveries/{id}/replayReplay a Business webhook delivery

get/v1/reputation/sellers/{id}Get a seller's reputation score (0-100). A new seller starts at the neutral baseline of 50.

get/v1/analytics/overviewGMV, trade volume, offer-acceptance match rate, and completion rate over a date range (default: trailing 30 days) for your own merchant — merchantId, if supplied, must match the caller.

post/v1/sandbox/test-accountSwitch on test mode for the signed-in rep's Merchant

get/v1/sandbox/test-accountThe signed-in rep's test account

get/v1/sandbox/fixturesCanned example request payloads (listing sync, offer create, matching candidates) for docs-site's live "try it" widgets — real shapes matching each service's actual DTOs

TBBN Platform API — v0.1.0

Resources

Auth

Businesses

Reputation

Merchants

ApiKeys

Sellers

Listings

Platform

Blog

Catalog

Media

Directory

Search

TradeEngine

Currency

Localization

Matching

Recommendations

Offers

TradeSessions

Checkout

Messages

Billing

Notifications

Webhooks

Analytics

Sandbox

All endpoints