Seller API

Seller inventory and lead write-back are disabled on this deployment. Marketplace search stays disabled.

marketplace_search — disabled

Authentication and payment

Send Authorization: Bearer with a seller API token. Grant scopes are read, write and publish. A workspace grant covers seller inventory; missing entitlement is 403 not_entitled and a used-up allowance is 429 quota_exceeded. That grant is not an MPP payment. When a machine surface returns 402, retry with the same bearer token and Payment-Authorization. Payment never replaces the API credential. Webhook signing secrets cannot authenticate requests.

HTTP contract

Create, update, delete and publish return 200 with a data object and an ETag. Delete of a draft is 200 with deleted true. Lead write-back is POST /api/tenants/{tenant_slug}/leads and returns 201. Mutations send If-Match; a missing precondition is 428 and a stale one is 412. Repeating the same reference_code, content_source and payload returns the same listing. Prices use integer amount_minor in the currency the seller quotes. Discover markets, areas, fields and currencies at GET /api/seller/vocabulary. Photo upload returns 422 cloudflare_not_configured until media delivery is configured. Publish returns 422 with seller_clearance_required until seller admission is current, or private_owner_quota when a private seller already has an active listing. Withdraw with POST /api/seller/listings/{id}/withdraw; a non-draft delete returns 409 withdraw_instead. Other listed errors include 400, 401 and 404.

get /api/seller/listings	200, 400, 401, 403, 404, 429 — disabled
post /api/seller/listings	200, 400, 401, 403, 404, 409, 422, 429 — disabled
delete /api/seller/listings/{id}	200, 400, 401, 403, 404, 409, 412, 422, 428, 429 — disabled
get /api/seller/listings/{id}	200, 400, 401, 403, 404, 429 — disabled
patch /api/seller/listings/{id}	200, 400, 401, 403, 404, 412, 422, 428, 429 — disabled
post /api/seller/listings/{id}/photos	200, 400, 401, 403, 404, 412, 422, 428, 429 — disabled
delete /api/seller/listings/{id}/photos/{photo_id}	200, 400, 401, 403, 404, 412, 422, 428, 429 — disabled
patch /api/seller/listings/{id}/photos/{photo_id}	200, 400, 401, 403, 404, 412, 422, 428, 429 — disabled
post /api/seller/listings/{id}/photos/{photo_id}/complete	200, 400, 401, 403, 404, 412, 422, 428, 429 — disabled
post /api/seller/listings/{id}/publish	200, 400, 401, 403, 404, 412, 422, 428, 429 — disabled
post /api/seller/listings/{id}/withdraw	200, 400, 401, 403, 404, 412, 422, 428, 429 — disabled
get /api/seller/published	200, 400, 401, 403, 404, 429 — disabled
get /api/seller/published/{id}	200, 400, 401, 403, 404, 429 — disabled
get /api/seller/vocabulary	200, 400, 401, 403, 404, 429 — disabled
post /api/tenants/{tenant_slug}/leads	201, 404, 422 — disabled

Webhooks

Deliveries are JSON with event, listing_id, tenant_id and occurred_at, plus headers x-tapakly-event and x-tapakly-signature: sha256= HMAC-SHA256 of the raw body. Wire events are listing_created, listing_updated and listing_deleted. A test event is integration_test. Check the signature, mark the listing dirty, and refetch current API state. Do not write inventory because a webhook arrived, and ignore duplicates, invalid signatures and older events after you have refetched.

Two recipes, one inventory

Tapakly-managed inventory: read GET /api/seller/published and render it on your site. CMS-managed inventory: your server writes POST /api/seller/listings and publishes when admission allows it. Pick one authoritative source. The other side displays or receives; it does not overwrite back.

tapakly CLI

Drive seller inventory from a terminal. Every command below exists in clients/cli. Pass --json for a stable machine record.

tapakly vocabulary
tapakly listings list
tapakly listings show
tapakly listings create
tapakly listings update
tapakly listings publish
tapakly listings withdraw
tapakly listings delete
tapakly photos upload
tapakly published
tapakly auth set

Install

No public download is published yet. Build the CLI from this repository:

cd clients/cli
go build -o tapakly .