Products API

Push Products

POST /api/v1/integration/products

Bulk upsert products. Optionally links to previously synced suppliers via supplierExternalId.

Required scope: integration:products:write

Request Body

{
  "products": [
    {
      "externalId": "string (required)",
      "name": "string (required)",
      "category": "string",
      "country": "string (ISO country code)",
      "hsCode": "string (HS/tariff code)",
      "unit": "string",
      "code": "string (product number)",
      "supplierExternalId": "string (links to a synced supplier)"
    }
  ]
}

Limits

Maximum 500 products per request

Response

{
  "success": true,
  "created": 1,
  "updated": 0,
  "errors": [],
  "records": [
    { "externalId": "ITEM-001", "internalId": "clx...", "status": "CREATED" }
  ]
}

Field Reference

Field	Type	Required	Description
`externalId`	string	✅	Unique ID in your system
`name`	string	✅	Product name
`category`	string		Product category
`country`	string		Country of origin (ISO code)
`hsCode`	string		HS/tariff code for EUDR classification
`unit`	string		Unit of measure (kg, pcs, etc.)
`code`	string		Product number or SKU
`supplierExternalId`	string		Links to a supplier by its external ID

List Synced Products

GET /api/v1/integration/products

Required scope: integration:products:read

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	50	Items per page (max 100)
`since`	string		ISO date filter

Response

{
  "entities": [
    {
      "externalId": "ITEM-001",
      "internalId": "clx...",
      "name": "Brazilian Hardwood Planks",
      "syncStatus": "SYNCED",
      "lastSyncedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 15,
  "page": 1,
  "limit": 50
}