Order object

Amounts are decimal strings

All monetary amounts in Orders are represented as decimal strings (for example "15.00" or "0.000001"). Do not use floating-point numbers.

Decimal precision depends on the currency/asset. For details, see Amounts and currency conversion.

Order fields

Field	Type	Description
`id`	`string`	Unique order identifier (e.g., `ord_...`).
`external_reference_id`	`string`	Merchant-provided identifier to correlate Orbi orders with your internal system.
`merchant_id`	`string`	Merchant identifier that owns the order.
`status`	`string`	Current order status. See Order lifecycle for details.
`items`	`Item[]`	Line items included in the order.
`payments`	`EmbeddedPayment[]`	Payments associated with the order (may be empty while awaiting payment).
`total_amount`	`string`	Total amount for the order, derived from `items` (including modifiers).
`remaining_amount`	`string`	Amount still required to complete the order.
`currency`	`string`	Order currency (ISO 4217 for fiat, or asset code for crypto).
`rates`	`Record<string, string>`	Reference rates used for conversions (when applicable).
`capabilities`	`Capabilities`	Behavior rules for the order (cancel/update, partial payments, overpayments, etc.).
`deposit_instructions`	`DepositInstructions[]`	Rail-specific instructions required to complete payment.
`payment_reference`	`string?`	Optional payment reference used for lookup and reconciliation.
`metadata`	`Record<string, string>?`	Merchant-defined structured metadata.
`expiration_date`	`string?`	ISO-8601 timestamp when the order expires (if configured).
`created_at`	`string?`	ISO-8601 creation timestamp.
`updated_at`	`string?`	ISO-8601 last update timestamp.

Items and modifiers

Orders are built from line items. Each item can optionally include modifiers (add-ons or customizations).

Item

Field	Type	Description
`name`	`string`	Item name displayed to the customer.
`quantity`	`number`	Quantity of the item.
`unit_price`	`string`	Unit price as a decimal string.
`currency`	`string`	Currency/asset code for the item price.
`modifiers`	`Modifier[]?`	Optional list of item modifiers.

Modifier

Field	Type	Description
`name`	`string`	Modifier name.
`quantity`	`number`	Quantity of the modifier.
`unit_price`	`string`	Modifier unit price as a decimal string.
`currency`	`string`	Currency/asset code for the modifier price.

Note
The Order total_amount is derived from the items and their modifiers. For rounding rules and precision requirements, see Amounts and currency conversion.

Payments (embedded)

The payments array contains payments applied and associated with the order.

Field	Type	Description
`id`	`string`	Payment identifier (e.g., `pay_...`).
`payment_rail`	`string`	Payment rail used for this payment (for example `orbi_pay` or `crypto_deposit`).
`provider_id`	`string`	Provider-side identifier (for example an on-chain transaction hash or provider reference).
`amount`	`string`	Amount received for this payment as a decimal string.
`currency`	`string`	Currency/asset code of the payment.
`metadata`	`Record<string, string>?`	Optional provider metadata.
`created_at`	`string`	ISO-8601 timestamp when the payment was recorded.

Capabilities

Capabilities define what actions are allowed on an order and how payments behave.

Field	Type	Description
`can_cancel`	`boolean`	Whether the merchant can cancel the order via API or dashboard.
`can_update`	`boolean`	Whether the merchant can update the order after creation. (deprecated)
`can_overpay`	`boolean`	Whether the customer is allowed to pay more than the required amount.
`partial_payments`	`boolean`	Whether multiple payments can contribute to the same order.
`express_checkout`	`boolean`	Whether the order supports express checkout flows.
`expiration_auto_renewal`	`boolean`	Whether the order can be automatically renewed after expiration.

Deposit instructions

Deposit instructions describe how the customer should complete payment for an order. The structure of details depends on the selected rail.

Field	Type	Description
`method`	`string`	Payment method/rail used to complete the order.
`details`	`Record<string, any>?`	Rail-specific instructions (for example a deposit address and network for crypto deposits).