Orders

Read and filter orders — the commercial record that groups the payment attempts behind every purchase, checkout, renewal, and setup flow.

An order is the commercial record of a single purchase intent. It is the durable, human-readable anchor that groups one or more payment attempts — the transactions Tokeflow orchestrates across your connected providers — under a stable identifier you can show on a receipt, reconcile against your ledger, or look up in support.

You never create an order directly. Tokeflow opens one automatically the moment a charge is initiated, then keeps its status in lockstep with the underlying transaction as it moves through your routing rules.

Tokeflow is payment orchestration, not a payment processor. An order records and standardizes the commercial event; the connected provider authorizes, captures, and settles the funds. Tokeflow never moves or settles money.

How orders are created

Every charge path produces exactly one order, distinguished by its order_type:

`order_type`	Created when	Typical `recurrence`
`api`	You call `POST /transactions` directly.	`none`
`checkout`	A hosted or embedded Checkout session is paid.	`none` or `initial`
`renewal`	A subscription bills a new cycle.	`subsequent`
`trial_setup`	A trial subscription is provisioned and its first/setup charge runs.	`initial`
`card_setup`	A card is verified and tokenized without an immediate sale (a zero/auth-only verification).	`none`

The order's status is derived from the transaction it groups. As the transaction is authorized, refunded, or charged back, Tokeflow advances the order status and appends an entry to its status history.

Today an order groups a single primary payment transaction. The data model is built to group multiple attempts (for example, a cascade fallback across providers) under one order, so always treat the order — not a single transaction — as the unit of reconciliation.

The order object

{
  "id": "ord_9f8e7d6c5b4a3210",
  "merchant_id": "mrc_8a1b2c3d4e5f",
  "organization_id": "org_1a2b3c4d5e6f",
  "customer_id": "cust_kj3x8rabc123",
  "external_order_id": "shop_order_456",
  "checkout_session_id": "cks_a1b2c3d4e5",
  "order_type": "checkout",
  "recurrence": "initial",
  "total_amount": 9900,
  "currency": "BRL",
  "status": "authorized",
  "metadata": {
    "cart_id": "cart_7788",
    "campaign": "winter_sale"
  },
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:04.000Z",
  "items": [
    {
      "id": "f3a1c2d4-1111-4a2b-9c3d-5e6f7a8b9c0d",
      "product_id": "prd_a1b2c3d4e5",
      "offer_id": "ofr_a1b2c3d4e5",
      "product_name": "Premium Plan",
      "offer_name": "Annual Discount",
      "billing_cycle": "yearly",
      "cycle_limit": 12,
      "is_first_charge": true,
      "quantity": 1,
      "unit_amount": 9900,
      "total_amount": 9900,
      "currency": "BRL",
      "installments": 1,
      "created_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "status_history": [
    {
      "from_status": null,
      "to_status": "pending",
      "triggered_by": "api",
      "created_at": "2026-01-15T12:30:00.000Z"
    },
    {
      "from_status": "pending",
      "to_status": "authorized",
      "triggered_by": "psp_webhook",
      "created_at": "2026-01-15T12:30:04.000Z"
    }
  ]
}

Fields

Field	Type	Description
`id`	string	Unique order identifier, prefixed `ord_`.
`merchant_id`	string	Merchant that owns the order (`mrc_`).
`organization_id`	string	Organization the merchant belongs to (`org_`).
`customer_id`	string	Customer the order belongs to (`cust_`).
`external_order_id`	string \| null	Your own order reference, echoed back for reconciliation. `null` when not supplied.
`checkout_session_id`	string \| null	Source checkout session (`cks_`) for `checkout` / `trial_setup` orders; `null` otherwise.
`order_type`	string	How the order originated. One of `api`, `checkout`, `renewal`, `trial_setup`, `card_setup`.
`recurrence`	string	Position in a recurring series: `none`, `initial`, `subsequent`, or `unscheduled`.
`total_amount`	integer	Total in minor units (cents). `9900` = R$99.00.
`currency`	string	ISO 4217 currency code (e.g. `BRL`).
`status`	string	Current order status. See Order status.
`metadata`	object \| null	Arbitrary key/value data you attach at creation.
`created_at`	string	ISO 8601 UTC creation timestamp.
`updated_at`	string	ISO 8601 UTC last-update timestamp.
`items`	array	Line items snapshotted at order creation. Returned by the single-order endpoint; empty/omitted in list results.
`status_history`	array	Ordered status transitions. Returned by the single-order endpoint.

List results (GET /orders) return order headers — the top-level fields above. The items and status_history arrays are populated only when you retrieve a single order by ID.

Order item fields

Each line item is an immutable snapshot of the product and offer at the time the order was created, so historical orders stay accurate even after you change your catalog.

Field	Type	Description
`id`	string	Line item identifier (UUID).
`product_id`	string \| null	Product reference (`prd_`).
`offer_id`	string \| null	Offer reference (`ofr_`).
`product_name`	string	Snapshot of the product name.
`offer_name`	string \| null	Snapshot of the offer name.
`billing_cycle`	string \| null	Snapshot of the offer billing cycle (e.g. `monthly`, `yearly`). `null` for one-time items.
`cycle_limit`	integer \| null	Snapshot of the offer cycle limit, if any.
`is_first_charge`	boolean	`true` when first-charge / setup pricing was applied.
`quantity`	integer	Quantity purchased.
`unit_amount`	integer	Unit price in minor units (reflects first-charge pricing when `is_first_charge` is `true`).
`total_amount`	integer	Line total in minor units (`unit_amount` × `quantity`).
`currency`	string	ISO 4217 currency code.
`installments`	integer \| null	Installments chosen at checkout. `null` or `1` means a single charge.
`created_at`	string	ISO 8601 UTC timestamp.

Status history fields

Field	Type	Description
`from_status`	string \| null	Status before the transition. `null` for the first entry.
`to_status`	string	Status after the transition.
`triggered_by`	string	What drove the change (e.g. `api`, `system`, `psp_webhook`).
`created_at`	string	ISO 8601 UTC timestamp of the transition.

Order status

Status	Meaning
`pending`	Order created; the charge has not completed yet.
`pre_authorized`	An authorization hold is in place, awaiting capture.
`authorized`	The charge succeeded (authorized/captured).
`failed`	The charge did not succeed. Terminal.
`canceled`	The order was canceled before completion. Terminal.
`refund_pending`	A refund has been requested and is being processed.
`partially_refunded`	Part of the amount has been refunded.
`refunded`	The full amount has been refunded.
`charged_back`	A chargeback was recorded against the order.

Order status mirrors the underlying transaction's lifecycle. To inspect the payment-level detail behind a status — provider results, captures, voids — read the linked transaction and its refunds.

Endpoints

Base URL: https://api.tokeflow.com — all routes are under /api/v1.

Orders are read-only over the API. Authenticate with a server-side secret key (Authorization: Bearer sk_live_…). See Authentication for key anatomy and scopes. Both endpoints require the orders:read scope.

Secret keys (sk_*) are server-side only — never expose them in browser or mobile code.

GET`/api/v1/orders`

Auth: Organization key (with merchant_id) or Merchant key.

Returns a paginated list of order headers for the resolved merchant, newest data first. A Merchant key infers its merchant automatically. An Organization key spans every merchant in the org, so it must pass merchant_id to scope the query.

Query parameters

Field	Type	Required	Description
`merchant_id`	string	Conditional	Required for Organization keys; omit for Merchant keys (inferred).
`status`	string	No	Filter by order status. Repeat the parameter or pass a comma-separated list for multiple values (e.g. `status=authorized,refunded`).
`customer_id`	string	No	Return only orders for this customer (`cust_`).
`external_order_id`	string	No	Match your own order reference.
`order_type`	string	No	One of `api`, `checkout`, `renewal`, `trial_setup`, `card_setup`.
`currency`	string	No	ISO 4217 currency code (e.g. `BRL`).
`date_from`	string	No	Include orders created on or after this ISO 8601 timestamp.
`date_to`	string	No	Include orders created on or before this ISO 8601 timestamp.
`page`	integer	No	Page number, 1-indexed. Default `1`.
`limit`	integer	No	Items per page. Default `20`, max `100`.

Request

curl -G "https://api.tokeflow.com/api/v1/orders" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=authorized,refunded" \
  --data-urlencode "order_type=checkout" \
  --data-urlencode "currency=BRL" \
  --data-urlencode "date_from=2026-01-01T00:00:00Z" \
  --data-urlencode "date_to=2026-01-31T23:59:59Z"

With an Organization key, add merchant_id to the query string to scope the list to one merchant: GET /api/v1/orders?merchant_id=mrc_8a1b2c3d4e5f&status=authorized

Response `200 OK`

{
  "success": true,
  "data": [
    {
      "id": "ord_9f8e7d6c5b4a3210",
      "merchant_id": "mrc_8a1b2c3d4e5f",
      "organization_id": "org_1a2b3c4d5e6f",
      "customer_id": "cust_kj3x8rabc123",
      "external_order_id": "shop_order_456",
      "checkout_session_id": "cks_a1b2c3d4e5",
      "order_type": "checkout",
      "recurrence": "initial",
      "total_amount": 9900,
      "currency": "BRL",
      "status": "authorized",
      "metadata": { "cart_id": "cart_7788" },
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:04.000Z"
    },
    {
      "id": "ord_1122334455667788",
      "merchant_id": "mrc_8a1b2c3d4e5f",
      "organization_id": "org_1a2b3c4d5e6f",
      "customer_id": "cust_kj3x8rabc123",
      "external_order_id": null,
      "checkout_session_id": null,
      "order_type": "api",
      "recurrence": "none",
      "total_amount": 15000,
      "currency": "BRL",
      "status": "refunded",
      "metadata": null,
      "created_at": "2026-01-12T09:05:00.000Z",
      "updated_at": "2026-01-13T17:42:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 42,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a1b9d7e",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

GET`/api/v1/orders/:id`

Auth: Organization key (with merchant_id) or Merchant key.

Retrieves a single order with its items and status_history. The order is returned only if it belongs to the resolving merchant (and, for Organization keys, the specified merchant_id within your organization).

Path parameters

Field	Type	Required	Description
`id`	string	Yes	The order ID (`ord_`).

Query parameters

Field	Type	Required	Description
`merchant_id`	string	Conditional	Required for Organization keys; omit for Merchant keys.

Request

curl "https://api.tokeflow.com/api/v1/orders/ord_9f8e7d6c5b4a3210" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Response `200 OK`

{
  "success": true,
  "data": {
    "id": "ord_9f8e7d6c5b4a3210",
    "merchant_id": "mrc_8a1b2c3d4e5f",
    "organization_id": "org_1a2b3c4d5e6f",
    "customer_id": "cust_kj3x8rabc123",
    "external_order_id": "shop_order_456",
    "checkout_session_id": "cks_a1b2c3d4e5",
    "order_type": "checkout",
    "recurrence": "initial",
    "total_amount": 9900,
    "currency": "BRL",
    "status": "authorized",
    "metadata": { "cart_id": "cart_7788", "campaign": "winter_sale" },
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:04.000Z",
    "items": [
      {
        "id": "f3a1c2d4-1111-4a2b-9c3d-5e6f7a8b9c0d",
        "product_id": "prd_a1b2c3d4e5",
        "offer_id": "ofr_a1b2c3d4e5",
        "product_name": "Premium Plan",
        "offer_name": "Annual Discount",
        "billing_cycle": "yearly",
        "cycle_limit": 12,
        "is_first_charge": true,
        "quantity": 1,
        "unit_amount": 9900,
        "total_amount": 9900,
        "currency": "BRL",
        "installments": 1,
        "created_at": "2026-01-15T12:30:00.000Z"
      }
    ],
    "status_history": [
      {
        "from_status": null,
        "to_status": "pending",
        "triggered_by": "api",
        "created_at": "2026-01-15T12:30:00.000Z"
      },
      {
        "from_status": "pending",
        "to_status": "authorized",
        "triggered_by": "psp_webhook",
        "created_at": "2026-01-15T12:30:04.000Z"
      }
    ]
  },
  "request_id": "req_7b2d1e0c8f6a",
  "timestamp": "2026-01-15T12:30:05.000Z"
}

Response `404 Not Found`

Returned when the order does not exist or does not belong to the resolved merchant.

{
  "error": {
    "type": "not_found_error",
    "code": "ORDER_NOT_FOUND",
    "message": "Order ord_9f8e7d6c5b4a3210 not found or does not belong to your merchant",
    "details": {},
    "request_id": "req_3c9a7f2b1d8e",
    "timestamp": "2026-01-15T12:31:00.000Z"
  }
}

Errors

Orders use the standard error envelope. Common cases:

HTTP	`type`	When
401	`authentication_error`	Missing or invalid API key.
403	`authorization_error`	Key lacks the `orders:read` scope, or an Organization key omitted `merchant_id`.
404	`not_found_error`	Order not found, or not owned by the resolved merchant.
429	`rate_limit_error`	Rate limit exceeded (default 100 requests / 60s per key). Back off and retry.

Transactions — the payment attempts an order groups, and where refunds live.
Checkout — sessions that create checkout orders.
Subscriptions — the source of renewal and trial_setup orders.
Authentication — key types, scopes, and the merchant_id rule for Organization keys.

Orders

GET/api/v1/orders

GET/api/v1/orders/:id

On this page

GET`/api/v1/orders`

GET`/api/v1/orders/:id`