Product and Discovery API

Every product API request requires a registered application. There is no anonymous API tier, and general discovery never requires a seller credential. Direct apps use client credentials; third-party apps use explicit buyer or seller consent with Authorization Code + S256 PKCE.

Base URL

https://zoipler.com/api/v1

Authentication

Exchange the registered client ID and secret for a short-lived application token. Secrets belong only in server-side applications.

curl -X POST 'https://zoipler.com/api/v1/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "zapp_...",
    "client_secret": "zsec_...",
    "scope": "products:read offers:read pricing:read delivery:quote"
  }'

Send the returned zat_... token as Authorization: Bearer .... Tokens expire after 15 minutes by default.

Third-party applications

Send the owner to https://zoipler.com/oauth/authorize with an exact registered redirect_uri, response_type=code, subject_type=buyer or seller, scopes, state, and an S256 PKCE challenge. Exchange the single-use zac_... code at the token endpoint. Rotating zrt_... refresh tokens are returned for delegated grants; reuse revokes the family.

Implemented resources

Method	Endpoint	Scope
GET	`/search`, `/search/suggestions`	`products:read`
GET	`/products/{zoid}`	`products:read`
POST	`/products/batch`	`products:read bulk:read` + bulk entitlement
GET	`/products/{zoid}/offers`	`offers:read pricing:read`
POST	`/delivery-promises`	`delivery:quote`
GET	`/taxonomy/versions/current`, `/taxonomy/categories`	`taxonomy:read`
GET	`/products/{zoid}/sales-ranks`	`ranks:read`
GET	`/products/{zoid}/history/{prices\|ranks\|sales}`	Dataset scope + entitlement
GET	`/products/{zoid}/recommendations`	`recommendations:read`
POST	`/exports`	`bulk:read` + bulk entitlement
GET	`/changes`	`changes:read` + changes entitlement
POST	`/webhook-subscriptions` and delivery controls	`changes:read webhooks:manage` + changes entitlement

Rate limits and metering

Calls consume weighted application, organization, optional grant and endpoint-family buckets. Responses include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-Zoipler-RateLimit-Bucket and X-Zoipler-Request-Cost.

Data semantics

Money is a decimal string plus ISO currency; landed totals reconcile their components.
Delivery promises are offer-, quantity-, destination- and time-specific and carry expiry and limitations.
Ranks are category- and marketplace-scoped.
Sales history explicitly distinguishes actual, observed_external and estimated.
Missing historical observations are null with a reason, never silently changed to zero.

View the complete OpenAPI contract