Register the invoice of an order
Record the reference of the fiscal document (factura/boleta) your ERP or invoicing system emitted for the order. Registration is independent of the order lifecycle: it does not change status, paymentStatus, or fulfillmentStatus, and may happen before or after payment or fulfillment. An order split across several documents takes one call per document; every registered reference rides on the order’s invoices array under orders:read, and the order’s invoiceStatus flips to INVOICED on the first one. Repeating a number already registered on the order responds 409 ORDER_ALREADY_INVOICED — a retry receiving that 409 can treat that invoice as already registered. Cancelling an invoiced order keeps its references. Pass invoiceUrl to have the file ingested into our storage: the 200 confirms the registration only, and the file appears once the asynchronous download completes. A failed download never undoes the registration and is not reported back — the merchant can attach the file from the admin. Requires the invoices:write scope.
Autorizaciones
Public API key presented as Authorization: Bearer rq_live_….
Parámetros de ruta
Order UUID.
"0b2e9f5a-1c3d-4e6f-8a9b-0c1d2e3f4a5b"
Cuerpo
External document number as the issuer formats it (e.g. F001-00001234).
1 - 100Fiscal issuance date of the document (ISO-8601 with timezone). Must not be in the future. Optional — omit and only the registration time is stored.
Public http(s) URL of the invoice file (PDF or XML). We download a copy into our own storage — the URL itself is never stored or exposed. The download runs asynchronously after this response.
Respuesta
The updated order.
Order UUID. Stable primary key; use it for lookups.
Display code assigned at creation from the organization's configured prefix and padding (e.g. #1042, P001042). Never changes after creation.
Lifecycle status: PLACED or CANCELLED.
PLACED, CANCELLED Payment state: UNPAID, PARTIALLY_PAID, PAID, PENDING (a charge attempt is open and resolving on its own), or ERROR (it never resolved; the merchant has to check the gateway).
UNPAID, PARTIALLY_PAID, PAID, PENDING, ERROR Preparation state, forward-only: UNFULFILLED → IN_PROGRESS → FULFILLED → DELIVERED.
UNFULFILLED, IN_PROGRESS, FULFILLED, DELIVERED Channel the order came from (currently always STOREFRONT).
STOREFRONT, PURCHASE_ORDER, MIGRATION When the order record was created.
"2026-06-30T14:12:00Z"
When the order was last modified. Use as the watermark for incremental sync.
"2026-06-30T14:12:00Z"
When the customer placed the order. Set by every placement path; null only on legacy rows.
"2026-06-30T14:12:00Z"
When the order was cancelled. Null unless status is CANCELLED.
"2026-06-30T14:12:00Z"
The buyer had no session at placement. This is the guest signal — buyer.customerId is set either way.
Free-text note the buyer wrote for the whole order at checkout. Distinct from shippingAddress.instructions (about the address) and cancellation.note (written by an operator). Null when none was given.
ISO 4217 currency code for all money fields.
"USD"
Net of everything (goods + shipping), post-discount. Equals total − taxTotal. subtotal + taxTotal = total in both tax modes.
"1234.56"
Aggregate of all taxes on the order.
"1234.56"
Shipping charge as the buyer saw it. Informational — already reflected in subtotal/total; not an addend.
"1234.56"
Goods + order discount as the buyer saw it. Informational; not an addend. Shipping discounts surface as a reduced shippingTotal plus a SHIPPING promotion.
"1234.56"
Amount owed: subtotal + taxTotal.
"1234.56"
Price list that governed this order's prices, resolved from the buyer's commercial policy at placement and snapshotted. Null when no policy applied to the order.
Where the order is fulfilled from, whatever its shipping type: the point the buyer collects at on PICKUP, the dispatch origin on DELIVERY. Null when placement carried no fulfillment selection.
The shipping method snapshot. type is the delivery/pickup discriminator.
Who placed the order, as they identified themselves at checkout.
Invoicing details the buyer requested. Null when no invoice was requested. Distinct from buyer.documentType / buyer.documentNumber, which are the buyer's own ID.
Delivery address snapshot. Null on PICKUP orders.
The method the buyer chose and what has been received against paymentStatus. Per-attempt gateway facts live in transactions.
Why and by whom the order was cancelled. Null unless status is CANCELLED.
Shipments of the order — carrier, tracking and the timestamps behind fulfillmentStatus. Empty while the order is UNFULFILLED; currently at most one element, since an order is prepared and dispatched as a single shipment.
Whether the order carries at least one registered fiscal document. Independent of status, paymentStatus, and fulfillmentStatus.
NOT_INVOICED, INVOICED Fiscal document references registered for the order, oldest first. Empty until invoiced; an order split across several facturas carries one element per document.
Applied promotions on the order, including SHIPPING-class ones.
Line items in the order, in stable display order. Array position is the line's order — there is no separate position field.
Every gateway charge attempt on this order, oldest first — declines and errors included. Empty for orders paid without a gateway.