Orders

How an order is made#

1. Quote. Send one patient, one clinic if your key holds several, and the products and quantities. The response fixes the lines, the amount and a 30 minute expiry.
2. Order. Send the quote id. The quote is consumed in the same transaction that creates the order, so it can fund exactly one order.
3. Follow. Read one order, or list orders changed since a timestamp. There are no webhooks yet, so polling is the supported path.
4. Cancel, while it is still in review. A cancellation is accepted only before approval and only while unpaid.

Create a quote#

The Idempotency-Key header is required. Use a new key for each intended quote. A retry with the same key and the same body returns the first quote.

POST /api/partner/v1/quotes
Authorization: Bearer tfk_test_…
Idempotency-Key: quote-2026-11-07-0001
Content-Type: application/json

{
  "patient_id": "0b7c…",
  "clinic_id": "dd47…",
  "items": [
    { "product_id": "0999dff2-506e-4d0d-a17a-c4772d1be9d4", "quantity": 2 }
  ]
}

A product is orderable only when it is active for the clinic in the catalogue and has an agreed price. If any line is not, the whole quote is refused with 400 validation_failed and nothing is created. Check the catalogue first: a product with priced: false cannot be quoted.

The response is 201 for a new quote and 200 for a replay:

{
  "ok": true,
  "request_id": "…",
  "quote": {
    "id": "c0f1…",
    "status": "open",
    "currency": "USD",
    "patient_id": "0b7c…",
    "clinic_id": "dd47…",
    "subtotal_cents": 75200,
    "total_cents": 75200,
    "expires_at": "2026-11-07T15:30:00.000Z",
    "created_at": "2026-11-07T15:00:00.000Z",
    "order_id": null,
    "lines": [
      {
        "product_id": "0999dff2-506e-4d0d-a17a-c4772d1be9d4",
        "name": "*International - Semax Nasal Spray - 10mg, 15mL",
        "quantity": 2,
        "unit": "each",
        "unit_amount_cents": 37600,
        "line_amount_cents": 75200
      }
    ]
  },
  "idempotent": false
}

Place the order#

The body carries the quote id and nothing else. The quote already names the patient, the clinic, the lines and the amount, so this endpoint never re-prices.

POST /api/partner/v1/orders
Authorization: Bearer tfk_test_…
Idempotency-Key: order-2026-11-07-0001
Content-Type: application/json

{ "quote_id": "c0f1…" }

The response is 201 for a new order and 200 for a replay:

{
  "ok": true,
  "request_id": "…",
  "order": {
    "id": "8a3d…",
    "order_number": "TF-2026-00042",
    "status": "pending_approval",
    "origin": "partner",
    "patient_id": "0b7c…",
    "clinic_id": "dd47…",
    "quote_id": "c0f1…",
    "total_cents": 75200,
    "currency": "USD",
    "payment_status": "pending",
    "item_count": 1,
    "created_at": "2026-11-07T15:01:00.000Z",
    "updated_at": "2026-11-07T15:01:00.000Z",
    "sent_at": null,
    "shipped_at": null,
    "delivered_at": null,
    "tracking_number": null,
    "carrier": null,
    "ship_status": null,
    "pharmacy_name": null
  },
  "idempotent": false
}

Read an order#

The shell carries the number, status, origin, dates, totals, payment status, tracking and pharmacy. Add orders:read:clinical to receive the lines as well.

{
  "ok": true,
  "request_id": "…",
  "order": {
    "id": "8a3d…",
    "order_number": "TF-2026-00042",
    "status": "pending_approval",
    "origin": "partner",
    "patient_id": "0b7c…",
    "clinic_id": "dd47…",
    "quote_id": "c0f1…",
    "total_cents": 75200,
    "currency": "USD",
    "payment_status": "pending",
    "item_count": 1,
    "created_at": "2026-11-07T15:01:00.000Z",
    "updated_at": "2026-11-07T15:01:00.000Z",
    "sent_at": null,
    "shipped_at": null,
    "delivered_at": null,
    "tracking_number": null,
    "carrier": null,
    "ship_status": null,
    "pharmacy_name": null,
    "items": [
      {
        "id": "…",
        "product_id": "0999dff2-506e-4d0d-a17a-c4772d1be9d4",
        "medication_name": "*International - Semax Nasal Spray - 10mg, 15mL",
        "dosage": "As directed",
        "quantity": 2,
        "unit": "each",
        "refills": 0,
        "days_supply": null,
        "line_type": "medication",
        "unit_amount_cents": 37600,
        "line_amount_cents": 75200
      }
    ]
  }
}

Without orders:read:clinical, the items key is absent, not an empty array.

A key can read every order in its clinics, including one a staff member created. Cancellation is narrower: only a partner-created order can be withdrawn through this API.

List and poll#

Newest first, keyset paginated. updated_since is the polling filter: send the last time you checked and receive everything that changed after it. The cursor is where the previous page ended.

{
  "ok": true,
  "request_id": "…",
  "orders": [ { "id": "8a3d…", "order_number": "TF-2026-00042", "status": "pending_approval", "…": "…" } ],
  "truncated": false,
  "next_cursor": null
}

The list is shell only, even when the key holds orders:read:clinical. Read one order to get its lines.

Cancel#

Accepted only for a partner-created order while it is draft or pending_approval and unpaid. After approval, after a payment, after a pharmacy has it, or for a staff-created order, the answer is 409 order_not_cancellable; contact the clinic.

{
  "ok": true,
  "request_id": "…",
  "order": {
    "id": "8a3d…",
    "order_number": "TF-2026-00042",
    "status": "cancelled",
    "already_cancelled": false
  }
}

Cancelling twice is 200 with already_cancelled: true. The event and audit rows are written once, for the transition.

Retries and idempotency#

Keys are 8 to 128 visible characters with no whitespace. A UUID, a request id or a date-stamped sequence all work. Use a new key for a new intention, not a new key for a retry of the same intention.

Prices and expiry#

A quote is valid for 30 minutes. The amount in the quote is the clinic-agreed amount from the catalogue, fixed at the moment the quote is created.

At order time the platform checks that every line is still active and still priced the same. If the price moved, the order is refused with 409 quote_price_changedrather than billing a different number. Create a new quote and show the new amount.

An expired quote returns 409 quote_expired. A quote that was already used returns 409 quote_consumed.

Order amounts are part of the order. orders:read carries the total, and orders:read:clinical carries the line breakdown. The catalogue's catalog:read:pricing gates the catalogue price, not an order.

Errors#

What is not returned#

• Patient name, email, phone or address. Use the patient endpoints and the PHI scope.
• The prescription sig, diagnosis codes, internal notes, override reasons and pharmacy cost. Those are clinical or commercial data the order API does not serve.
• Card data, Stripe ids and payment failure messages.
• Orders from a clinic the key does not hold.

Sandbox and production#

Orders are available in the sandbox now. Production is gated three ways: the key must carry the scope, the BAA and DPA must be signed and recorded, and an operator must enable orders for the account after the lawful-supply review. A production key without all three gets 403 orders_not_enabled.