Products API

Overview

The Products API provides full CRUD operations for your product catalog. All endpoints require the products:read or products:write scope.

Endpoints

List Products

GET /api/products

Query Parameters:

Parameter	Type	Description
limit	integer	Results per page (default: 50, max: 200)
cursor	string	Pagination cursor from previous response
status	string	Filter by status: `active`, `inactive`, `draft`, `archived`
marketplace	string	Filter to products with listings on a specific marketplace
search	string	Full-text search across title, SKU, and GTIN
sort	string	Sort field: `sku`, `title`, `created_at`, `updated_at`
order	string	`asc` or `desc` (default: `desc`)

Example Response:

{
  "data": [
    {
      "id": "prod_01HXK9MZPQ3B8C7D2E5F6G",
      "sku": "SKU-001",
      "title": "Blue Widget 500ml",
      "description": "Premium blue widget in 500ml size",
      "status": "active",
      "gtin": "5901234123457",
      "cost_price": 4.99,
      "weight_kg": 0.35,
      "images": ["https://cdn.example.com/sku-001-main.jpg"],
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-03-12T14:32:01.000Z"
    }
  ],
  "meta": {"total": 1248, "page": 1, "limit": 50, "nextCursor": "cursor_abc123"}
}

Get Product

GET /api/products/:sku

Returns a single product by SKU, including all marketplace listings.

Example Response:

{
  "data": {
    "id": "prod_01HXK9MZPQ3B8C7D2E5F6G",
    "sku": "SKU-001",
    "title": "Blue Widget 500ml",
    "status": "active",
    "gtin": "5901234123457",
    "cost_price": 4.99,
    "listings": [
      {
        "marketplace": "amazon_us",
        "external_id": "B01EXAMPLE",
        "price": 13.49,
        "quantity": 150,
        "status": "active",
        "last_synced_at": "2026-03-12T14:00:00.000Z"
      },
      {
        "marketplace": "shopify",
        "external_id": "9876543210",
        "price": 14.99,
        "quantity": 150,
        "status": "active",
        "last_synced_at": "2026-03-12T14:05:00.000Z"
      }
    ]
  }
}

Create Product

POST /api/products

Required scope: products:write

Request Body:

{
  "sku": "SKU-002",
  "title": "Red Widget 250ml",
  "description": "Compact red widget in 250ml size",
  "status": "draft",
  "gtin": "5901234123464",
  "cost_price": 2.99,
  "weight_kg": 0.18,
  "images": ["https://cdn.example.com/sku-002-main.jpg"]
}

Response: HTTP 201 with the created product.

Update Product

PATCH /api/products/:sku

Required scope: products:write

Partial update — only include fields you want to change.

Request Body:

{
  "title": "Red Widget 250ml (Updated)",
  "status": "active"
}

Response: HTTP 200 with the updated product.

Delete Product

DELETE /api/products/:sku

Required scope: products:write

Soft-deletes the product (sets status to archived). Products with open orders cannot be deleted.

Response: HTTP 204 No Content.

Bulk Update Products

POST /api/products/bulk

Required scope: products:write

Update multiple products in one request. Maximum 100 products per request.

Request Body:

{
  "updates": [
    {"sku": "SKU-001", "status": "active"},
    {"sku": "SKU-002", "status": "inactive"},
    {"sku": "SKU-003", "price": 19.99}
  ]
}

Response:

{
  "data": {
    "updated": 3,
    "failed": 0,
    "errors": []
  }
}

Sync Product to Marketplace

POST /api/products/:sku/sync

Required scope: products:write

Triggers an immediate push of this product's data to all connected marketplace listings.

Request Body (optional):

{
  "marketplaces": ["amazon_us", "shopify"]
}

Omit marketplaces to sync to all connected marketplaces.

Response: HTTP 202 Accepted with a job ID.

Error Codes

Code	HTTP Status	Description
`PRODUCT_NOT_FOUND`	404	SKU does not exist in this tenant
`DUPLICATE_SKU`	409	SKU already exists
`INVALID_GTIN`	422	GTIN/EAN/UPC format is invalid
`OPEN_ORDERS_EXIST`	409	Cannot delete product with open orders
`INSUFFICIENT_SCOPE`	403	API key lacks required scope

On this page