Trade-ins and trade credit

Take items in at your counter and give credit that your till spends as a payment type on its own order. Your checkout, tax and fulfilment stay yours. TBBN keeps the record, handles no money and takes no cut.

These calls use your Merchant API key.

1. Say which location stock is at

A listing takes branchId, or locationRef with the store number you gave the location, and your sku. A catalog feed uses the location_id column. The location must belong to a Business your Merchant is linked to, or the call answers 400 LOCATION_NOT_FOUND.

2. Take an item in

curl -X POST https://api.tbbnetwork.com/v1/trade_ins \
  -H "Authorization: Bearer $TBBN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "locationRef": "store-7", "sku": "TI-1042", "title": "Used bike", "category": "Sports", "condition": "GOOD", "originalPrice": 120, "currency": "USD", "visibility": "GLOBAL", "listingType": "SALE" }'

The item becomes your listing at that location, under the same rules as any store listing. It stays off the Marketplace until you send "publish": true or make it available. A tradein.accepted webhook carries the listing, location and sku, so it can reach your inventory system.

3. Give credit

curl -X POST https://api.tbbnetwork.com/v1/trade_credits \
  -H "Authorization: Bearer $TBBN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 40, "currency": "USD", "locationRef": "store-7", "listingId": "...", "customerRef": "your-customer-id" }'

Name a location to limit the credit to it. expiresAt is optional.

4. Spend it on your till

Apply it as a payment type on your own order, then tell TBBN:

curl -X POST https://api.tbbnetwork.com/v1/trade_credits/$ID/redeem \
  -H "Authorization: Bearer $TBBN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "posOrderId": "your-order-id" }'

Telling TBBN twice about the same order is safe. Otherwise it answers 409 with one of these:

Code	Meaning
TRADE_CREDIT_ALREADY_SPENT	Spent on another order.
TRADE_CREDIT_EXPIRED	Past its expiresAt.
TRADE_CREDIT_VOIDED	Cancelled.
TRADE_CREDIT_OTHER_LOCATION	Limited to another location.

POST /v1/trade_credits/{id}/void cancels unspent credit. Webhooks: trade_credit.issued, trade_credit.redeemed, trade_credit.voided.