Available

Offers

post/v1/offers

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

curl -X POST https://api.tbbnetwork.com/v1/offers \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "fromSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "toSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "listingIdsA": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "listingIdsB": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "extraAmountOffered": 1,
  "cashIncluded": 1,
  "expiresAt": "2026-07-01T12:00:00Z",
  "quoteFingerprint": "quoteFingerprint",
  "meetupSpaceId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "meetupFromListing": false
}'

Parameters

Request body

Field	Type	Required
fromSellerId	string (uuid)	yes
toSellerId	string (uuid)	yes
listingIdsA	string[]	yes
listingIdsB	string[]	yes
extraAmountOffered	number	—
cashIncluded	number	—
expiresAt	string (date-time)	—
quoteFingerprint	string	yes
meetupSpaceId	string (uuid)	—
meetupFromListing	boolean	—

Response (201)

Field	Type	Required
id	string (uuid)	—
fromSellerId	string (uuid)	—
toSellerId	string (uuid)	—
status	DRAFT \| PENDING \| ACCEPTED \| REJECTED \| CANCELLED \| EXPIRED \| COUNTERED	—
extraAmountOffered	numbernull	—
cashIncluded	numbernull	—
expiresAt	string,null (date-time)	—
createdAt	string (date-time)	—
quoteFingerprint	stringnull	—
quoteAcknowledgedFromAt	string,null (date-time)	—
quoteAcknowledgedToAt	string,null (date-time)	—
quote	object	—
quoteLockedAt	string,null (date-time)	—
offerListingsA	object[]	—
offerListingsB	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "fromSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "toSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "extraAmountOffered": null,
  "cashIncluded": null,
  "expiresAt": "2026-07-01T12:00:00Z",
  "createdAt": "2026-07-01T12:00:00Z",
  "quoteFingerprint": null,
  "quoteAcknowledgedFromAt": "2026-07-01T12:00:00Z",
  "quoteAcknowledgedToAt": "2026-07-01T12:00:00Z",
  "quote": null,
  "quoteLockedAt": "2026-07-01T12:00:00Z",
  "offerListingsA": [
    {
      "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"
      }
    }
  ],
  "offerListingsB": [
    {
      "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"
      }
    }
  ]
}

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/offers

List offers for a seller

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

Parameters

sellerId	query	required
direction	query	optional

Response (200)

Example 200 response

[
  {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "fromSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "toSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "status": "DRAFT",
    "extraAmountOffered": null,
    "cashIncluded": null,
    "expiresAt": "2026-07-01T12:00:00Z",
    "createdAt": "2026-07-01T12:00:00Z",
    "quoteFingerprint": null,
    "quoteAcknowledgedFromAt": "2026-07-01T12:00:00Z",
    "quoteAcknowledgedToAt": "2026-07-01T12:00:00Z",
    "quote": null,
    "quoteLockedAt": "2026-07-01T12:00:00Z",
    "offerListingsA": [
      {}
    ],
    "offerListingsB": [
      {}
    ]
  }
]

post/v1/offers/quote

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

curl -X POST https://api.tbbnetwork.com/v1/offers/quote \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "listingIdsA": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "listingIdsB": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "extraAmountOffered": 1,
  "cashIncluded": 1
}'

Request body

Field	Type	Required
listingIdsA	string[]	yes
listingIdsB	string[]	yes
extraAmountOffered	number	—
cashIncluded	number	—

Response (201)

Field	Type	Required
quote	TradeQuote	—
problems	object[]	—
tradeable	boolean	—
coverage	object	—
maxCashIncluded	number	—

Example 201 response

{
  "quote": {
    "version": 1,
    "currency": "USD",
    "sides": {
      "A": {
        "listedPrice": 1,
        "tradeValue": 1
      },
      "B": {
        "listedPrice": 1,
        "tradeValue": 1
      }
    },
    "extraCashFromB": 1,
    "difference": 1,
    "payer": "A",
    "payee": "A",
    "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
      }
    ],
    "directPayment": {
      "fromSide": "A",
      "toSide": "A",
      "amount": 1
    },
    "fingerprint": "fingerprint"
  },
  "problems": [
    {
      "code": "COMMISSION_RATE_MISSING",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName"
    }
  ],
  "tradeable": false,
  "coverage": {
    "required": 1,
    "offered": 1,
    "shortfall": 1,
    "enough": false
  },
  "maxCashIncluded": 1
}

Possible errors

Example error response

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

get/v1/offers/{id}/quote

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

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

Parameters

path

required

Response (200)

Field	Type	Required
quote	TradeQuote	—
problems	object[]	—
locked	boolean	—
acknowledged	object	—

Example 200 response

{
  "quote": {
    "version": 1,
    "currency": "USD",
    "sides": {
      "A": {
        "listedPrice": 1,
        "tradeValue": 1
      },
      "B": {
        "listedPrice": 1,
        "tradeValue": 1
      }
    },
    "extraCashFromB": 1,
    "difference": 1,
    "payer": "A",
    "payee": "A",
    "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
      }
    ],
    "directPayment": {
      "fromSide": "A",
      "toSide": "A",
      "amount": 1
    },
    "fingerprint": "fingerprint"
  },
  "problems": [
    {
      "code": "COMMISSION_RATE_MISSING",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName"
    }
  ],
  "locked": false,
  "acknowledged": {
    "sender": false,
    "recipient": false
  }
}

Possible errors

Example error response

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

post/v1/offers/{id}/quote/acknowledge

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

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

Parameters

path

required

Request body

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

Response (201)

Field	Type	Required
quote	TradeQuote	—
problems	object[]	—
locked	boolean	—
acknowledged	object	—

Example 201 response

{
  "quote": {
    "version": 1,
    "currency": "USD",
    "sides": {
      "A": {
        "listedPrice": 1,
        "tradeValue": 1
      },
      "B": {
        "listedPrice": 1,
        "tradeValue": 1
      }
    },
    "extraCashFromB": 1,
    "difference": 1,
    "payer": "A",
    "payee": "A",
    "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
      }
    ],
    "directPayment": {
      "fromSide": "A",
      "toSide": "A",
      "amount": 1
    },
    "fingerprint": "fingerprint"
  },
  "problems": [
    {
      "code": "COMMISSION_RATE_MISSING",
      "merchantId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "merchantName": "merchantName"
    }
  ],
  "locked": false,
  "acknowledged": {
    "sender": false,
    "recipient": false
  }
}

Possible errors

Example error response

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

get/v1/offers/{id}

Get an offer. A PENDING offer past its expiresAt is lazily transitioned to EXPIRED on read.

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

Parameters

path

required

Response (200)

Field	Type	Required
id	string (uuid)	—
fromSellerId	string (uuid)	—
toSellerId	string (uuid)	—
status	DRAFT \| PENDING \| ACCEPTED \| REJECTED \| CANCELLED \| EXPIRED \| COUNTERED	—
extraAmountOffered	numbernull	—
cashIncluded	numbernull	—
expiresAt	string,null (date-time)	—
createdAt	string (date-time)	—
quoteFingerprint	stringnull	—
quoteAcknowledgedFromAt	string,null (date-time)	—
quoteAcknowledgedToAt	string,null (date-time)	—
quote	object	—
quoteLockedAt	string,null (date-time)	—
offerListingsA	object[]	—
offerListingsB	object[]	—

Example 200 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "fromSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "toSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "extraAmountOffered": null,
  "cashIncluded": null,
  "expiresAt": "2026-07-01T12:00:00Z",
  "createdAt": "2026-07-01T12:00:00Z",
  "quoteFingerprint": null,
  "quoteAcknowledgedFromAt": "2026-07-01T12:00:00Z",
  "quoteAcknowledgedToAt": "2026-07-01T12:00:00Z",
  "quote": null,
  "quoteLockedAt": "2026-07-01T12:00:00Z",
  "offerListingsA": [
    {
      "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"
      }
    }
  ],
  "offerListingsB": [
    {
      "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"
      }
    }
  ]
}

Possible errors

Example error response

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

post/v1/offers/{id}/accept

Accept 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).

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

Parameters

path

required

Request body

Field	Type	Required
actingSellerId	string (uuid)	yes
quoteFingerprint	string	yes

Response (201)

Field	Type	Required
id	string (uuid)	—
fromSellerId	string (uuid)	—
toSellerId	string (uuid)	—
status	DRAFT \| PENDING \| ACCEPTED \| REJECTED \| CANCELLED \| EXPIRED \| COUNTERED	—
extraAmountOffered	numbernull	—
cashIncluded	numbernull	—
expiresAt	string,null (date-time)	—
createdAt	string (date-time)	—
quoteFingerprint	stringnull	—
quoteAcknowledgedFromAt	string,null (date-time)	—
quoteAcknowledgedToAt	string,null (date-time)	—
quote	object	—
quoteLockedAt	string,null (date-time)	—
offerListingsA	object[]	—
offerListingsB	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "fromSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "toSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "extraAmountOffered": null,
  "cashIncluded": null,
  "expiresAt": "2026-07-01T12:00:00Z",
  "createdAt": "2026-07-01T12:00:00Z",
  "quoteFingerprint": null,
  "quoteAcknowledgedFromAt": "2026-07-01T12:00:00Z",
  "quoteAcknowledgedToAt": "2026-07-01T12:00:00Z",
  "quote": null,
  "quoteLockedAt": "2026-07-01T12:00:00Z",
  "offerListingsA": [
    {
      "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"
      }
    }
  ],
  "offerListingsB": [
    {
      "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"
      }
    }
  ]
}

Possible errors

Example error response

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

post/v1/offers/{id}/reject

Reject a PENDING offer — only the recipient (toSellerId) may reject

curl -X POST https://api.tbbnetwork.com/v1/offers/{id}/reject \
  -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)	yes

Response (201)

Field	Type	Required
id	string (uuid)	—
fromSellerId	string (uuid)	—
toSellerId	string (uuid)	—
status	DRAFT \| PENDING \| ACCEPTED \| REJECTED \| CANCELLED \| EXPIRED \| COUNTERED	—
extraAmountOffered	numbernull	—
cashIncluded	numbernull	—
expiresAt	string,null (date-time)	—
createdAt	string (date-time)	—
quoteFingerprint	stringnull	—
quoteAcknowledgedFromAt	string,null (date-time)	—
quoteAcknowledgedToAt	string,null (date-time)	—
quote	object	—
quoteLockedAt	string,null (date-time)	—
offerListingsA	object[]	—
offerListingsB	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "fromSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "toSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "extraAmountOffered": null,
  "cashIncluded": null,
  "expiresAt": "2026-07-01T12:00:00Z",
  "createdAt": "2026-07-01T12:00:00Z",
  "quoteFingerprint": null,
  "quoteAcknowledgedFromAt": "2026-07-01T12:00:00Z",
  "quoteAcknowledgedToAt": "2026-07-01T12:00:00Z",
  "quote": null,
  "quoteLockedAt": "2026-07-01T12:00:00Z",
  "offerListingsA": [
    {
      "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"
      }
    }
  ],
  "offerListingsB": [
    {
      "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"
      }
    }
  ]
}

Possible errors

Example error response

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

post/v1/offers/{id}/cancel

Cancel a DRAFT or PENDING offer — only the sender (fromSellerId) may cancel

curl -X POST https://api.tbbnetwork.com/v1/offers/{id}/cancel \
  -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)	yes

Response (201)

Field	Type	Required
id	string (uuid)	—
fromSellerId	string (uuid)	—
toSellerId	string (uuid)	—
status	DRAFT \| PENDING \| ACCEPTED \| REJECTED \| CANCELLED \| EXPIRED \| COUNTERED	—
extraAmountOffered	numbernull	—
cashIncluded	numbernull	—
expiresAt	string,null (date-time)	—
createdAt	string (date-time)	—
quoteFingerprint	stringnull	—
quoteAcknowledgedFromAt	string,null (date-time)	—
quoteAcknowledgedToAt	string,null (date-time)	—
quote	object	—
quoteLockedAt	string,null (date-time)	—
offerListingsA	object[]	—
offerListingsB	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "fromSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "toSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "extraAmountOffered": null,
  "cashIncluded": null,
  "expiresAt": "2026-07-01T12:00:00Z",
  "createdAt": "2026-07-01T12:00:00Z",
  "quoteFingerprint": null,
  "quoteAcknowledgedFromAt": "2026-07-01T12:00:00Z",
  "quoteAcknowledgedToAt": "2026-07-01T12:00:00Z",
  "quote": null,
  "quoteLockedAt": "2026-07-01T12:00:00Z",
  "offerListingsA": [
    {
      "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"
      }
    }
  ],
  "offerListingsB": [
    {
      "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"
      }
    }
  ]
}

Possible errors

Example error response

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

post/v1/offers/{id}/counter

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

curl -X POST https://api.tbbnetwork.com/v1/offers/{id}/counter \
  -H "Authorization: Bearer sk_sandbox_..." \
  -H "Idempotency-Key: 5f2f...b91" \
  -H "Content-Type: application/json" \
  -d '{
  "actingSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "listingIdsA": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "listingIdsB": [
    "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  ],
  "extraAmountOffered": 1,
  "cashIncluded": 1,
  "expiresAt": "2026-07-01T12:00:00Z",
  "quoteFingerprint": "quoteFingerprint"
}'

Parameters

path

required

Request body

Field	Type	Required
actingSellerId	string (uuid)	yes
listingIdsA	string[]	yes
listingIdsB	string[]	yes
extraAmountOffered	number	—
cashIncluded	number	—
expiresAt	string (date-time)	—
quoteFingerprint	string	yes

Response (201)

Field	Type	Required
id	string (uuid)	—
fromSellerId	string (uuid)	—
toSellerId	string (uuid)	—
status	DRAFT \| PENDING \| ACCEPTED \| REJECTED \| CANCELLED \| EXPIRED \| COUNTERED	—
extraAmountOffered	numbernull	—
cashIncluded	numbernull	—
expiresAt	string,null (date-time)	—
createdAt	string (date-time)	—
quoteFingerprint	stringnull	—
quoteAcknowledgedFromAt	string,null (date-time)	—
quoteAcknowledgedToAt	string,null (date-time)	—
quote	object	—
quoteLockedAt	string,null (date-time)	—
offerListingsA	object[]	—
offerListingsB	object[]	—

Example 201 response

{
  "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "fromSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "toSellerId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "DRAFT",
  "extraAmountOffered": null,
  "cashIncluded": null,
  "expiresAt": "2026-07-01T12:00:00Z",
  "createdAt": "2026-07-01T12:00:00Z",
  "quoteFingerprint": null,
  "quoteAcknowledgedFromAt": "2026-07-01T12:00:00Z",
  "quoteAcknowledgedToAt": "2026-07-01T12:00:00Z",
  "quote": null,
  "quoteLockedAt": "2026-07-01T12:00:00Z",
  "offerListingsA": [
    {
      "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"
      }
    }
  ],
  "offerListingsB": [
    {
      "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"
      }
    }
  ]
}

Possible errors

Example error response

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