Partner API
Build fast on wiinta.
One base URL, five endpoints, deterministic ids. Sync your whole catalog or one SKU at a time - the pipeline is idempotent, so retries always converge.
Quickstart
Four calls to a smarter catalog
- 1
Register your brand
Name, website, vertical. Wiinta verifies the storefront so your product URLs always belong to you.
- 2
Mint a key
From the portal. Shown once, hashed at rest, 60 requests a minute, every plan.
- 3
POST your products
Full mode first, incremental after. Rows are validated against the ontology and staged in the mirror.
- 4
Watch the demand arrive
Ping, list and insights keep your systems honest about what wiinta knows.
$ curl -X POST https://wiinta.com/api/merchants/v1/products \
-H "Authorization: Bearer wbk_live_..." \
-d '{ "mode": "full", "products": [...] }'
{"accepted": 1240, "published": 1240, "rejected": 0}Endpoint reference
Base URL: https://wiinta.com/api/merchants/v1
/api/merchants/v1/productsbody { "mode": "full" | "incremental", "products": [ { externalId, url, name, price, images, ... } ] }
returns { mode, accepted, rejected, published, withdrawn, rows: [{ externalId, ok, staged, errors, publishedProductId }] }
Upsert a batch of up to 5,000 rows (4 MB), within your plan limit. Full mode replaces the entire catalog in one transaction and rejects invalid files. Incremental mode touches only the rows sent.
/api/merchants/v1/products?limit=100&offset=0&updated_since=<iso>returns { brand, total, offset, limit, products: [{ externalId, url, name, price, status, available, lastSyncedAt }] }
List your rows exactly as wiinta stores them, including validation state.
/api/merchants/v1/productsbody { "externalIds": ["SKU-1", "SKU-2"] }
returns { withdrawn, externalIds }
Withdraw up to 1,000 SKUs per call. Products are withdrawn from new search results; withdrawn rows never count against your plan cap.
/api/merchants/v1/insights?days=30returns { totals: { views, clickOuts, saves }, topQueries: [...], gaps: [...] }
Engagement and demand data for your range, windowed by your plan. New activity appears after the search completes; contact details are redacted.
/api/merchants/v1/pingreturns { ok: true, brand: { slug, name, status, vertical }, publishable }
Auth check and brand status in one round trip. Build your health checks on this.
Limits and errors
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHENTICATED | Missing or bad API key. Keys read "Authorization: Bearer wbk_live_...". |
| 403 | PLAN_LIMIT | The sync would exceed your plan’s live catalog. Withdraw rows or upgrade. |
| 403 | URL_OWNERSHIP | A product URL sits outside your verified domain. |
| 400 | INVALID_INPUT | Row-level validation failed. The rows array names every field. |
| 413 | TOO_LARGE | Send at most 5,000 products and 4 MB per import. |
| 429 | RATE_LIMITED | Over 60 requests per minute on this key. Back off and retry. |
Do I need the API?
No. The portal CSV upload applies the same validation and reaches the same racks. The API is for merchants who want their stock system and wiinta to stay in step automatically.
What does idempotent actually mean here?
Every row is keyed by your externalId and every published row by a deterministic id derived from your URL. Send the same batch twice and the second call converges to the same state instead of duplicating anything.
How fast is the sync?
Batches are acknowledged in seconds; products are staged in the catalogue mirror before the next shopper ask. Shoppers never wait on your sync, and never see a price you retired.
Is my key safe?
Keys are shown once at mint, stored only as hashes, revocable instantly in the portal, and rate limited per key. They are server-to-server credentials: never paste them into a website.
Your catalog, staged before the ask.
Every plan includes the API. Mint a key in the portal and make your first call this afternoon.