Orders

E-commerce-grade orders attached to your workspace's contacts. An order carries line items, header money rollups, an append-only refund ledger, and a two-axis status model: financial_status (the money) and fulfillment_status (the goods), plus a separate cancellation stamp that touches neither axis. Order writes fire the workspace's order automations and registered order.* webhooks exactly as in-app writes do.

All endpoints require authentication. Orders cannot be deleted via the API, and there are no PATCH routes — after creation, status changes ride the action routes below, and field updates ride the idempotent re-POST (see upsert semantics).

Plan feature required: every route on this page requires the Orders feature on the workspace's plan, in addition to API access. Without it, all calls return 403 with error_code: "FEATURE_NOT_INCLUDED_IN_PLAN" — see feature-gated resource groups. The Orders feature is included on all current plans, so in practice this error appears only when the feature has been switched off for a specific workspace.

All POSTs return 201, including the action routes. Every write response returns the full order object — header, items, refunds, and joined contact identity (list rows omit items/refunds); the refunds route wraps it as { duplicate, order }.

The order object

Money is numeric. Order money fields (total, subtotal, unit_price, refund amount, …) serialize as JSON numbers, rounded to 2 decimals, in the order's charge currency — the same JSON-number serialization used by deals and payments.

Header fields:

Line item (items[], detail/write responses only, ordered by position):

Refund (refunds[], detail/write responses only, ordered by refunded_at ascending):

Money math

Totals are computed server-side and are authoritative — client-sent totals are never trusted:

• Per line: line_total = round2(quantity × unit_price × (1 − discount_percent/100))
• subtotal = sum of the rounded line totals
• total = max(0, subtotal − discount_total + shipping_total + tax_total)

Rounding is 2-decimal, half-up.

Store provenance fields

number, store_connection_id, store_domain, external_order_id, and external_updated_at are populated only for orders synced from a connected e-commerce store (where store sync is available on the workspace) — for every order you create via the API or in the app they are always null. Store-synced orders are read-only through this API: the mutation routes reject them with 409 error_code: "STORE_SYNCED_READ_ONLY". Orders created via the API can never trigger that error.

GET /api/v1/orders

This route uses dedicated query parameters (not the generic filter) with the deals/payments pagination family (see where deals and payments differ) — but note the clamping difference on limit/offset below the table. There is no search parameter on this route.

Pagination clamping: unlike deals and payments (which return 400 on malformed paging), orders never rejects limit/offset values — a malformed or zero limit silently defaults to 25 and out-of-range values are clamped into 1–100; a malformed or negative offset silently defaults to 0.

Results are ordered by placed_at descending (not created_at).

curl -G "https://app.otok.io/api/v1/orders" \
  -H "Authorization: Bearer otok_live_abc123..." \
  --data-urlencode 'status=paid' \
  --data-urlencode 'placed_from=2026-07-01'

Response 200 — { data, total, limit, offset }; each row is the order object above with joined contact fields, without items/refunds.

GET /api/v1/orders/:id

The full order with items[] + refunds[] + joined contact identity.

• 200 — the order.
• 400 — non-UUID id.
• 404 — "Order not found" (an unknown id and another workspace's order are indistinguishable).

POST /api/v1/orders

Creates an order — or, when external_reference matches an existing order, updates its mutable fields (idempotent upsert; see below). Response 201 in both cases with the full order object (items + refunds + contact join).

No duplicate flag. Unlike POST /v1/contacts / /v1/deals / /v1/payments / /v1/bookings, the order create response carries no top-level duplicate boolean — a fresh create and an external_reference match return the same full-order body. To distinguish the two, compare the response's created_at against your request time, or pre-check with GET /v1/orders?external_reference=….

Request body

Item shape

A product reference is resolved in order: product_id → product_sku → product_external_id (first provided wins).

Contact resolution

Shared with the contacts upsert (same as deals and payments):

• contact_id wins when present (validated for workspace membership → 404 "Contact not found").
• Otherwise phone/email are upserted exactly like POST /v1/contacts: normalized phone match wins, email is the fallback; a match updates that contact, no match creates one.
• Phone resolving to one contact and email to a different one → 409 CONTACT_MERGE_REQUIRED with a merge_request_id (a merge request is parked; the order is not created — see contacts).
• Neither contact_id nor phone/email → 400 "Provide contact_id, or a phone/email to attach the order to a contact".

Idempotent upsert via external_reference

external_reference is unique per workspace. A repeat POST with a matching value updates that order instead of creating a duplicate — this is race-safe: a concurrent create that loses the uniqueness race is automatically retried as an update against the winner.

• Always updated (when present in the body): note, coupon_codes, placed_at, deal_id.
• Money fields (items, currency, discount_total, shipping_total, tax_total) apply only while the order is still pending — once paid, money is locked and repeat POSTs silently skip these fields; corrections flow through refunds/cancel.
• financial_status is never changed on a match — an exact replay of a created-as-paid POST is a clean no-op; status moves ride the mark-paid/cancel/refund endpoints. A repeat POST can never resurrect a cancelled order.
• The contact is never re-pointed on a match (unlike deals, where a repeat POST re-applies the resolved contact). Contact resolution still runs first, so a repeat POST must still carry contact_id or phone/email — and phone/email upsert side effects still run on the contact itself.
• Response: 201 with the full updated order (no duplicate marker — see above).

A direct-conflict 409 (error_code: "ORDER_REFERENCE_EXISTS", message "An order with this external_reference already exists.") exists in the contract but is resolved automatically by the retry-as-update path — callers should not normally observe it.

Example

curl -X POST "https://app.otok.io/api/v1/orders" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+972501234567",
    "email": "dana@example.com",
    "name": "Dana Levi",
    "currency": "ILS",
    "shipping_total": 20,
    "items": [
      { "product_sku": "WGT-1", "quantity": 2, "unit_price": 120 },
      { "title": "Gift wrap", "unit_price": 100 }
    ],
    "coupon_codes": ["SUMMER10"],
    "external_reference": "shop-order-1042"
  }'

Response 201:

{
  "id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "workspace_id": "…",
  "contact_id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c",
  "contact_name": "Dana Levi",
  "contact_phone": "+972501234567",
  "contact_email": "dana@example.com",
  "order_number": 1042,
  "number": null,
  "platform": "api",
  "source": "api",
  "store_connection_id": null,
  "store_domain": null,
  "external_order_id": null,
  "external_reference": "shop-order-1042",
  "deal_id": null,
  "financial_status": "pending",
  "fulfillment_status": "unfulfilled",
  "currency": "ILS",
  "total": 360,
  "subtotal": 340,
  "discount_total": 0,
  "shipping_total": 20,
  "tax_total": 0,
  "refunded_total": 0,
  "item_count": 3,
  "first_item_name": "Widget",
  "coupon_codes": ["SUMMER10"],
  "placed_at": "2026-07-14T10:00:00.000Z",
  "paid_at": null,
  "cancelled_at": null,
  "refunded_at": null,
  "external_updated_at": null,
  "payment_reference": null,
  "payment_synced_at": null,
  "note": null,
  "metadata": null,
  "created_by": null,
  "created_at": "2026-07-14T10:00:00.000Z",
  "updated_at": "2026-07-14T10:00:00.000Z",
  "items": [
    {
      "id": "11a2b3c4-…",
      "workspace_id": "…",
      "order_id": "0a1b2c3d-…",
      "position": 0,
      "product_id": "77e8f9a0-…",
      "external_product_id": null,
      "title": "Widget",
      "sku": "WGT-1",
      "quantity": 2,
      "unit_price": 120,
      "discount_percent": null,
      "line_total": 240,
      "created_at": "2026-07-14T10:00:00.000Z"
    },
    {
      "id": "22b3c4d5-…",
      "workspace_id": "…",
      "order_id": "0a1b2c3d-…",
      "position": 1,
      "product_id": null,
      "external_product_id": null,
      "title": "Gift wrap",
      "sku": null,
      "quantity": 1,
      "unit_price": 100,
      "discount_percent": null,
      "line_total": 100,
      "created_at": "2026-07-14T10:00:00.000Z"
    }
  ],
  "refunds": []
}

Errors

(error_code values appear as an error_code field on the response body.)

Side effects

Creation fires the workspace's order-created automations (plus order-paid when created as paid), writes the contact's activity timeline, and emits registered order.created (and order.paid) webhooks. A paid create also records a completed payment for the full order total, in the order's currency, on the contact's payment history. API writes are attributed to source api with no acting user.

POST /api/v1/orders/:id/refunds

Appends to the order's refund ledger, rolls the financial status to partially_refunded/refunded, mirrors the refund into the recorded payment, and fires the order-refunded automations + the order.refunded webhook.

Request body

The example continues the order created above, assuming it was first marked paid — refunding a never-paid order returns 400 ORDER_NEVER_PAID.

curl -X POST "https://app.otok.io/api/v1/orders/0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9/refunds" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50, "external_refund_id": "r-1", "reason": "damaged" }'

Response 201

{
  "duplicate": false,
  "order": {
    "id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "financial_status": "partially_refunded",
    "refunded_total": 50,
    "refunded_at": "2026-07-15T09:30:00.000Z",
    "…": "…full order object with items + refunds…",
    "refunds": [
      {
        "id": "33c4d5e6-…",
        "workspace_id": "…",
        "order_id": "0a1b2c3d-…",
        "external_refund_id": "r-1",
        "amount": 50,
        "currency": "ILS",
        "reason": "damaged",
        "refunded_at": "2026-07-15T09:30:00.000Z",
        "created_at": "2026-07-15T09:30:00.000Z"
      }
    ]
  }
}

duplicate: true means the external_refund_id was already recorded on this order — nothing was applied and the current order state is returned.

Semantics

• Refunds require the order to have ever been paid (paid_at set — a partially_paid order qualifies). Never-paid → 400 error_code: "ORDER_NEVER_PAID", message "Cannot refund an order that was never paid.".
• A refund that exhausts the remaining total moves financial_status to refunded; a partial one to partially_refunded. These states are reachable only through refunds — never through a status endpoint.
• Refunding a cancelled-but-paid order is allowed — cancellation doesn't touch the money axis.
• refunded_at is stamped on the order header with each refund.
• An amount exceeding the remaining total → 400 "Refund amount exceeds the order's remaining total (X)".

Errors

POST /api/v1/orders/:id/mark-paid

Moves the financial status to paid, records the payment (a completed one-time payment for the full order total, in the order's currency, on the contact's payment history) — or links onto an existing payment via payment_reference — and fires the order-paid automations + the order.paid webhook.

Request body (all optional)

curl -X POST "https://app.otok.io/api/v1/orders/0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9/mark-paid" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "payment_reference": "shop-charge-1042" }'

Response 201 — the full order object.

Transition rules

paid_at is stamped on first entry into a paid state and is historical — it is kept through later refund states.

Errors

The ORDER_PAYMENT_* codes validate payment_reference and are checked before linking:

POST /api/v1/orders/:id/cancel

Stamps cancelled_at and fires the order-cancelled automations + the order.cancelled webhook. No request body.

curl -X POST "https://app.otok.io/api/v1/orders/0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9/cancel" \
  -H "Authorization: Bearer otok_live_abc123..."

Response 201 — the full order object.

Semantics:

• Cancellation is a stamp, not a status: financial_status keeps its last state — recorded revenue stands until a refund is recorded. Cancel a paid order, then record refunds as money is actually returned.
• Idempotent: cancelling an already-cancelled order is a 201 no-op (no duplicate automations).
• A cancelled pending order can still be marked paid later — the cancellation stamp is workflow state on the fulfillment side and does not block later payment transitions.