TracePass
Get started
Products

Create a product

Create a product. The category template is resolved automatically from the `category` slug — must match a seeded category (e.g. `batteries`, `textiles`, `jewelry`). Model strings are unique within the workspace.

POST/api/v1/products
Download OpenAPI 3.1
POST/api/v1/products

Create a product

Create a product. The category template is resolved automatically from the `category` slug — must match a seeded category (e.g. `batteries`, `textiles`, `jewelry`). Model strings are unique within the workspace.

Counts as one v1 write. Honours `Idempotency-Key`. Optional `imageUrls` accepts an array of public HTTPS URLs (max 20 per product, max 2048 chars each); the customer's CDN remains canonical and TracePass doesn't re-host them. Use the multipart upload endpoint when you don't have CDN URLs ready.

Headers

  • Authorizationrequired

    string

    `Bearer <api-key>`.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4 per logical operation.

Body fields

  • namerequired

    string (1-200)

    Display name.

    e.g. Li-Ion 48V Battery Pack

  • modelrequired

    string (1-100)

    Model identifier. Must be unique within your workspace.

    e.g. BP-48V-100

  • categoryrequired

    string

    Seeded category slug — `batteries`, `textiles`, `jewelry`, `electronics`, `furniture`, `chemicals`, `packaging`, `toys`, `fmcg`, `tyres`, `iron-steel`, `construction`.

    e.g. batteries

  • description

    string (≤ 2000)

    Optional description.

  • defaultFieldValues

    object

    Seed values applied to every passport created from this product. Each entry's key must exist on the category template.

  • imageUrls

    string[] (max 20)

    Public HTTPS image URLs. Replaces the existing array on PATCH; appends on the multipart upload endpoint.

  • sourceLocale

    string (ISO 639-1)

    Locale of `name` and `description`. Defaults to your workspace's `defaultSourceLocale` (typically `en`).

Request

curl -sS https://app.tracepass.eu/api/v1/products \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Li-Ion 48V Battery Pack",
    "model": "BP-48V-100",
    "category": "batteries",
    "defaultFieldValues": {
      "battery_chemistry": "lithium-ion",
      "nominal_voltage": 48
    }
  }'

Response

{
  "_id": "6650a1b2c3d4e5f6a7b8c9d0",
  "name": "Li-Ion 48V Battery Pack",
  "model": "BP-48V-100",
  "category": "batteries",
  "templateId": "6650a1b2c3d4e5f6a7b8c9d1",
  "defaultFieldValues": { "battery_chemistry": "lithium-ion", "nominal_voltage": 48 },
  "passportCount": 0,
  "status": "active",
  "createdAt": "2026-05-09T10:00:00.000Z"
}

Related endpoints