BTB API
Track inventory, listings and sales across every platform you sell on. JSON over HTTPS, authenticated with 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 likeebay. - Errors
-
Always
{"error": {"code", "message", "details"}}. Field errors come back as 422 with per-field messages indetails. - Pagination
-
Lists return
next_cursor; pass it back as?cursor=. It's null on the last page. - Retries
-
Send an
Idempotency-Keyheader 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 includesretry-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
/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
/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
/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"
/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"}'
/items/{id}
Get an item
curl https://btb.net/api/v1/items/1 \
-H "Authorization: Bearer $BTB_KEY"
/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)"}'
/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"
/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"}'
/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
/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"}'
/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"
/listings/{id}
Get a listing
curl https://btb.net/api/v1/listings/1 \
-H "Authorization: Bearer $BTB_KEY"
/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"}'
/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"
/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"
/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
/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"}'
/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"
/sales/{id}
Get a sale
curl https://btb.net/api/v1/sales/1 \
-H "Authorization: Bearer $BTB_KEY"
/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"
/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
/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"}'
/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"}'
/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"
/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"}'
/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"
/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}'
/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"
/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"
/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"}'
/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"}'
/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
/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"
/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"
/templates/{id}
Get a listing template
curl https://btb.net/api/v1/templates/1 \
-H "Authorization: Bearer $BTB_KEY"
Payouts
/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"}'
/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"
/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"}'
/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"
/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}'
/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}]}}}'
/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"]}'
/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
/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"
/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"
/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"
/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"}'
/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"
/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"}'
/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}'
/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"}'
/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
/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"}'
/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"}'
/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}'
/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"
/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"
/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"}'
/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"}'
/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}'
/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"
/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}'
/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"
/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}'
/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"
/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
/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"
/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]}'
/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"
/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"}'
/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"
/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}'
/price-drop/progress
List price-drop progress
curl https://btb.net/api/v1/price-drop/progress \
-H "Authorization: Bearer $BTB_KEY"
/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"}'
/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"
/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}'
/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"}'
/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"
/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"}'
/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
/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"}}'
/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"
/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]}'
/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"
/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"