Skip to main content
POST
Register the invoice of an order

Autorizaciones

Authorization
string
header
requerido

Public API key presented as Authorization: Bearer rq_live_….

Parámetros de ruta

id
string<uuid>
requerido

Order UUID.

Ejemplo:

"0b2e9f5a-1c3d-4e6f-8a9b-0c1d2e3f4a5b"

Cuerpo

application/json
invoiceNumber
string
requerido

External document number as the issuer formats it (e.g. F001-00001234).

Required string length: 1 - 100
issuedAt
string<date-time>

Fiscal issuance date of the document (ISO-8601 with timezone). Must not be in the future. Optional — omit and only the registration time is stored.

invoiceUrl
string<uri>

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.

id
string
requerido

Order UUID. Stable primary key; use it for lookups.

code
string
requerido

Display code assigned at creation from the organization's configured prefix and padding (e.g. #1042, P001042). Never changes after creation.

status
enum<string>
requerido

Lifecycle status: PLACED or CANCELLED.

Opciones disponibles:
PLACED,
CANCELLED
paymentStatus
enum<string>
requerido

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).

Opciones disponibles:
UNPAID,
PARTIALLY_PAID,
PAID,
PENDING,
ERROR
fulfillmentStatus
enum<string>
requerido

Preparation state, forward-only: UNFULFILLEDIN_PROGRESSFULFILLEDDELIVERED.

Opciones disponibles:
UNFULFILLED,
IN_PROGRESS,
FULFILLED,
DELIVERED
source
enum<string>
requerido

Channel the order came from (currently always STOREFRONT).

Opciones disponibles:
STOREFRONT,
PURCHASE_ORDER,
MIGRATION
createdAt
string
requerido

When the order record was created.

Ejemplo:

"2026-06-30T14:12:00Z"

updatedAt
string
requerido

When the order was last modified. Use as the watermark for incremental sync.

Ejemplo:

"2026-06-30T14:12:00Z"

placedAt
string | null
requerido

When the customer placed the order. Set by every placement path; null only on legacy rows.

Ejemplo:

"2026-06-30T14:12:00Z"

cancelledAt
string | null
requerido

When the order was cancelled. Null unless status is CANCELLED.

Ejemplo:

"2026-06-30T14:12:00Z"

placedAsGuest
boolean
requerido

The buyer had no session at placement. This is the guest signal — buyer.customerId is set either way.

comment
string | null
requerido

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.

currencyCode
string
requerido

ISO 4217 currency code for all money fields.

Ejemplo:

"USD"

subtotal
string
requerido

Net of everything (goods + shipping), post-discount. Equals total − taxTotal. subtotal + taxTotal = total in both tax modes.

Ejemplo:

"1234.56"

taxTotal
string
requerido

Aggregate of all taxes on the order.

Ejemplo:

"1234.56"

shippingTotal
string
requerido

Shipping charge as the buyer saw it. Informational — already reflected in subtotal/total; not an addend.

Ejemplo:

"1234.56"

discountTotal
string
requerido

Goods + order discount as the buyer saw it. Informational; not an addend. Shipping discounts surface as a reduced shippingTotal plus a SHIPPING promotion.

Ejemplo:

"1234.56"

total
string
requerido

Amount owed: subtotal + taxTotal.

Ejemplo:

"1234.56"

priceList
object | null
requerido

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.

location
object | null
requerido

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.

shippingMethod
object
requerido

The shipping method snapshot. type is the delivery/pickup discriminator.

buyer
object
requerido

Who placed the order, as they identified themselves at checkout.

billing
object | null
requerido

Invoicing details the buyer requested. Null when no invoice was requested. Distinct from buyer.documentType / buyer.documentNumber, which are the buyer's own ID.

shippingAddress
object | null
requerido

Delivery address snapshot. Null on PICKUP orders.

payment
object
requerido

The method the buyer chose and what has been received against paymentStatus. Per-attempt gateway facts live in transactions.

cancellation
object | null
requerido

Why and by whom the order was cancelled. Null unless status is CANCELLED.

fulfillments
object[]
requerido

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.

invoiceStatus
enum<string>
requerido

Whether the order carries at least one registered fiscal document. Independent of status, paymentStatus, and fulfillmentStatus.

Opciones disponibles:
NOT_INVOICED,
INVOICED
invoices
object[]
requerido

Fiscal document references registered for the order, oldest first. Empty until invoiced; an order split across several facturas carries one element per document.

promotions
object[]
requerido

Applied promotions on the order, including SHIPPING-class ones.

items
object[]
requerido

Line items in the order, in stable display order. Array position is the line's order — there is no separate position field.

transactions
object[]
requerido

Every gateway charge attempt on this order, oldest first — declines and errors included. Empty for orders paid without a gateway.