Available

TradeSessions

get/v1/trade-sessions

List 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.

curl -X GET https://api.tbbnetwork.com/v1/trade-sessions \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

sellerId

query

required

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "DRAFT",
    "fulfillmentMode": "MERCHANT_CHECKOUT",
    "tradeValue": null,
    "currency": "USD",
    "quote": null,
    "checkouts": [
      {
        "side": "A",
        "buyerSide": "A",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantName": "merchantName",
        "commissionRate": null,
        "taxBase": 1,
        "differenceOwed": 1,
        "commissionDue": 1,
        "commissionOffset": 1,
        "commissionShortfall": 1,
        "checkoutFee": 1,
        "processingFeesPassed": false,
        "total": 1,
        "sellerNetCash": 1,
        "shipFromRegion": null,
        "settlement": "TBBN_CHECKOUT",
        "checkoutUrl": null,
        "link": null,
        "paymentStatus": null,
        "paidAt": "2026-07-01T12:00:00Z"
      }
    ],
    "createdAt": "2026-07-01T12:00:00Z",
    "updatedAt": "2026-07-01T12:00:00Z",
    "expiresAt": "2026-07-01T12:00:00Z",
    "lockedAt": "2026-07-01T12:00:00Z",
    "completedAt": "2026-07-01T12:00:00Z",
    "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
    "lastReminderSentAt": "2026-07-01T12:00:00Z",
    "closeNote": null,
    "listingsA": [
      {}
    ],
    "listingsB": [
      {}
    ],
    "reservations": [
      {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "side": "A",
        "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "status": "PENDING",
        "reservedAt": "2026-07-01T12:00:00Z",
        "releasedAt": "2026-07-01T12:00:00Z"
      }
    ],
    "payments": [
      {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "side": "A",
        "status": "PENDING",
        "merchantCheckoutSessionRef": null,
        "amount": 1,
        "breakdown": null,
        "currency": "USD",
        "completedAt": "2026-07-01T12:00:00Z",
        "failedReason": null,
        "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
        "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
        "settlement": "TBBN_CHECKOUT",
        "externalSettlementDueAt": "2026-07-01T12:00:00Z",
        "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
        "externalSettlementExtensionReason": null
      }
    ]
  }
]

get/v1/trade-sessions/records

Your trade records, for your books

curl -X GET https://api.tbbnetwork.com/v1/trade-sessions/records \
  -H "Authorization: Bearer sk_sandbox_..." \

Parameters

from	query	optional
to	query	optional

Response (200)

Field	Type	Required
from	string (date-time)	—
to	string (date-time)	—
records	object[]	—

Example 200 response

{
  "from": "2026-07-01T12:00:00Z",
  "to": "2026-07-01T12:00:00Z",
  "records": [
    {
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "status",
      "createdAt": "2026-07-01T12:00:00Z",
      "completedAt": "2026-07-01T12:00:00Z",
      "currency": "USD",
      "side": "A",
      "yourItems": [],
      "yourOriginalPrice": 1,
      "yourTradeValue": 1,
      "theirItems": [],
      "theirOriginalPrice": 1,
      "theirTradeValue": 1,
      "counterparty": {
        "kind": "MERCHANT",
        "name": "Acme Co."
      },
      "cashAddedToOffer": 1,
      "youCollected": 1,
      "theyCollected": 1,
      "commissionRate": null,
      "commissionAmount": null,
      "commissionOffset": null,
      "commissionShortfall": null,
      "checkoutFeeCollected": null,
      "sellerNetCash": null,
      "settlement": "TBBN_CHECKOUT",
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z",
      "merchantCheckoutSessionRef": null,
      "fulfilledAt": "2026-07-01T12:00:00Z",
      "termsFrozen": false
    }
  ]
}

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/trade-sessions/{id}

Get a trade session

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

Parameters

path

required

Response (200)

Field	Type	Required
id	string (uuid)	—
offerId	string,null (uuid)	—
sellerAId	string (uuid)	—
sellerBId	string (uuid)	—
status	DRAFT \| PENDING \| OFFERED \| ACCEPTED \| RESERVING \| RESERVED \| WAITING_CHECKOUT_A \| WAITING_CHECKOUT_B \| EXTERNAL_SETTLEMENT \| CHECKOUT_A_COMPLETE \| CHECKOUT_B_COMPLETE \| SCHEDULING_A \| SCHEDULING_B \| EXCHANGE_A_CONFIRMED \| EXCHANGE_B_CONFIRMED \| EXCHANGE_FAILED \| LOCKED \| FULFILLMENT \| FULFILLED \| COMPLETED \| CANCELLED \| CLOSED_UNRECIPROCATED \| EXPIRED \| PAYMENT_FAILED \| RESERVATION_FAILED \| FULFILLMENT_FAILED \| RETURNED \| REFUNDED	—
fulfillmentMode	MERCHANT_CHECKOUT \| PEER_TO_PEER	—
tradeValue	numbernull	—
currency	string	—
quote	object	—
checkouts	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
expiresAt	string,null (date-time)	—
lockedAt	string,null (date-time)	—
completedAt	string,null (date-time)	—
counterpartyHoldStartedAt	string,null (date-time)	—
lastReminderSentAt	string,null (date-time)	—
closeNote	stringnull	—
listingsA	object[]	—
listingsB	object[]	—
reservations	object[]	—
payments	object[]	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "fulfillmentMode": "MERCHANT_CHECKOUT",
  "tradeValue": null,
  "currency": "USD",
  "quote": null,
  "checkouts": [
    {
      "side": "A",
      "buyerSide": "A",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName",
      "commissionRate": null,
      "listingIds": [],
      "taxBase": 1,
      "differenceOwed": 1,
      "commissionDue": 1,
      "commissionOffset": 1,
      "commissionShortfall": 1,
      "checkoutFee": 1,
      "processingFeesPassed": false,
      "total": 1,
      "sellerNetCash": 1,
      "shipFromRegion": null,
      "settlement": "TBBN_CHECKOUT",
      "checkoutUrl": null,
      "link": null,
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z"
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z",
  "lockedAt": "2026-07-01T12:00:00Z",
  "completedAt": "2026-07-01T12:00:00Z",
  "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
  "lastReminderSentAt": "2026-07-01T12:00:00Z",
  "closeNote": null,
  "listingsA": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "listingsB": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "reservations": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "PENDING",
      "reservedAt": "2026-07-01T12:00:00Z",
      "releasedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "payments": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "status": "PENDING",
      "merchantCheckoutSessionRef": null,
      "amount": 1,
      "breakdown": null,
      "currency": "USD",
      "completedAt": "2026-07-01T12:00:00Z",
      "failedReason": null,
      "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
      "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
      "settlement": "TBBN_CHECKOUT",
      "externalSettlementDueAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtensionReason": null
    }
  ]
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/cancel

Cancel 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.

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/cancel \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "actingSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "reason": "Customer requested cancellation."
}'

Parameters

path

required

Request body

Field	Type	Required
actingSellerId	string (uuid)	yes
reason	string	—

Response (201)

Field	Type	Required
id	string (uuid)	—
offerId	string,null (uuid)	—
sellerAId	string (uuid)	—
sellerBId	string (uuid)	—
status	DRAFT \| PENDING \| OFFERED \| ACCEPTED \| RESERVING \| RESERVED \| WAITING_CHECKOUT_A \| WAITING_CHECKOUT_B \| EXTERNAL_SETTLEMENT \| CHECKOUT_A_COMPLETE \| CHECKOUT_B_COMPLETE \| SCHEDULING_A \| SCHEDULING_B \| EXCHANGE_A_CONFIRMED \| EXCHANGE_B_CONFIRMED \| EXCHANGE_FAILED \| LOCKED \| FULFILLMENT \| FULFILLED \| COMPLETED \| CANCELLED \| CLOSED_UNRECIPROCATED \| EXPIRED \| PAYMENT_FAILED \| RESERVATION_FAILED \| FULFILLMENT_FAILED \| RETURNED \| REFUNDED	—
fulfillmentMode	MERCHANT_CHECKOUT \| PEER_TO_PEER	—
tradeValue	numbernull	—
currency	string	—
quote	object	—
checkouts	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
expiresAt	string,null (date-time)	—
lockedAt	string,null (date-time)	—
completedAt	string,null (date-time)	—
counterpartyHoldStartedAt	string,null (date-time)	—
lastReminderSentAt	string,null (date-time)	—
closeNote	stringnull	—
listingsA	object[]	—
listingsB	object[]	—
reservations	object[]	—
payments	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "fulfillmentMode": "MERCHANT_CHECKOUT",
  "tradeValue": null,
  "currency": "USD",
  "quote": null,
  "checkouts": [
    {
      "side": "A",
      "buyerSide": "A",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName",
      "commissionRate": null,
      "listingIds": [],
      "taxBase": 1,
      "differenceOwed": 1,
      "commissionDue": 1,
      "commissionOffset": 1,
      "commissionShortfall": 1,
      "checkoutFee": 1,
      "processingFeesPassed": false,
      "total": 1,
      "sellerNetCash": 1,
      "shipFromRegion": null,
      "settlement": "TBBN_CHECKOUT",
      "checkoutUrl": null,
      "link": null,
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z"
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z",
  "lockedAt": "2026-07-01T12:00:00Z",
  "completedAt": "2026-07-01T12:00:00Z",
  "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
  "lastReminderSentAt": "2026-07-01T12:00:00Z",
  "closeNote": null,
  "listingsA": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "listingsB": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "reservations": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "PENDING",
      "reservedAt": "2026-07-01T12:00:00Z",
      "releasedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "payments": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "status": "PENDING",
      "merchantCheckoutSessionRef": null,
      "amount": 1,
      "breakdown": null,
      "currency": "USD",
      "completedAt": "2026-07-01T12:00:00Z",
      "failedReason": null,
      "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
      "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
      "settlement": "TBBN_CHECKOUT",
      "externalSettlementDueAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtensionReason": null
    }
  ]
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/close-unreciprocated

Closes 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.

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/close-unreciprocated \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "actingSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "note": "note"
}'

Parameters

path

required

Request body

Field	Type	Required
actingSellerId	string (uuid)	—
note	string	yes

Response (201)

Field	Type	Required
id	string (uuid)	—
offerId	string,null (uuid)	—
sellerAId	string (uuid)	—
sellerBId	string (uuid)	—
status	DRAFT \| PENDING \| OFFERED \| ACCEPTED \| RESERVING \| RESERVED \| WAITING_CHECKOUT_A \| WAITING_CHECKOUT_B \| EXTERNAL_SETTLEMENT \| CHECKOUT_A_COMPLETE \| CHECKOUT_B_COMPLETE \| SCHEDULING_A \| SCHEDULING_B \| EXCHANGE_A_CONFIRMED \| EXCHANGE_B_CONFIRMED \| EXCHANGE_FAILED \| LOCKED \| FULFILLMENT \| FULFILLED \| COMPLETED \| CANCELLED \| CLOSED_UNRECIPROCATED \| EXPIRED \| PAYMENT_FAILED \| RESERVATION_FAILED \| FULFILLMENT_FAILED \| RETURNED \| REFUNDED	—
fulfillmentMode	MERCHANT_CHECKOUT \| PEER_TO_PEER	—
tradeValue	numbernull	—
currency	string	—
quote	object	—
checkouts	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
expiresAt	string,null (date-time)	—
lockedAt	string,null (date-time)	—
completedAt	string,null (date-time)	—
counterpartyHoldStartedAt	string,null (date-time)	—
lastReminderSentAt	string,null (date-time)	—
closeNote	stringnull	—
listingsA	object[]	—
listingsB	object[]	—
reservations	object[]	—
payments	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "fulfillmentMode": "MERCHANT_CHECKOUT",
  "tradeValue": null,
  "currency": "USD",
  "quote": null,
  "checkouts": [
    {
      "side": "A",
      "buyerSide": "A",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName",
      "commissionRate": null,
      "listingIds": [],
      "taxBase": 1,
      "differenceOwed": 1,
      "commissionDue": 1,
      "commissionOffset": 1,
      "commissionShortfall": 1,
      "checkoutFee": 1,
      "processingFeesPassed": false,
      "total": 1,
      "sellerNetCash": 1,
      "shipFromRegion": null,
      "settlement": "TBBN_CHECKOUT",
      "checkoutUrl": null,
      "link": null,
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z"
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z",
  "lockedAt": "2026-07-01T12:00:00Z",
  "completedAt": "2026-07-01T12:00:00Z",
  "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
  "lastReminderSentAt": "2026-07-01T12:00:00Z",
  "closeNote": null,
  "listingsA": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "listingsB": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "reservations": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "PENDING",
      "reservedAt": "2026-07-01T12:00:00Z",
      "releasedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "payments": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "status": "PENDING",
      "merchantCheckoutSessionRef": null,
      "amount": 1,
      "breakdown": null,
      "currency": "USD",
      "completedAt": "2026-07-01T12:00:00Z",
      "failedReason": null,
      "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
      "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
      "settlement": "TBBN_CHECKOUT",
      "externalSettlementDueAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtensionReason": null
    }
  ]
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/excuse-fulfillment

A 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.

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/excuse-fulfillment \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "note"
}'

Parameters

path

required

Request body

Field	Type	Required
note	string	yes

Response (201)

Field	Type	Required
id	string (uuid)	—
offerId	string,null (uuid)	—
sellerAId	string (uuid)	—
sellerBId	string (uuid)	—
status	DRAFT \| PENDING \| OFFERED \| ACCEPTED \| RESERVING \| RESERVED \| WAITING_CHECKOUT_A \| WAITING_CHECKOUT_B \| EXTERNAL_SETTLEMENT \| CHECKOUT_A_COMPLETE \| CHECKOUT_B_COMPLETE \| SCHEDULING_A \| SCHEDULING_B \| EXCHANGE_A_CONFIRMED \| EXCHANGE_B_CONFIRMED \| EXCHANGE_FAILED \| LOCKED \| FULFILLMENT \| FULFILLED \| COMPLETED \| CANCELLED \| CLOSED_UNRECIPROCATED \| EXPIRED \| PAYMENT_FAILED \| RESERVATION_FAILED \| FULFILLMENT_FAILED \| RETURNED \| REFUNDED	—
fulfillmentMode	MERCHANT_CHECKOUT \| PEER_TO_PEER	—
tradeValue	numbernull	—
currency	string	—
quote	object	—
checkouts	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
expiresAt	string,null (date-time)	—
lockedAt	string,null (date-time)	—
completedAt	string,null (date-time)	—
counterpartyHoldStartedAt	string,null (date-time)	—
lastReminderSentAt	string,null (date-time)	—
closeNote	stringnull	—
listingsA	object[]	—
listingsB	object[]	—
reservations	object[]	—
payments	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "fulfillmentMode": "MERCHANT_CHECKOUT",
  "tradeValue": null,
  "currency": "USD",
  "quote": null,
  "checkouts": [
    {
      "side": "A",
      "buyerSide": "A",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName",
      "commissionRate": null,
      "listingIds": [],
      "taxBase": 1,
      "differenceOwed": 1,
      "commissionDue": 1,
      "commissionOffset": 1,
      "commissionShortfall": 1,
      "checkoutFee": 1,
      "processingFeesPassed": false,
      "total": 1,
      "sellerNetCash": 1,
      "shipFromRegion": null,
      "settlement": "TBBN_CHECKOUT",
      "checkoutUrl": null,
      "link": null,
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z"
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z",
  "lockedAt": "2026-07-01T12:00:00Z",
  "completedAt": "2026-07-01T12:00:00Z",
  "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
  "lastReminderSentAt": "2026-07-01T12:00:00Z",
  "closeNote": null,
  "listingsA": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "listingsB": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "reservations": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "PENDING",
      "reservedAt": "2026-07-01T12:00:00Z",
      "releasedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "payments": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "status": "PENDING",
      "merchantCheckoutSessionRef": null,
      "amount": 1,
      "breakdown": null,
      "currency": "USD",
      "completedAt": "2026-07-01T12:00:00Z",
      "failedReason": null,
      "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
      "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
      "settlement": "TBBN_CHECKOUT",
      "externalSettlementDueAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtensionReason": null
    }
  ]
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/external-settlement

Report how a matching-only side settled on your own platform

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/external-settlement \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "side": "A",
  "outcome": "completed",
  "reason": "Customer requested cancellation."
}'

Parameters

path

required

Request body

Field	Type	Required
side	A \| B	yes
outcome	completed \| failed	yes
reason	string	—

Response (201)

Field	Type	Required
id	string (uuid)	—
offerId	string,null (uuid)	—
sellerAId	string (uuid)	—
sellerBId	string (uuid)	—
status	DRAFT \| PENDING \| OFFERED \| ACCEPTED \| RESERVING \| RESERVED \| WAITING_CHECKOUT_A \| WAITING_CHECKOUT_B \| EXTERNAL_SETTLEMENT \| CHECKOUT_A_COMPLETE \| CHECKOUT_B_COMPLETE \| SCHEDULING_A \| SCHEDULING_B \| EXCHANGE_A_CONFIRMED \| EXCHANGE_B_CONFIRMED \| EXCHANGE_FAILED \| LOCKED \| FULFILLMENT \| FULFILLED \| COMPLETED \| CANCELLED \| CLOSED_UNRECIPROCATED \| EXPIRED \| PAYMENT_FAILED \| RESERVATION_FAILED \| FULFILLMENT_FAILED \| RETURNED \| REFUNDED	—
fulfillmentMode	MERCHANT_CHECKOUT \| PEER_TO_PEER	—
tradeValue	numbernull	—
currency	string	—
quote	object	—
checkouts	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
expiresAt	string,null (date-time)	—
lockedAt	string,null (date-time)	—
completedAt	string,null (date-time)	—
counterpartyHoldStartedAt	string,null (date-time)	—
lastReminderSentAt	string,null (date-time)	—
closeNote	stringnull	—
listingsA	object[]	—
listingsB	object[]	—
reservations	object[]	—
payments	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "fulfillmentMode": "MERCHANT_CHECKOUT",
  "tradeValue": null,
  "currency": "USD",
  "quote": null,
  "checkouts": [
    {
      "side": "A",
      "buyerSide": "A",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName",
      "commissionRate": null,
      "listingIds": [],
      "taxBase": 1,
      "differenceOwed": 1,
      "commissionDue": 1,
      "commissionOffset": 1,
      "commissionShortfall": 1,
      "checkoutFee": 1,
      "processingFeesPassed": false,
      "total": 1,
      "sellerNetCash": 1,
      "shipFromRegion": null,
      "settlement": "TBBN_CHECKOUT",
      "checkoutUrl": null,
      "link": null,
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z"
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z",
  "lockedAt": "2026-07-01T12:00:00Z",
  "completedAt": "2026-07-01T12:00:00Z",
  "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
  "lastReminderSentAt": "2026-07-01T12:00:00Z",
  "closeNote": null,
  "listingsA": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "listingsB": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "reservations": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "PENDING",
      "reservedAt": "2026-07-01T12:00:00Z",
      "releasedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "payments": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "status": "PENDING",
      "merchantCheckoutSessionRef": null,
      "amount": 1,
      "breakdown": null,
      "currency": "USD",
      "completedAt": "2026-07-01T12:00:00Z",
      "failedReason": null,
      "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
      "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
      "settlement": "TBBN_CHECKOUT",
      "externalSettlementDueAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtensionReason": null
    }
  ]
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/external-settlement/extend

Extend a matching-only side's report deadline once

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/external-settlement/extend \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "side": "A",
  "days": 1,
  "reason": "Customer requested cancellation."
}'

Parameters

path

required

Request body

Field	Type	Required
side	A \| B	yes
days	integer	yes
reason	string	yes

Response (201)

Field	Type	Required
id	string (uuid)	—
offerId	string,null (uuid)	—
sellerAId	string (uuid)	—
sellerBId	string (uuid)	—
status	DRAFT \| PENDING \| OFFERED \| ACCEPTED \| RESERVING \| RESERVED \| WAITING_CHECKOUT_A \| WAITING_CHECKOUT_B \| EXTERNAL_SETTLEMENT \| CHECKOUT_A_COMPLETE \| CHECKOUT_B_COMPLETE \| SCHEDULING_A \| SCHEDULING_B \| EXCHANGE_A_CONFIRMED \| EXCHANGE_B_CONFIRMED \| EXCHANGE_FAILED \| LOCKED \| FULFILLMENT \| FULFILLED \| COMPLETED \| CANCELLED \| CLOSED_UNRECIPROCATED \| EXPIRED \| PAYMENT_FAILED \| RESERVATION_FAILED \| FULFILLMENT_FAILED \| RETURNED \| REFUNDED	—
fulfillmentMode	MERCHANT_CHECKOUT \| PEER_TO_PEER	—
tradeValue	numbernull	—
currency	string	—
quote	object	—
checkouts	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
expiresAt	string,null (date-time)	—
lockedAt	string,null (date-time)	—
completedAt	string,null (date-time)	—
counterpartyHoldStartedAt	string,null (date-time)	—
lastReminderSentAt	string,null (date-time)	—
closeNote	stringnull	—
listingsA	object[]	—
listingsB	object[]	—
reservations	object[]	—
payments	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "fulfillmentMode": "MERCHANT_CHECKOUT",
  "tradeValue": null,
  "currency": "USD",
  "quote": null,
  "checkouts": [
    {
      "side": "A",
      "buyerSide": "A",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName",
      "commissionRate": null,
      "listingIds": [],
      "taxBase": 1,
      "differenceOwed": 1,
      "commissionDue": 1,
      "commissionOffset": 1,
      "commissionShortfall": 1,
      "checkoutFee": 1,
      "processingFeesPassed": false,
      "total": 1,
      "sellerNetCash": 1,
      "shipFromRegion": null,
      "settlement": "TBBN_CHECKOUT",
      "checkoutUrl": null,
      "link": null,
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z"
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z",
  "lockedAt": "2026-07-01T12:00:00Z",
  "completedAt": "2026-07-01T12:00:00Z",
  "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
  "lastReminderSentAt": "2026-07-01T12:00:00Z",
  "closeNote": null,
  "listingsA": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "listingsB": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "reservations": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "PENDING",
      "reservedAt": "2026-07-01T12:00:00Z",
      "releasedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "payments": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "status": "PENDING",
      "merchantCheckoutSessionRef": null,
      "amount": 1,
      "breakdown": null,
      "currency": "USD",
      "completedAt": "2026-07-01T12:00:00Z",
      "failedReason": null,
      "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
      "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
      "settlement": "TBBN_CHECKOUT",
      "externalSettlementDueAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtensionReason": null
    }
  ]
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/acknowledge-hold-terms

Records 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.

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/acknowledge-hold-terms \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "actingSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Parameters

path

required

Request body

Field	Type	Required
actingSellerId	string (uuid)	—

Response (201)

Field	Type	Required
id	string (uuid)	—
offerId	string,null (uuid)	—
sellerAId	string (uuid)	—
sellerBId	string (uuid)	—
status	DRAFT \| PENDING \| OFFERED \| ACCEPTED \| RESERVING \| RESERVED \| WAITING_CHECKOUT_A \| WAITING_CHECKOUT_B \| EXTERNAL_SETTLEMENT \| CHECKOUT_A_COMPLETE \| CHECKOUT_B_COMPLETE \| SCHEDULING_A \| SCHEDULING_B \| EXCHANGE_A_CONFIRMED \| EXCHANGE_B_CONFIRMED \| EXCHANGE_FAILED \| LOCKED \| FULFILLMENT \| FULFILLED \| COMPLETED \| CANCELLED \| CLOSED_UNRECIPROCATED \| EXPIRED \| PAYMENT_FAILED \| RESERVATION_FAILED \| FULFILLMENT_FAILED \| RETURNED \| REFUNDED	—
fulfillmentMode	MERCHANT_CHECKOUT \| PEER_TO_PEER	—
tradeValue	numbernull	—
currency	string	—
quote	object	—
checkouts	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
expiresAt	string,null (date-time)	—
lockedAt	string,null (date-time)	—
completedAt	string,null (date-time)	—
counterpartyHoldStartedAt	string,null (date-time)	—
lastReminderSentAt	string,null (date-time)	—
closeNote	stringnull	—
listingsA	object[]	—
listingsB	object[]	—
reservations	object[]	—
payments	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "fulfillmentMode": "MERCHANT_CHECKOUT",
  "tradeValue": null,
  "currency": "USD",
  "quote": null,
  "checkouts": [
    {
      "side": "A",
      "buyerSide": "A",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName",
      "commissionRate": null,
      "listingIds": [],
      "taxBase": 1,
      "differenceOwed": 1,
      "commissionDue": 1,
      "commissionOffset": 1,
      "commissionShortfall": 1,
      "checkoutFee": 1,
      "processingFeesPassed": false,
      "total": 1,
      "sellerNetCash": 1,
      "shipFromRegion": null,
      "settlement": "TBBN_CHECKOUT",
      "checkoutUrl": null,
      "link": null,
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z"
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z",
  "lockedAt": "2026-07-01T12:00:00Z",
  "completedAt": "2026-07-01T12:00:00Z",
  "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
  "lastReminderSentAt": "2026-07-01T12:00:00Z",
  "closeNote": null,
  "listingsA": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "listingsB": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "reservations": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "PENDING",
      "reservedAt": "2026-07-01T12:00:00Z",
      "releasedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "payments": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "status": "PENDING",
      "merchantCheckoutSessionRef": null,
      "amount": 1,
      "breakdown": null,
      "currency": "USD",
      "completedAt": "2026-07-01T12:00:00Z",
      "failedReason": null,
      "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
      "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
      "settlement": "TBBN_CHECKOUT",
      "externalSettlementDueAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtensionReason": null
    }
  ]
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/scheduling/confirm

Peer-to-peer trade completion — either party confirms the exchange happened on their side. Once both sides have confirmed, the session moves to COMPLETED.

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/scheduling/confirm \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "actingSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "confirmedByMerchantUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Parameters

path

required

Request body

Field	Type	Required
actingSellerId	string (uuid)	yes
confirmedByMerchantUserId	string (uuid)	—

Response (200)

Field	Type	Required
id	string (uuid)	—
offerId	string,null (uuid)	—
sellerAId	string (uuid)	—
sellerBId	string (uuid)	—
status	DRAFT \| PENDING \| OFFERED \| ACCEPTED \| RESERVING \| RESERVED \| WAITING_CHECKOUT_A \| WAITING_CHECKOUT_B \| EXTERNAL_SETTLEMENT \| CHECKOUT_A_COMPLETE \| CHECKOUT_B_COMPLETE \| SCHEDULING_A \| SCHEDULING_B \| EXCHANGE_A_CONFIRMED \| EXCHANGE_B_CONFIRMED \| EXCHANGE_FAILED \| LOCKED \| FULFILLMENT \| FULFILLED \| COMPLETED \| CANCELLED \| CLOSED_UNRECIPROCATED \| EXPIRED \| PAYMENT_FAILED \| RESERVATION_FAILED \| FULFILLMENT_FAILED \| RETURNED \| REFUNDED	—
fulfillmentMode	MERCHANT_CHECKOUT \| PEER_TO_PEER	—
tradeValue	numbernull	—
currency	string	—
quote	object	—
checkouts	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
expiresAt	string,null (date-time)	—
lockedAt	string,null (date-time)	—
completedAt	string,null (date-time)	—
counterpartyHoldStartedAt	string,null (date-time)	—
lastReminderSentAt	string,null (date-time)	—
closeNote	stringnull	—
listingsA	object[]	—
listingsB	object[]	—
reservations	object[]	—
payments	object[]	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "fulfillmentMode": "MERCHANT_CHECKOUT",
  "tradeValue": null,
  "currency": "USD",
  "quote": null,
  "checkouts": [
    {
      "side": "A",
      "buyerSide": "A",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName",
      "commissionRate": null,
      "listingIds": [],
      "taxBase": 1,
      "differenceOwed": 1,
      "commissionDue": 1,
      "commissionOffset": 1,
      "commissionShortfall": 1,
      "checkoutFee": 1,
      "processingFeesPassed": false,
      "total": 1,
      "sellerNetCash": 1,
      "shipFromRegion": null,
      "settlement": "TBBN_CHECKOUT",
      "checkoutUrl": null,
      "link": null,
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z"
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z",
  "lockedAt": "2026-07-01T12:00:00Z",
  "completedAt": "2026-07-01T12:00:00Z",
  "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
  "lastReminderSentAt": "2026-07-01T12:00:00Z",
  "closeNote": null,
  "listingsA": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "listingsB": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "reservations": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "PENDING",
      "reservedAt": "2026-07-01T12:00:00Z",
      "releasedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "payments": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "status": "PENDING",
      "merchantCheckoutSessionRef": null,
      "amount": 1,
      "breakdown": null,
      "currency": "USD",
      "completedAt": "2026-07-01T12:00:00Z",
      "failedReason": null,
      "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
      "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
      "settlement": "TBBN_CHECKOUT",
      "externalSettlementDueAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtensionReason": null
    }
  ]
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/scheduling/fail

Either party reports the peer-to-peer exchange failed (no-show, item mismatch)

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/scheduling/fail \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "actingSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "reason": "Customer requested cancellation."
}'

Parameters

path

required

Request body

Field	Type	Required
actingSellerId	string (uuid)	yes
reason	string	—

Response (200)

Field	Type	Required
id	string (uuid)	—
offerId	string,null (uuid)	—
sellerAId	string (uuid)	—
sellerBId	string (uuid)	—
status	DRAFT \| PENDING \| OFFERED \| ACCEPTED \| RESERVING \| RESERVED \| WAITING_CHECKOUT_A \| WAITING_CHECKOUT_B \| EXTERNAL_SETTLEMENT \| CHECKOUT_A_COMPLETE \| CHECKOUT_B_COMPLETE \| SCHEDULING_A \| SCHEDULING_B \| EXCHANGE_A_CONFIRMED \| EXCHANGE_B_CONFIRMED \| EXCHANGE_FAILED \| LOCKED \| FULFILLMENT \| FULFILLED \| COMPLETED \| CANCELLED \| CLOSED_UNRECIPROCATED \| EXPIRED \| PAYMENT_FAILED \| RESERVATION_FAILED \| FULFILLMENT_FAILED \| RETURNED \| REFUNDED	—
fulfillmentMode	MERCHANT_CHECKOUT \| PEER_TO_PEER	—
tradeValue	numbernull	—
currency	string	—
quote	object	—
checkouts	object[]	—
createdAt	string (date-time)	—
updatedAt	string (date-time)	—
expiresAt	string,null (date-time)	—
lockedAt	string,null (date-time)	—
completedAt	string,null (date-time)	—
counterpartyHoldStartedAt	string,null (date-time)	—
lastReminderSentAt	string,null (date-time)	—
closeNote	stringnull	—
listingsA	object[]	—
listingsB	object[]	—
reservations	object[]	—
payments	object[]	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "offerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerAId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerBId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "fulfillmentMode": "MERCHANT_CHECKOUT",
  "tradeValue": null,
  "currency": "USD",
  "quote": null,
  "checkouts": [
    {
      "side": "A",
      "buyerSide": "A",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName",
      "commissionRate": null,
      "listingIds": [],
      "taxBase": 1,
      "differenceOwed": 1,
      "commissionDue": 1,
      "commissionOffset": 1,
      "commissionShortfall": 1,
      "checkoutFee": 1,
      "processingFeesPassed": false,
      "total": 1,
      "sellerNetCash": 1,
      "shipFromRegion": null,
      "settlement": "TBBN_CHECKOUT",
      "checkoutUrl": null,
      "link": null,
      "paymentStatus": null,
      "paidAt": "2026-07-01T12:00:00Z"
    }
  ],
  "createdAt": "2026-07-01T12:00:00Z",
  "updatedAt": "2026-07-01T12:00:00Z",
  "expiresAt": "2026-07-01T12:00:00Z",
  "lockedAt": "2026-07-01T12:00:00Z",
  "completedAt": "2026-07-01T12:00:00Z",
  "counterpartyHoldStartedAt": "2026-07-01T12:00:00Z",
  "lastReminderSentAt": "2026-07-01T12:00:00Z",
  "closeNote": null,
  "listingsA": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "listingsB": [
    {
      "listing": {
        "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "merchantListingRef": null,
        "sellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "title": "title",
        "category": "category",
        "subcategory": null,
        "brand": null,
        "model": null,
        "size": null,
        "condition": null,
        "year": null,
        "originalPrice": 1,
        "currency": "USD",
        "visibility": "PRIVATE",
        "status": "ACTIVE",
        "listingType": "SALE",
        "deliveryMethod": "LOCAL_PICKUP",
        "preferredSpaceBranchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "city": null,
        "region": null,
        "locationLabel": null,
        "locationCountry": null,
        "sellerIdentityVerified": false,
        "publicNow": false,
        "notPublicReason": "PENDING_REVIEW",
        "kind": "GOODS",
        "details": null,
        "preferredSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "sellerStoreSlug": null,
        "viewerIsOwner": false,
        "merchantItemUrl": null,
        "requestedAmount": null,
        "willingToPay": null,
        "note": null,
        "createdAt": "2026-07-01T12:00:00Z",
        "updatedAt": "2026-07-01T12:00:00Z",
        "syncedAt": "2026-07-01T12:00:00Z",
        "deletedAt": "2026-07-01T12:00:00Z"
      }
    }
  ],
  "reservations": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "listingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "status": "PENDING",
      "reservedAt": "2026-07-01T12:00:00Z",
      "releasedAt": "2026-07-01T12:00:00Z"
    }
  ],
  "payments": [
    {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "side": "A",
      "status": "PENDING",
      "merchantCheckoutSessionRef": null,
      "amount": 1,
      "breakdown": null,
      "currency": "USD",
      "completedAt": "2026-07-01T12:00:00Z",
      "failedReason": null,
      "fulfillmentStartedAt": "2026-07-01T12:00:00Z",
      "fulfillmentCompletedAt": "2026-07-01T12:00:00Z",
      "settlement": "TBBN_CHECKOUT",
      "externalSettlementDueAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtendedAt": "2026-07-01T12:00:00Z",
      "externalSettlementExtensionReason": null
    }
  ]
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/space-proposals

Propose a Space to meet at for a peer-to-peer trade

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/space-proposals \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "spaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "branchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "scheduledAt": "2026-07-01T12:00:00Z",
  "acceptTerms": false,
  "actingSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Parameters

path

required

Request body

Field	Type	Required
spaceId	string (uuid)	—
branchId	string (uuid)	—
scheduledAt	string (date-time)	—
acceptTerms	boolean	—
actingSellerId	string (uuid)	—

Response (201)

Field	Type	Required
id	string (uuid)	—
tradeSessionId	string (uuid)	—
branchId	string (uuid)	—
spaceId	string,null (uuid)	—
proposedBySellerId	string (uuid)	—
scheduledAt	string,null (date-time)	—
payerTermsAcceptedAt	string,null (date-time)	—
bookingId	string,null (uuid)	—
status	PROPOSED \| ACCEPTED \| REJECTED \| SUPERSEDED	—
proposedAt	string (date-time)	—
respondedAt	string,null (date-time)	—
space	objectnull	—
branch	object	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "branchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "spaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "proposedBySellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "scheduledAt": "2026-07-01T12:00:00Z",
  "payerTermsAcceptedAt": "2026-07-01T12:00:00Z",
  "bookingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "PROPOSED",
  "proposedAt": "2026-07-01T12:00:00Z",
  "respondedAt": "2026-07-01T12:00:00Z",
  "space": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Co.",
    "isFree": false
  },
  "branch": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Co.",
    "addressLine1": "addressLine1",
    "city": "city",
    "country": "US"
  }
}

Possible errors

Example error response

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

get/v1/trade-sessions/{id}/space-proposals

List a trade's meeting-place proposals, newest first

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

Parameters

path

required

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "branchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "spaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "proposedBySellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "scheduledAt": "2026-07-01T12:00:00Z",
    "payerTermsAcceptedAt": "2026-07-01T12:00:00Z",
    "bookingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "PROPOSED",
    "proposedAt": "2026-07-01T12:00:00Z",
    "respondedAt": "2026-07-01T12:00:00Z",
    "space": {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Acme Co.",
      "isFree": false
    },
    "branch": {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Acme Co.",
      "addressLine1": "addressLine1",
      "city": "city",
      "country": "US"
    }
  }
]

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/space-proposals/{proposalId}/decline

Decline the other trader's meeting-place proposal

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/space-proposals/{proposalId}/decline \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "actingSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Parameters

id	path	required
proposalId	path	required

Request body

Field	Type	Required
actingSellerId	string (uuid)	—

Response (201)

Field	Type	Required
id	string (uuid)	—
tradeSessionId	string (uuid)	—
branchId	string (uuid)	—
spaceId	string,null (uuid)	—
proposedBySellerId	string (uuid)	—
scheduledAt	string,null (date-time)	—
payerTermsAcceptedAt	string,null (date-time)	—
bookingId	string,null (uuid)	—
status	PROPOSED \| ACCEPTED \| REJECTED \| SUPERSEDED	—
proposedAt	string (date-time)	—
respondedAt	string,null (date-time)	—
space	objectnull	—
branch	object	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "branchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "spaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "proposedBySellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "scheduledAt": "2026-07-01T12:00:00Z",
  "payerTermsAcceptedAt": "2026-07-01T12:00:00Z",
  "bookingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "PROPOSED",
  "proposedAt": "2026-07-01T12:00:00Z",
  "respondedAt": "2026-07-01T12:00:00Z",
  "space": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Co.",
    "isFree": false
  },
  "branch": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Acme Co.",
    "addressLine1": "addressLine1",
    "city": "city",
    "country": "US"
  }
}

Possible errors

Example error response

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

post/v1/trade-sessions/{id}/space-proposals/{proposalId}/accept

Accept the other trader's meeting-place proposal

curl -X POST https://api.tbbnetwork.com/v1/trade-sessions/{id}/space-proposals/{proposalId}/accept \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "actingSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}'

Parameters

id	path	required
proposalId	path	required

Request body

Field	Type	Required
actingSellerId	string (uuid)	—

Response (201)

Field	Type	Required
proposal	TradeSpaceProposal	—
booking	objectnull	—

Example 201 response

{
  "proposal": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "tradeSessionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "branchId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "spaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "proposedBySellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "scheduledAt": "2026-07-01T12:00:00Z",
    "payerTermsAcceptedAt": "2026-07-01T12:00:00Z",
    "bookingId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "PROPOSED",
    "proposedAt": "2026-07-01T12:00:00Z",
    "respondedAt": "2026-07-01T12:00:00Z",
    "space": {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Acme Co.",
      "isFree": false
    },
    "branch": {
      "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Acme Co.",
      "addressLine1": "addressLine1",
      "city": "city",
      "country": "US"
    }
  },
  "booking": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "status",
    "scheduledAt": "2026-07-01T12:00:00Z",
    "chargeAmount": null,
    "currency": null
  }
}

Possible errors

Example error response

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