Products API

Create, read, update, and delete products in your catalog.

Endpoints

GET

/products

products:read

Retrieve a paginated list of products. Supports filtering by status, category, and search.

GET

/products/:id

products:read

Retrieve a single product by its ID.

POST

/products

products:write

Create a new product in your catalog.

PUT

/products/:id

products:write

Update an existing product. Partial updates are supported.

DELETE

/products/:id

products:write

Soft-delete a product. It can be restored within 30 days.

Field Reference

Field	Type	Required	Description
id	string	No	Unique product identifier (read-only)
sku	string	Yes	Stock Keeping Unit
name	string	Yes	Product name
description	string	No	Product description (HTML allowed)
barcode	string	No	Primary product barcode (UPC/EAN)
brand	string	No	Product brand name
categoryId	string	No	Category identifier
unitPrice	integer	Yes	Price in cents (e.g. 1999 = $19.99)
normalPrice	integer	No	Normal / list price in cents (for showing discounts)
purchasePrice	integer	No	Purchase / cost price in cents
weight	string	No	Weight in grams
isActive	boolean	No	Whether the product is active / published (default: true)
stockTotal	integer	No	Total available stock across all warehouses (read-only)
images	string[]	No	Product image URLs
createdAt	datetime	No	ISO 8601 timestamp (read-only)
updatedAt	datetime	No	ISO 8601 timestamp (read-only)

Query Parameters (List)

Field	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 20, max: 100)

Example

List products with pagination

bash

curl "https://api.mercozy.com/api/v1/external/products?page=1&limit=10" \
  -H "X-API-Key: mk_live_your_key_here"

Create a product

bash

curl -X POST "https://api.mercozy.com/api/v1/external/products" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "WDG-001",
    "name": "Premium Widget",
    "unitPrice": 2999,
    "normalPrice": 3999,
    "brand": "Acme Corp",
    "isActive": true
  }'