Products

The workspace product catalog, shared by deals and customer payments: when a deal or payment carries a product_id, its title derives from the product name, and a deal created without an amount defaults to the product's price. The API mirrors the in-app catalog (Products) — same rows, same rules.

All endpoints require authentication; there is no extra plan feature (like contacts and tags, products sell on API access alone). Products cannot be deleted — archive with manual_status: "archived" so existing deals/payments keep resolving their attached product.

The product object

GET /api/v1/products

Standard list envelope (data/total/limit/offset; limit default 50, cap 500), newest first. Filters combine (AND):

curl "https://app.otok.io/api/v1/products?is_active=true&q=onboarding" \
  -H "Authorization: Bearer otok_live_abc123..."

GET /api/v1/products/:id

Returns the product, or 404 product_not_found (structured {"error": {"code", "message"}} envelope) for an unknown or cross-workspace id.

POST /api/v1/products — idempotent upsert

Request body

Upsert resolution

When external_id matches an existing product, that product's fields are updated instead of a new one being created, and the response carries duplicate: true. Both outcomes return 201 with the full product:

curl -X POST "https://app.otok.io/api/v1/products" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding package",
    "external_id": "prod-9",
    "sku": "ONB-1",
    "price": 249.9
  }'

Response 201:

{
  "id": "6f2a1b3c-4d5e-6071-8293-a4b5c6d7e8f9",
  "workspace_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "name": "Onboarding package",
  "sku": "ONB-1",
  "external_id": "prod-9",
  "description": null,
  "price": 249.9,
  "vat_mode": null,
  "vat_rate": null,
  "is_active": true,
  "created_by": null,
  "created_at": "2026-07-16T10:00:00.000Z",
  "updated_at": "2026-07-16T10:00:00.000Z",
  "duplicate": false
}

Errors

PATCH /api/v1/products/:id

Partial update — same fields as POST, all optional; only the fields present in the body change (a field you don't send is never nulled). Returns the updated product (no duplicate marker).

Archive instead of deleting:

curl -X PATCH "https://app.otok.io/api/v1/products/6f2a1b3c-..." \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"manual_status": "archived"}'

Notes

• Attachment rules (enforced on deals/payments, not here): only active products attach to new records; re-saving a record that already carries an inactive product never fails; deleting is impossible, so denormalized titles always keep resolving.
• The public API resolves product references on deal creation by product_id → sku → external_id.

Fixed pricing

With dynamic_pricing: false the product's price is the only price: a deal created without an amount defaults to it even when its cycle has a price of its own, setting a different price on one of the product's cycles is refused with 400 PRODUCT_PRICE_LOCKED, and a sale recorded at a different unit amount is refused with 400 SALE_PRICE_LOCKED. Turning it back on (true, the default) lets cycles and sales override the price again.

Scheduling

Dated products use automatic schedule status. Use manual_status: "archived" or "cancelled" to override it. For a dated product, is_active: false without an archive/cancel status returns 400 PRODUCT_STATUS_AUTOMATIC. Dates are validated together with existing values on PATCH; an end before the start returns 400 PRODUCT_DATES_INCOHERENT. Setting is_active: true without manual_status clears a previous override.

Use product cycles for multiple cohorts, runs or versions of a product.