Order
The Order entity in Payments.
An Order is the receipt-level record of a checkout: it ties a Customer, a Payment Instrument, the line items they purchased, the totals, and the resulting Transfer (the actual money movement) into a single object you can hand to your fulfillment, accounting, or analytics systems. Anything that goes through client.checkout(...), an Embedded Checkout session, or a Payment Link produces an Order. Direct createTransfer calls do not — those are bare money movements without line-item context.
Lifecycle
- Created — emitted when a checkout flow runs successfully. The Order is created together with its child Transfer; both share the same
merchant_id. - Settled — once the underlying Transfer's
statebecomesSUCCEEDED, the Order is the durable record you reconcile against. Thetransferfield on the Order embeds the Transfer object. - Refunded — when you call
client.createRefund(transferId, { refund_amount })against the Order's Transfer, the reversal links back to the original Transfer (and therefore the Order). Refunds do not change the Order itself. - Disputed — if the buyer charges back, a
dispute.createdwebhook fires. The Dispute references the Transfer; you can resolve back to the Order viatransfer.id.
Orders are immutable except for tags. Use client.updateOrderTags(orderId, tags) to add internal references (fulfillment ID, shipment number, etc.).
Relationships
Each Order has one Customer (identity), one Payment Instrument (payment_instrument), and at most one Transfer (transfer, may be null for orders that fail before authorization). Orders contain purchase_items which reference your Products and Prices by ID. Orders may carry a payment_link_id if they originated from a Payment Link.
Fields that matter
id,order_number(string) — the canonical ID and a human-friendly receipt number safe to show buyers.subtotal_cents,tax_amount_cents,total_cents(number) — amounts in the smallest currency unit.total_centsis what the buyer was charged.currency(string) — ISO-4217 code.transfer(TransferData | null) — the embedded Transfer.transfer.statetells you whether the money actually moved.purchase_items(PurchaseItemData[]) — line items with quantity, price, and product snapshot (name + image at time of sale).buyer_details,shipping_address,billing_address— what the buyer entered at checkout. Use these for fulfillment.tags(Record<string, unknown>) — your own metadata. Mutable.