BTB API

Track inventory, listings and sales across every platform you sell on. JSON over HTTPS, authenticated with an API key.

https://btb.net/api/v1 openapi.json Get an API key

Quickstart

Create a key under Settings → API keys, export it, and you're three calls from tracking a sale.

export BTB_KEY=btb_...

1 Add an item

curl https://btb.net/api/v1/items \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Levi's 501 jeans","sku":"LEV-501","cost":"6.00"}'

2 List it on a couple of platforms

curl https://btb.net/api/v1/items/1/listings \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price":"38.00","platform":"ebay"}'

3 Record the sale

curl https://btb.net/api/v1/items/1/sell \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"ebay","platform_fees":"5.12","sale_price":"38.00"}'

If that was the last unit, the response's needs_delist lists every other listing to take down, so it can't sell twice.

Conventions

Auth
Authorization: Bearer btb_.... Read-only keys can call GET endpoints only (writes return 403).
Values
Money is a decimal string ("45.00"), times are ISO 8601 UTC, platforms are slugs like ebay.
Errors
Always {"error": {"code", "message", "details"}}. Field errors come back as 422 with per-field messages in details.
Pagination
Lists return next_cursor; pass it back as ?cursor=. It's null on the last page.
Retries
Send an Idempotency-Key header on writes. A retry with the same key replays the first response for 24 hours instead of running again.
Rate limits
120 requests/minute per key. See x-ratelimit-remaining; a 429 includes retry-after.

MCP server

The same actions are available as MCP tools for Claude and other AI assistants, using the same API key.

claude mcp add --transport http btb https://btb.net/mcp \
  --header "Authorization: Bearer $BTB_KEY"

Account

get /me

Who am I

Returns the user and API key making the request. Use it to check a key works.

curl https://btb.net/api/v1/me \
  -H "Authorization: Bearer $BTB_KEY"

Platforms

get /platforms

List platforms

Marketplaces items can be listed and sold on. Use the slug wherever a platform is expected.

curl https://btb.net/api/v1/platforms \
  -H "Authorization: Bearer $BTB_KEY"

Items

get /items

List items

Newest first, with each item's listings.

Query Type Description
status draft | active | sold | archived Only items with this status.
q string Case-insensitive match on title, SKU or brand.
limit integer Page size.
cursor string next_cursor from the previous page.
curl https://btb.net/api/v1/items \
  -H "Authorization: Bearer $BTB_KEY"
post /items write

Create an item

The item is the universal listing template: title, description, price, photos, condition, size and shipping details live here once and every platform listing uses them. New items start as draft and become active once listed.

curl https://btb.net/api/v1/items \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size":"M","title":"Patagonia Better Sweater","tags":["patagonia","fleece"],"condition":"like_new","department":"men","brand":"Patagonia","original_price":"139.00","price":"55.00","weight_oz":"18","sku":"PAT-001","cost":"8.00"}'
get /items/{id}

Get an item

curl https://btb.net/api/v1/items/1 \
  -H "Authorization: Bearer $BTB_KEY"
patch /items/{id} write

Update an item

Changes details only. Quantity changes go through /adjust or /sell so they're logged.

curl https://btb.net/api/v1/items/1 \
  -X PATCH \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size":"M","title":"Patagonia Better Sweater (M)"}'
delete /items/{id} write

Delete an item

Deletes the item with its listings, sales and stock history. Prefer archiving.

curl https://btb.net/api/v1/items/1 \
  -X DELETE \
  -H "Authorization: Bearer $BTB_KEY"
post /items/{id}/adjust write

Adjust stock

Add or remove units outside a sale. Fails with insufficient_stock below zero.

curl https://btb.net/api/v1/items/1/adjust \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"return","change":1,"note":"Buyer returned it"}'
get /items/{id}/stock-movements

Stock history

Every quantity change for the item, newest first.

curl https://btb.net/api/v1/items/1/stock-movements \
  -H "Authorization: Bearer $BTB_KEY"

Listings

post /items/{id}/listings write

List an item on a platform

Listings use the item as their template (title, description, photos, price), so usually you only say where: platform , plus url / external_id once it's live. An item can have one live listing per platform.

curl https://btb.net/api/v1/items/1/listings \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.ebay.com/itm/123","platform":"ebay","external_id":"123"}'
get /listings

List listings

Use status=needs_delist for the delist queue.

Query Type Description
status active | needs_delist | delisted | sold Only listings with this status.
platform string Only listings on this platform.
item_id integer Only listings of this item.
external_id string Only listings with this platform listing id.
limit integer Page size.
cursor string next_cursor from the previous page.
curl https://btb.net/api/v1/listings \
  -H "Authorization: Bearer $BTB_KEY"
get /listings/{id}

Get a listing

curl https://btb.net/api/v1/listings/1 \
  -H "Authorization: Bearer $BTB_KEY"
patch /listings/{id} write

Update a listing

curl https://btb.net/api/v1/listings/1 \
  -X PATCH \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"price":"49.99"}'
post /listings/{id}/delist write

Mark as delisted

Confirms the listing was taken down on its platform. Clears it from the delist queue.

curl https://btb.net/api/v1/listings/1/delist \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY"
post /listings/{id}/end-on-ebay write

End on eBay

Ends an eBay listing on eBay through the team's linked eBay account, then marks it delisted (clearing it from the delist queue). A listing that had already ended on eBay is marked delisted too. Fails with platform_error when eBay refuses (e.g. the account needs reconnecting) and leaves the listing as it was.

curl https://btb.net/api/v1/listings/1/end-on-ebay \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY"
delete /listings/{id} write

Delete a listing

Removes the record entirely. Prefer /delist to keep history.

curl https://btb.net/api/v1/listings/1 \
  -X DELETE \
  -H "Authorization: Bearer $BTB_KEY"

Sales

post /items/{id}/sell write

Record a sale

Records the sale and decrements stock in one transaction. If the item sells out, the listing it sold through becomes sold and its other active listings become needs_delist ; those are returned in needs_delist so you can take them down.

Pass listing_id , or just platform and the item's live listing there is linked automatically. Send external_order_id (or an Idempotency-Key ) to make retries safe.

curl https://btb.net/api/v1/items/1/sell \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"poshmark","external_order_id":"PM-88213","platform_fees":"9.00","sale_price":"45.00","shipping_charged":"7.97"}'
get /sales

List sales

Most recent first, by sold_at .

Query Type Description
from timestamp Sold at or after (ISO 8601).
to timestamp Sold before (ISO 8601).
platform string Only sales on this platform.
limit integer Page size.
cursor string next_cursor from the previous page.
curl https://btb.net/api/v1/sales \
  -H "Authorization: Bearer $BTB_KEY"
get /sales/{id}

Get a sale

curl https://btb.net/api/v1/sales/1 \
  -H "Authorization: Bearer $BTB_KEY"
delete /sales/{id} write

Void a sale

Undoes a sale: restores stock and reopens listings flagged for delisting.

curl https://btb.net/api/v1/sales/1 \
  -X DELETE \
  -H "Authorization: Bearer $BTB_KEY"
get /stats/summary

Sales summary

Totals and net profit for a period.

Query Type Description
from timestamp Sold at or after (ISO 8601).
to timestamp Sold before (ISO 8601).
platform string Only sales on this platform.
curl https://btb.net/api/v1/stats/summary \
  -H "Authorization: Bearer $BTB_KEY"

Sync

post /sales write

Record a sale by platform ids

For sync clients that know the platform's ids but not BTB's. Identify what sold with external_listing_id + platform , listing_id , item_id or sku . Same effects as /items/{id}/sell : stock goes down and sell-outs flag other listings for delisting.

Always send external_order_id . If that order was already recorded on the platform, the existing sale comes back with 200 and already_recorded: true , so re-running a sync is safe. If the item has no stock left you get 409 oversold : it may have sold twice.

curl https://btb.net/api/v1/sales \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"poshmark","external_listing_id":"6523f0c1a9","sold_at":"2026-10-26T18:04:00Z","external_order_id":"PM-88213","platform_fees":"9.00","sale_price":"45.00"}'
put /platforms/{platform}/listings/{external_id} write

Create or update a listing by platform id

Upserts the listing with this platform listing id. Returns 201 when created, 200 when updated. Updating changes price, URL and status but never moves the listing to another item.

To create, say which item it's for: item_id , sku , or an item object. With sku + item , the item is created if the SKU is new. Set status to delisted to confirm a takedown, or sold when it sold.

curl https://btb.net/api/v1/platforms/poshmark/listings/6523f0c1a9 \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item":{"title":"Patagonia Better Sweater","brand":"Patagonia","cost":"8.00"},"url":"https://poshmark.com/listing/6523f0c1a9","price":"55.00","sku":"PAT-001"}'
get /to-ship

Orders waiting to ship

Orders the extension last saw waiting to ship on Poshmark, eBay, Depop, Mercari, Vinted and Facebook. Each platform's count is null until a read succeeds. A failed read keeps the last count, or null if there isn't one, and is not treated as zero. The top-level count adds up only the platforms that have a number. item_id is null when the SKU matches no item on the team.

curl https://btb.net/api/v1/to-ship \
  -H "Authorization: Bearer $BTB_KEY"
post /to-ship/snapshots write

Store a to-ship snapshot

One platform's current unshipped orders. Match an existing sale by external_order_id , otherwise an item and its live listing by SKU, otherwise store the line with no item. Send error when the site could not be read: the previous list is kept and the error is stored for that platform. A body without error is the full waiting list, and orders that are no longer in it are marked shipped. Does not change stock.

curl https://btb.net/api/v1/to-ship/snapshots \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"error":null,"count":1,"items":[{"title":"Patagonia Better Sweater","url":"https://poshmark.com/order/sales/PM-88213","sku":"PAT-001","external_order_id":"PM-88213"}],"platform":"poshmark"}'
get /accounts/{id}/offer-rules/{job}

Get an auto-offer rule

Settings for one auto-offer job on a marketplace account. Jobs are offers_to_likers , favorite_offers , flyp_send_offers and reactivate_inactive . A job with no saved row is returned disabled. Money fields are integer cents.

curl https://btb.net/api/v1/accounts/1/offer-rules/offers_to_likers \
  -H "Authorization: Bearer $BTB_KEY"
put /accounts/{id}/offer-rules/{job} write

Save an auto-offer rule

Replaces the rule for that account and job. shipping_discount_option is none , 499 or free . min_basis is price or earnings . min_amount_cents is an integer number of cents. Cookies and passwords are not accepted.

curl https://btb.net/api/v1/accounts/1/offer-rules/offers_to_likers \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"interval_minutes":30,"discount_pct":15,"shipping_discount_option":"499","min_basis":"earnings","min_amount_cents":1500,"exclude_listed_within_days":2,"like_lookback_days":7,"lower_to_pct":10,"max_per_run":20}'
get /accounts/{id}/offer-memory

Offer memory for listings

Liker memory and listing offer state for the given external listing ids. The same buyer and listing inside the memory window is already_handled . Depop keeps a pair for 60 days. Vinted keeps it. Listing state older than 180 days is left out.

Query Type Description
listings string Comma-separated external listing ids.
curl https://btb.net/api/v1/accounts/1/offer-memory \
  -H "Authorization: Bearer $BTB_KEY"
get /offers

List recorded offers

Seller sends and buyer offers for the team. from is inclusive and to is exclusive on offered_at . offer_to_likers is a seller send and is left out of initiated_by=buyer and out of stats.buyer_offers . stats is the Today line for the same range: seller items and people per marketplace. Flyp sends count as items with zero people. Amounts are integer cents.

Query Type Description
initiated_by buyer | seller buyer or seller.
from timestamp Offered at or after (ISO 8601).
to timestamp Offered before (ISO 8601).
curl https://btb.net/api/v1/offers \
  -H "Authorization: Bearer $BTB_KEY"
post /offers/sends write

Record a seller offer send

Records a seller-initiated send. kind offer_to_likers stores one recipient row per person, except Flyp ( via flyp ), which is items only. Depop and Vinted store one buyer and listing in liker memory ( offered , skipped or gave_up ). A Mercari price that is not strictly under marketplace_last_otl_cents is an attempt with outcome refused , not an offer. Amounts are integer cents.

curl https://btb.net/api/v1/offers/sends \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"via":"ui_automation","listing":{"title":"Jacket","external_id":"dep-1","price_cents":2500,"likes":2},"kind":"offer_to_likers","account_id":1,"recipients":[{"username":"buyer-a","external_user_id":"buyer-a"}],"run_id":1,"amount_cents":2000,"verified_at":"2026-11-05T12:00:00Z"}'
post /offers/attempts write

Record an offer send attempt

Stores a try that may not be an offer. outcome is sent , unconfirmed , not_sent , refused , failed or skipped . This does not create an offer. Amounts are integer cents.

curl https://btb.net/api/v1/offers/attempts \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"already offered","account_id":1,"outcome":"skipped"}'
post /offer-runs write

Record an auto-offer run

Writes one automation_run for offers_to_likers , favorite_offers , flyp_send_offers or reactivate_inactive . Flyp eBay forces people_count to 0. Reactivate stores Seller Hub before and after in details .

curl https://btb.net/api/v1/offer-runs \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"succeeded","details":{"after":4,"before":12},"summary":"reactivated","job":"reactivate_inactive","account_id":1,"people_count":0,"sent_count":2,"trigger":"manual"}'

Templates

get /items/{id}/listing

Finished listing for a platform

Everything needed to post the item on one platform: title, description, condition (and condition description), category and store category, custom label, item specifics, price, photos, policies and package. Rendered through the item's listing template for that platform when it has one, otherwise from the universal template. warnings lists anything to fix first; ready is true when there's nothing.

Query Type Description
platform string Platform to render for (required).
curl https://btb.net/api/v1/items/1/listing \
  -H "Authorization: Bearer $BTB_KEY"
get /templates

List listing templates

The seller's templates: fields, defaults, rules and title/description patterns.

curl https://btb.net/api/v1/templates \
  -H "Authorization: Bearer $BTB_KEY"
get /templates/{id}

Get a listing template

curl https://btb.net/api/v1/templates/1 \
  -H "Authorization: Bearer $BTB_KEY"

Payouts

put /accounts/{id}/balance write

Store a marketplace balance

Upserts the one balance row for this marketplace account. Amounts are integer cents. owed_cents is stored as sent: Poshmark pending is not added in. Send owed_cents equal to available when pending should stay out of the owed total.

curl https://btb.net/api/v1/accounts/1/balance \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency":"USD","available_cents":4200,"pending_cents":1500,"owed_cents":4200,"total_cents":5700,"captured_at":"2026-11-05T15:00:00Z"}'
get /balances

List marketplace balances

One row per account that has a stored balance. owed_cents on the envelope is the sum of account owed_cents for accounts whose payout sync is not paused. A paused account is still returned, with paused: true , and its owed amount is left out of that sum. Null owed counts as zero. Pending is not recomputed into owed.

curl https://btb.net/api/v1/balances \
  -H "Authorization: Bearer $BTB_KEY"
post /payouts write

Store a payout

Upserts on (marketplace account, external_payout_id) for the team's account on platform (eBay, Poshmark, Mercari, Vinted, Depop). The same external id updates that row. A later sync that omits a payout does not delete it. kind is withdrawal , sale_payout or clawback . A clawback may be a negative amount_cents . Currency is the account's currency. Omitted optional fields keep the stored value.

curl https://btb.net/api/v1/payouts \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid","kind":"clawback","method":"ach","platform":"depop","amount_cents":-350,"external_payout_id":"deposit:9","paid_at":"2026-11-01T12:00:00Z","fee_cents":0,"external_status":"taken back"}'
get /payouts

List payouts

Payouts for the team, newest paid_at first. from is inclusive and to is exclusive, compared to paid_at . Paused accounts are included.

Query Type Description
platform string Only payouts on this platform.
from timestamp Paid at or after (ISO 8601).
to timestamp Paid before (ISO 8601).
curl https://btb.net/api/v1/payouts \
  -H "Authorization: Bearer $BTB_KEY"
put /accounts/{id}/sync/payouts

Pause or resume payout sync

Writes account_sync_state for job payouts . Only paused is updated. Allowed with a read-only key (Payout Desk): it only chooses which sites BTB Everything reads. A paused account's balance stays stored and is left out of the owed total from GET /balances.

curl https://btb.net/api/v1/accounts/1/sync/payouts \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paused":true}'
post /payouts/import write

Import Payout Desk's stored history

Payout Desk 0.5.0's one-time copy of what it kept: per site ( ebay , poshmark , mercari , vinted , depop ) the balance ( available , pending , owed , dollars), payouts ( id , at , amount , status , sale ) and state ( backfilled , settled , historyFrom ). Payouts upsert by their site id, so sending it again only updates. Answers per site how many payouts were saved and how many failed.

curl https://btb.net/api/v1/payouts/import \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sites":{"depop":{"pending":30.0,"state":{"backfilled":true,"historyFrom":"2026-01-01","settled":[]},"available":120.5,"payouts":[{"id":"deposit:9","status":"Bank deposit","at":"2026-11-02T15:00:00Z","amount":400.0}]}}}'
post /payouts/refresh

Read the sites now

Asks the computer where BTB Everything is On to read these sites' balances and payouts now ( sites , else all). The numbers arrive on GET /balances and GET /payouts when it's done. 409 no_computer when BTB Everything isn't On anywhere.

curl https://btb.net/api/v1/payouts/refresh \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sites":["depop"]}'
get /payouts/reads

Each site's last read

Per site: read_at (last good read), tried_at , error (only while newer than the last good read), history_from (the site's own history starts there) and backfilled .

curl https://btb.net/api/v1/payouts/reads \
  -H "Authorization: Bearer $BTB_KEY"

Offers

get /offers

List buyer offers

Offers waiting on the seller, or every kind except offer_to_likers . status=pending is the inbox: buyer offers that are still pending. Amounts are integer cents.

Query Type Description
status pending | accepted | declined | countered | expired | cancelled Only offers in this status.
platform string Only offers on this platform.
curl https://btb.net/api/v1/offers \
  -H "Authorization: Bearer $BTB_KEY"
get /offers/stats

Offer desk stats

Waiting, received, accepted, countered, counters accepted, and deal rate. Offers to likers are excluded. from is inclusive and to is exclusive. Waiting is the current buyer inbox and ignores the window. Amounts are integer cents.

Query Type Description
platform string Only offers on this platform.
from timestamp Inclusive start (ISO 8601).
to timestamp Exclusive end (ISO 8601).
curl https://btb.net/api/v1/offers/stats \
  -H "Authorization: Bearer $BTB_KEY"
get /offer-threads

List offer threads

follow=due returns threads whose follow_until is now or earlier.

Query Type Description
follow due Pass due for threads that should be re-read.
curl https://btb.net/api/v1/offer-threads \
  -H "Authorization: Bearer $BTB_KEY"
post /offers/inbox write

Upsert an offer inbox

Stores threads and offers from a marketplace read. The same (external_offer_id, initiated_by) updates the existing row. kind is buyer_offer or counter . Does not call the marketplace. Amounts are integer cents.

curl https://btb.net/api/v1/offers/inbox \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threads":[{"offers":[{"currency":"USD","kind":"buyer_offer","amount_cents":2200,"listing_price_cents":4500,"initiated_by":"buyer","external_offer_id":"off-1"}],"external_listing_id":"v1","external_thread_id":"thread-v1","history_partial":false}],"platform":"vinted"}'
post /offers/{id}/accept write

Accept an offer

Enqueues a respond_offer listing task with op accept . A second accept of an already decided offer returns that decision and does not enqueue again.

curl https://btb.net/api/v1/offers/1/accept \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY"
post /offers/{id}/decline write

Decline an offer

Enqueues a respond_offer listing task with op decline .

curl https://btb.net/api/v1/offers/1/decline \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"No thanks"}'
post /offers/{id}/counter write

Counter an offer

Enqueues a respond_offer listing task with op counter . The amount must be above the buyer's offer and, when set, inside counter_min_cents and counter_max_cents . Otherwise the response is 422. A counter the buyer might accept sets follow_until four days out. blocked: true records eBay's limit for seven days and does not enqueue. Amounts are integer cents.

curl https://btb.net/api/v1/offers/1/counter \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Meet you part way","amount_cents":1999}'
post /offers/{id}/result write

Record a marketplace answer

The extension reports how accept, decline, or counter finished and the listing task completes. error or blocked: true puts a seller decision back to pending. blocked: true sets counter_blocked_until seven days out.

curl https://btb.net/api/v1/offers/1/result \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"error":null,"blocked":false,"status":"accepted","decided_by":"seller"}'
put /conversations write

Store a detected in-chat price

Stores the detected price only. detected_offer_text must be 140 characters or fewer. Full chat text is not stored.

curl https://btb.net/api/v1/conversations \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"facebook","external_thread_id":"fb-1","awaiting_reply":true,"detected_offer_cents":2500,"detected_offer_text":"Would you take 25?"}'

Worker

post /devices write

Register a device

Registers an extension device. The token is returned once; only its HMAC is stored. Later calls send it as the X-Device-Token header, or as JSON device_token . Authorization: Bearer remains the API key.

curl https://btb.net/api/v1/devices \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Greg laptop","version":"1.4.0"}'
post /devices/heartbeat write

Device heartbeat

Updates version , last_seen_at and signed_in . Identify the device with X-Device-Token or JSON device_token . A revoked device returns 401. signed_in maps this team's marketplace account ids to ISO 8601 times. Omitting it clears the map.

curl https://btb.net/api/v1/devices/heartbeat \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version":"1.4.0","signed_in":{"12":"2026-11-05T18:00:00Z"},"device_token":"btd_example"}'
post /accounts/{id}/lease write

Lease an account

Takes or renews the lease via claim_account_lease (default 120 seconds, max 86400). A second device cannot take a live lease (409 lease_held ). Send X-Device-Token or JSON device_token . A revoked device returns 401.

curl https://btb.net/api/v1/accounts/1/lease \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seconds":120}'
delete /accounts/{id}/lease write

Release an account lease

Drops the lease when this device holds it, or when it is already free. A live lease held by another device is 409 lease_held . Send X-Device-Token or JSON device_token .

curl https://btb.net/api/v1/accounts/1/lease \
  -X DELETE \
  -H "Authorization: Bearer $BTB_KEY"
post /tasks/claim write

Claim due tasks

Locks due pending listing_task and account_task rows for accounts this device currently leases ( status running, locked_at , locked_by_device_id ). Rows locked by another device are left alone. Send X-Device-Token . Claiming does not increment attempts .

curl https://btb.net/api/v1/tasks/claim \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY"
post /tasks/{kind}/{id}/result write

Record a task result

kind is listing or account . error is stored as last_error . progress is stored on account tasks; listing tasks have no progress column. A finished task is returned unchanged so a retry does not increment attempts . Send X-Device-Token . The same Idempotency-Key replays the first response.

curl https://btb.net/api/v1/tasks/listing/1/result \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"error":null,"status":"succeeded"}'
post /runs write

Open an automation run

job is an automation_job. trigger is scheduled, manual, turned_on or job. mode is full or quick. status is running, succeeded, problem, failed, stopped or timed_out. Optional X-Device-Token sets device_id ; a revoked token is 401.

curl https://btb.net/api/v1/runs \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"running","mode":"quick","job":"sync_listings","trigger":"manual"}'
patch /runs/{id} write

Update an automation run

Updates counters and status. A terminal status sets finished_at when it was empty. Optional X-Device-Token ; a revoked token is 401.

curl https://btb.net/api/v1/runs/1 \
  -X PATCH \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"succeeded","total":3,"done":3}'
get /accounts/{id}/sync/{job}

Get account sync state

account_sync_state for this account and job: paused, cursor, watermarks, blocked_until and last_error .

curl https://btb.net/api/v1/accounts/1/sync/offers_to_likers \
  -H "Authorization: Bearer $BTB_KEY"
put /accounts/{id}/sync/{job} write

Save account sync state

Creates or updates that sync state. Omitted fields on an existing row are kept.

curl https://btb.net/api/v1/accounts/1/sync/offers_to_likers \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cursor":{"page":"2"},"paused":false,"last_error":null}'
get /schedules

List sync schedules

Schedules for the team. Each row sets interval_minutes or daily_at , never both. A null marketplace_account_id is the team-wide schedule for that job.

curl https://btb.net/api/v1/schedules \
  -H "Authorization: Bearer $BTB_KEY"
put /schedules write

Upsert a sync schedule

Upserts (team, account or team-wide, job) . Send exactly one of interval_minutes or daily_at ; the other is cleared. daily_at is a clock time HH:MM:SS .

curl https://btb.net/api/v1/schedules \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"job":"follow","interval_minutes":30}'
get /accounts/{id}/rates

List rate counters

Daily counters. action is follow, offer, post or share.

Query Type Description
action follow | offer | post | share Only this action.
day string ISO date (YYYY-MM-DD).
curl https://btb.net/api/v1/accounts/1/rates \
  -H "Authorization: Bearer $BTB_KEY"
post /accounts/{id}/rates write

Set a rate counter

Sets n for (account, action, day) . This replaces the count; it does not add. Omit day for today in the team's time zone.

curl https://btb.net/api/v1/accounts/1/rates \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"follow","n":4,"day":"2026-11-05"}'

Price drop

get /price-drop/rules

Get the price-drop rule

The team's rule. Defaults are returned before one is saved.

curl https://btb.net/api/v1/price-drop/rules \
  -H "Authorization: Bearer $BTB_KEY"
put /price-drop/rules write

Save the price-drop rule

Creates or updates the team's rule. pct is 1 to 90.

curl https://btb.net/api/v1/price-drop/rules \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rounding":"x99","batch_size":25,"pct":"20.00","min_active_listings":4,"min_days_since_change":61,"min_last_change_on":"2026-02-15","relist_marketplace_ids":[2,3,5]}'
post /price-drop/plans write

Build a price-drop plan

Draft plan from the enabled rule. Qualifying items are the oldest last-changed first. x99 rounding lowers by pct , then snaps to the nearest price ending in .99, and never goes under 99 cents. Amounts are integer cents.

curl https://btb.net/api/v1/price-drop/plans \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY"
patch /price-drop/plans/{id}/items/{item_id} write

Edit a draft plan item

Sets include and pct, then recalculates the target. Only while the plan is a draft.

curl https://btb.net/api/v1/price-drop/plans/1/items/1 \
  -X PATCH \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include":false,"pct":"15.00"}'
post /price-drop/plans/{id}/start write

Start a price-drop plan

Sets the plan to running. Included items get progress and a started step per live listing: price , plus relist when that marketplace is in relist_marketplace_ids . Items with include false are skipped and get no steps.

curl https://btb.net/api/v1/price-drop/plans/1/start \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY"
put /price-drop/items/{item_id}/steps write

Record a price-drop step

One row per item, listing, and step. Sending done again keeps that one row. A later started does not change a step that is already done.

curl https://btb.net/api/v1/price-drop/items/1/steps \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"error":null,"status":"done","step":"price","listing_id":1,"target_price_cents":3199}'
get /price-drop/progress

List price-drop progress

curl https://btb.net/api/v1/price-drop/progress \
  -H "Authorization: Bearer $BTB_KEY"
post /sales/sync write

Sync orders in a window

Sales whose sold_at is inside the window and whose external_order_id is absent from orders are marked cancelled. Sales outside the window are kept.

curl https://btb.net/api/v1/sales/sync \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-06-01T00:00:00Z","orders":[{"platform":"poshmark","external_order_id":"PM-88213"}],"to":"2026-06-30T23:59:59Z"}'
get /sales/profit-needed

Sales missing earnings

Sales with no reported_payout_cents . Cancelled and unpaid orders are left out.

curl https://btb.net/api/v1/sales/profit-needed \
  -H "Authorization: Bearer $BTB_KEY"
post /sales/{id}/profit write

Record sale earnings

earnings_cents is stored as reported_payout_cents . The sale then leaves profit-needed.

curl https://btb.net/api/v1/sales/1/profit \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"earnings_cents":2500}'
post /listing-issues write

Open a listing issue

curl https://btb.net/api/v1/listing-issues \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"stale_link","sku_text":"PAT-001"}'
get /listing-issues

List listing issues

Query Type Description
open boolean When true, only issues with no resolved_at.
curl https://btb.net/api/v1/listing-issues \
  -H "Authorization: Bearer $BTB_KEY"
post /listing-issues/{id}/resolve write

Resolve a listing issue

Sets resolved_at once. A second call keeps the first timestamp.

curl https://btb.net/api/v1/listing-issues/1/resolve \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resolution":"delisted the stale link"}'
post /store-size write

Record daily store size

One reading per team per day. A second post for the same day replaces the qty.

curl https://btb.net/api/v1/store-size \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"day":"2026-06-02","qty":120}'

Crosslist

post /imports/ebay write

Import an eBay listing

Creates or refreshes the item and its eBay listing from the extension. A later import updates eBay and the general fields. A site title, description, or price the seller already changed is left as they set it. Returns 201 the first time and 200 when the same eBay listing is imported again.

curl https://btb.net/api/v1/imports/ebay \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Light wash trucker jacket","title":"Vintage denim jacket","condition":"good","price":"45.00","sku":"JKT-1","photos":["https://cdn.example/1.jpg","https://cdn.example/2.jpg"],"quantity":1,"external_id":"123456789012","package":{"height_in":"2","length_in":"12","weight_oz":"16","width_in":"10"},"specifics":{"Brand":"Levi's"}}'
get /items/{id}/crosslist

Crosslist an item

General fields plus each marketplace's status and site-specific fields. Photo position 0 is the cover.

curl https://btb.net/api/v1/items/1/crosslist \
  -H "Authorization: Bearer $BTB_KEY"
put /listings/{id}/fields write

Update one site's fields

Writes that listing's title, description, price, category, photo order, and the columns of its marketplace table. photo_ids is this item's photo ids; the first one is the cover. Unknown keys are ignored.

curl https://btb.net/api/v1/listings/1/fields \
  -X PUT \
  -H "Authorization: Bearer $BTB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Posh Custom","category":"200","price":"45.00","platform":"poshmark","photo_ids":[1,2]}'
post /listings/{id}/publish write

Enqueue publish

Enqueues a publish task, or update when the listing already has an external id. Title and price are required. Category is required too. Missing fields return 422 and nothing is enqueued.

curl https://btb.net/api/v1/listings/1/publish \
  -X POST \
  -H "Authorization: Bearer $BTB_KEY"
get /platforms/{platform}/taxonomy

Marketplace taxonomy

Categories and attribute definitions stored for that platform. An empty list means nothing is synced yet.

curl https://btb.net/api/v1/platforms/poshmark/taxonomy \
  -H "Authorization: Bearer $BTB_KEY"