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.

Every call needs your API key plus the HMAC signature headers. See Authentication for how to sign requests.

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

POST/api/v1/products/importidempotent

Import products

Bulk-create products (up to 5000 per call). Product URLs must be on your approved domain.

Request body

{
  "products": [
    {
      "externalProductId": "SKU-100",
      "name": "Wireless Earbuds",
      "productUrl": "https://merchant-store.com/p/sku-100",
      "price": "2999.00",
      "currency": "NPR",
      "commissionType": "PERCENTAGE",
      "commissionValue": "10"
    }
  ]
}

Response · 202

{
  "received": 1,
  "created": 1,
  "updated": 0,
  "failed": 0
}

POST/api/v1/products/upsertidempotent

Upsert products

Create or update products by externalProductId (unique per merchant).

Request body

{
  "products": [
    {
      "externalProductId": "SKU-100",
      "name": "Wireless Earbuds v2",
      "productUrl": "https://merchant-store.com/p/sku-100",
      "price": "2799.00"
    }
  ]
}

Response · 202

{
  "received": 1,
  "created": 0,
  "updated": 1,
  "failed": 0
}

GET/api/v1/products

List products

Paginated list of your products. Query: page, pageSize (≤200), status, category, campaignId, search.

Response · 200

{
  "data": [
    {
      "id": "uuid",
      "externalProductId": "SKU-100",
      "name": "Wireless Earbuds",
      "status": "ACTIVE"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

GET/api/v1/products/{id}

Get a product

Fetch one of your products by its platform id.

PATCH/api/v1/products/{id}

Update a product

Partially update a product (name, price, stockStatus, commission, status, …).

Request body

{
  "price": "2599.00",
  "stockStatus": "OUT_OF_STOCK"
}

POST/api/v1/products/archive

Archive products

Archive products by platform id. Archived products stop generating new links.

Request body

{
  "productIds": [
    "uuid-1",
    "uuid-2"
  ]
}

Response · 200

{
  "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.