Catalog
Products API
Sync your product catalog into the platform so affiliates can promote it. Import and upsert run in bulk and asynchronously; list, get, update and archive operate on individual products.
Endpoints
| Method | Path | Idempotent | Status |
|---|---|---|---|
| POST | /api/v1/products/import | Yes | 202 |
| POST | /api/v1/products/upsert | Yes | 202 |
| GET | /api/v1/products | — | 200 |
| GET | /api/v1/products/{id} | — | 200 |
| PATCH | /api/v1/products/{id} | — | 200 |
| POST | /api/v1/products/archive | — | 200 |
Field reference
Bulk write bodies (import and upsert) take a products array of ProductInput objects. The same shape is used when creating or updating a single product.
| Field | Type | Required | Notes |
|---|---|---|---|
externalProductId | string | Yes | Your own product id. ≤120 chars. Unique per merchant — upsert keys on this. |
name | string | Yes | Display name. ≤255 chars. |
description | string | — | Optional long description. |
productUrl | string (URL) | Yes | Landing URL. MUST be on your approved domain or the item is rejected. |
imageUrl | string (URL) | — | Optional product image URL. |
category | string | — | Optional category label. |
brand | string | — | Optional brand label. |
price | string (decimal) | Yes | Decimal string, e.g. "2999.00". Not a number. |
discountPrice | string (decimal) | — | Optional sale price as a decimal string. |
currency | string | — | ISO currency code, e.g. NPR. |
stockStatus | string | — | e.g. IN_STOCK / OUT_OF_STOCK. |
commissionType | enum | — | PERCENTAGE | FIXED. |
commissionValue | string | — | Commission amount as a decimal string. |
campaignId | string | — | Optional campaign to attach the product to. |
Validation rules
productUrl must resolve to one of your approved domains; an off-domain URL rejects that item with 400. Monetary fields — price, discountPrice and commissionValue — are decimal strings (e.g. "2999.00"), never JSON numbers, to avoid float rounding. A single import or upsert call accepts up to 5000 items; split larger catalogs across calls.
Idempotency
import, upsert and single-product create honor X-Idempotency-Key, so a safe retry replays the original response instead of writing twice. See Idempotency for details.
Endpoint details
Import products
Bulk-create products (up to 5000 per call). Product URLs must be on your approved domain.
{
"products": [
{
"externalProductId": "SKU-100",
"name": "Wireless Earbuds",
"productUrl": "https://merchant-store.com/p/sku-100",
"price": "2999.00",
"currency": "NPR",
"commissionType": "PERCENTAGE",
"commissionValue": "10"
}
]
}{
"received": 1,
"created": 1,
"updated": 0,
"failed": 0
}Upsert products
Create or update products by externalProductId (unique per merchant).
{
"products": [
{
"externalProductId": "SKU-100",
"name": "Wireless Earbuds v2",
"productUrl": "https://merchant-store.com/p/sku-100",
"price": "2799.00"
}
]
}{
"received": 1,
"created": 0,
"updated": 1,
"failed": 0
}List products
Paginated list of your products. Query: page, pageSize (≤200), status, category, campaignId, search.
{
"data": [
{
"id": "uuid",
"externalProductId": "SKU-100",
"name": "Wireless Earbuds",
"status": "ACTIVE"
}
],
"page": 1,
"pageSize": 50,
"total": 1
}Get a product
Fetch one of your products by its platform id.
Update a product
Partially update a product (name, price, stockStatus, commission, status, …).
{
"price": "2599.00",
"stockStatus": "OUT_OF_STOCK"
}Archive products
Archive products by platform id. Archived products stop generating new links.
{
"productIds": [
"uuid-1",
"uuid-2"
]
}{
"archived": 2
}upsert is keyed on externalProductId, which is unique per merchant: a matching id updates the existing product, otherwise a new one is created.Attach products to a campaign with campaignId — see the Campaigns API.