Catalog feed (scheduled sync)

If you already export a Google Merchant Center or Meta Commerce Manager-style feed for your own shopping/ads listings, you can point that same feed at TBBN instead of building an API integration. This is the lower-effort alternative to direct listing sync — use either, or both (bulk catalog via feed, high-velocity individual items via the API). Every listing looks identical to TBBN once it's ingested, regardless of which path created it.

Set up a feed source

POST /v1/merchant/feed-source
{
  "feedUrl": "https://yourstore.example.com/feeds/tbbn.xml",
  "feedFormat": "XML",
  "feedUsername": "...",
  "feedPassword": "...",
  "defaultSellerId": "sel_01hxyz..."
}

feedFormat is XML (RSS 2.0-shaped) or CSV/TSV. feedUsername/feedPassword are sent as HTTP Basic Auth when TBBN fetches your URL — never embed credentials in the URL string itself. defaultSellerId is required: the feed format has no per-item seller concept, so every listing from one feed is attributed to one Seller on your account.

TBBN pulls the feed every 24 hours. Trigger an immediate pull any time with:

POST /v1/merchant/feed-source/fetch-now

Feed fields

Field names deliberately match Google's established vocabulary (id, title, price, condition, image_link, availability) — if you're already running a feed app that outputs a Google/Meta-shaped feed, pointing it at TBBN is usually just a destination-URL change.

Field	Required	Notes
`item_id`	Yes	Unique key; identifies this listing across re-fetches.
`category`, `sub_category`	Yes	Two-tier taxonomy — enables cross-catalog matching while preserving your own organization.
`brand`	Conditional	Required unless your category is a declared no-brand category.
`condition`	Yes	Required on every item — trade-fairness scoring needs it.
`original_price`	Yes	Numeric + ISO 4217 currency code, e.g. `19.99 USD`.
`listing_type`	Yes	`SALE` / `TRADE` / `BOTH`. A `SALE` listing is discovery-only and never offer-able — TBBN links out to `product_link` instead of orchestrating a trade for it.
`wants`	No	Structured trade-preference array, reusing the `category`/`sub_category` taxonomy above.
`image_link`, `additional_image_link[]`	Primary required	One primary image, optional secondary images.
`quantity`, `availability`	Yes	A real count, not just in-stock/out-of-stock — reservations need it.
`product_link`	No	URL to the item's page on your own site. Required for a `SALE`-only listing, since that's the only link shown for it.

Every ingested row runs through the exact same validation your direct API calls do — a fed-in listing and an API-submitted listing are indistinguishable to every downstream consumer.

Known limitation

Create and update work on every pull. Delete does not yet: a listing whose item_id disappears from your feed is not automatically deactivated on TBBN. Deactivate it directly via DELETE /merchant/listings/:id in the meantime.