Products

Manage the catalog that powers your storefronts, orders, and conversations. Use this API to keep products in sync with your inventory or commerce systems.

All endpoints share the prefix /v1/products and authenticate with an API key.

Endpoint	Scope
`GET /v1/products`	`products:read`
`GET /v1/products/:id`	`products:read`
`POST /v1/products`	`products:write`
`PATCH /v1/products/:id`	`products:write`

List products


GET /v1/products

Query parameters

Parameter	Type	Description
`search`	string	Match against product name
`page`	number	Page number (default `1`)
`limit`	number	Items per page (default `50`)


{
  "message": "Products retrieved",
  "data": [
    {
      "id": "p1a2b3c4-...",
      "name": "Jollof Rice",
      "price": 2500,
      "quantity": 40,
      "sku": "JR-001",
      "isActive": true,
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "perPage": 50, "totalPages": 1, "hasMore": false }
}

Get a product


GET /v1/products/:id

Returns a single product with its variants. Responds 404 not_found if the ID doesn’t belong to your business.

Create a product


POST /v1/products

Creating a product with a name that already exists updates the existing one instead of creating a duplicate.

Body

Field	Type	Required	Description
`name`	string	Yes	Product name (2–255 characters)
`price`	number	Yes	Selling price
`description`	string	No	Product description
`quantity`	number	No	Initial stock quantity
`sku`	string	No	Stock-keeping unit
`barcode`	string	No	Barcode
`category_id`	uuid	No	Category to file under
`cost_price`	number	No	Your cost, for margin reporting
`unit`	string	No	Unit of measure (e.g. `kg`, `piece`)
`is_active`	boolean	No	Whether the product is sellable
`reorder_level`	number	No	Low-stock threshold
`image_urls`	string[]	No	Image URLs
`store_ids`	uuid[]	No	Stores to stock the product in


{
  "name": "Jollof Rice",
  "price": 2500,
  "quantity": 40,
  "sku": "JR-001",
  "unit": "plate"
}

Response 201 Created - the created (or updated) product.

Pass an Idempotency-Key header (or idempotency_key field) so retries don’t create duplicate products.

Update a product


PATCH /v1/products/:id

Send only the fields you want to change: name, price, description, sku, barcode, category_id, cost_price, unit, is_active, reorder_level, image_urls.

Stock quantity is managed through inventory operations, not this endpoint - PATCH changes catalog attributes only.


{ "price": 2700, "is_active": true }

Response 200 OK - the updated product.