> ## Documentation Index > Fetch the complete documentation index at: https://docs.riqra.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /new-api/openapi.json post /orders/{id}/invoice openapi: 3.1.0 info: title: Riqra Public API version: 1.0.0 description: Programmatic access to a merchant's commerce data. servers: - url: https://api-v2.riqra.com/public/v1 security: [] paths: /orders/{id}/invoice: post: tags: - Invoicing summary: Register the invoice of an order description: >- 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. parameters: - schema: type: string format: uuid example: 0b2e9f5a-1c3d-4e6f-8a9b-0c1d2e3f4a5b description: Order UUID. required: true description: Order UUID. name: id in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterInvoiceRequest' responses: '200': description: The updated order. content: application/json: schema: $ref: '#/components/schemas/Order' '400': description: Invalid request body or order id. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Missing required scope. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No order with that id in this organization. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The order already has an invoice registered with that number. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: The order is cancelled. content: application/json: schema: $ref: '#/components/schemas/Error' security: - BearerAuth: [] components: schemas: RegisterInvoiceRequest: type: object properties: invoiceNumber: type: string minLength: 1 maxLength: 100 description: >- External document number as the issuer formats it (e.g. `F001-00001234`). issuedAt: type: string format: date-time description: >- 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: type: string format: uri description: >- 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. required: - invoiceNumber Order: type: object properties: id: type: string description: Order UUID. Stable primary key; use it for lookups. code: type: string description: >- Display code assigned at creation from the organization's configured prefix and padding (e.g. `#1042`, `P001042`). Never changes after creation. status: type: string enum: - PLACED - CANCELLED description: 'Lifecycle status: `PLACED` or `CANCELLED`.' paymentStatus: type: string enum: - UNPAID - PARTIALLY_PAID - PAID - PENDING - ERROR description: >- 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). fulfillmentStatus: type: string enum: - UNFULFILLED - IN_PROGRESS - FULFILLED - DELIVERED description: >- Preparation state, forward-only: `UNFULFILLED` → `IN_PROGRESS` → `FULFILLED` → `DELIVERED`. source: type: string enum: - STOREFRONT - PURCHASE_ORDER - MIGRATION description: Channel the order came from (currently always `STOREFRONT`). createdAt: type: string example: '2026-06-30T14:12:00Z' description: When the order record was created. updatedAt: type: string example: '2026-06-30T14:12:00Z' description: >- When the order was last modified. Use as the watermark for incremental sync. placedAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: >- When the customer placed the order. Set by every placement path; null only on legacy rows. cancelledAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: When the order was cancelled. Null unless `status` is `CANCELLED`. placedAsGuest: type: boolean description: >- The buyer had no session at placement. This is the guest signal — `buyer.customerId` is set either way. comment: type: - string - 'null' description: >- 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: type: string example: USD description: ISO 4217 currency code for all money fields. subtotal: type: string example: '1234.56' description: >- Net of everything (goods + shipping), post-discount. Equals total − taxTotal. subtotal + taxTotal = total in both tax modes. taxTotal: type: string example: '1234.56' description: Aggregate of all taxes on the order. shippingTotal: type: string example: '1234.56' description: >- Shipping charge as the buyer saw it. Informational — already reflected in subtotal/total; not an addend. discountTotal: type: string example: '1234.56' description: >- Goods + order discount as the buyer saw it. Informational; not an addend. Shipping discounts surface as a reduced shippingTotal plus a SHIPPING promotion. total: type: string example: '1234.56' description: 'Amount owed: subtotal + taxTotal.' priceList: $ref: '#/components/schemas/OrderPriceList' location: $ref: '#/components/schemas/OrderLocation' shippingMethod: $ref: '#/components/schemas/OrderShippingMethod' buyer: $ref: '#/components/schemas/OrderBuyer' billing: $ref: '#/components/schemas/OrderBilling' shippingAddress: $ref: '#/components/schemas/OrderShippingAddress' payment: $ref: '#/components/schemas/OrderPayment' cancellation: $ref: '#/components/schemas/OrderCancellation' fulfillments: type: array items: $ref: '#/components/schemas/OrderFulfillment' description: >- 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: type: string enum: - NOT_INVOICED - INVOICED description: >- Whether the order carries at least one registered fiscal document. Independent of `status`, `paymentStatus`, and `fulfillmentStatus`. invoices: type: array items: $ref: '#/components/schemas/OrderInvoice' description: >- Fiscal document references registered for the order, oldest first. Empty until invoiced; an order split across several facturas carries one element per document. promotions: type: array items: $ref: '#/components/schemas/OrderPromotion' description: Applied promotions on the order, including SHIPPING-class ones. items: type: array items: $ref: '#/components/schemas/OrderLineItem' description: >- Line items in the order, in stable display order. Array position is the line's order — there is no separate position field. transactions: type: array items: $ref: '#/components/schemas/PaymentTransaction' description: >- Every gateway charge attempt on this order, oldest first — declines and errors included. Empty for orders paid without a gateway. required: - id - code - status - paymentStatus - fulfillmentStatus - source - createdAt - updatedAt - placedAt - cancelledAt - placedAsGuest - comment - currencyCode - subtotal - taxTotal - shippingTotal - discountTotal - total - priceList - location - shippingMethod - buyer - billing - shippingAddress - payment - cancellation - fulfillments - invoiceStatus - invoices - promotions - items - transactions Error: type: object properties: error: type: object properties: code: type: string message: type: string requestId: type: string required: - code - message - requestId required: - error OrderPriceList: type: - object - 'null' properties: id: type: string description: Price list UUID as resolved at placement. name: type: string description: Price list name snapshotted at placement. required: - id - name description: >- 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. OrderLocation: type: - object - 'null' properties: id: type: string description: Location UUID. Resolvable against `GET /stock/locations`. name: type: string description: Location name. required: - id - name description: >- 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. OrderShippingMethod: type: object properties: id: type: - string - 'null' description: >- Shipping method UUID. Null once that method is deleted — `type` and `label` are snapshots and still hold. type: type: - string - 'null' enum: - DELIVERY - PICKUP - null description: >- `DELIVERY` (ship to address) or `PICKUP` (collect at `location`). Snapshotted at placement. Null only on orders placed with no shipping rail at all. label: type: - string - 'null' description: Shipping method name chosen at checkout, snapshotted. required: - id - type - label description: >- The shipping method snapshot. `type` is the delivery/pickup discriminator. OrderBuyer: type: object properties: firstName: type: string description: First name the buyer gave at checkout, snapshotted. lastName: type: string description: Last name the buyer gave at checkout, snapshotted. email: type: - string - 'null' description: Buyer email as given at checkout, if provided. phone: type: - string - 'null' description: >- Buyer phone in E.164 format (e.g. `+51999100001`) as given at checkout, if provided. customerId: type: - string - 'null' description: >- Registered customer UUID, and the value `GET /orders`'s `customerId` filter takes. This is the live link; the fields beside it are frozen at checkout and may no longer match what that customer record says today. Set on every order — a guest checkout finds or creates a customer record from the checkout email, so it is not a guest signal; `placedAsGuest` is. Null only on legacy orders and once the customer is deleted. documentType: type: - string - 'null' description: >- Buyer's personal ID document type (e.g. `DNI`). Not the invoice document — that is `billing.documentType`. Null if not collected. documentNumber: type: - string - 'null' description: Buyer's personal ID document number. Null if not collected. required: - firstName - lastName - email - phone - customerId - documentType - documentNumber description: Who placed the order, as they identified themselves at checkout. OrderBilling: type: - object - 'null' properties: documentType: type: - string - 'null' description: Invoice document type requested by the buyer (e.g. `FACTURA`). documentNumber: type: - string - 'null' description: Tax ID for the invoice (e.g. a `RUC` number). legalName: type: - string - 'null' description: Legal name for the invoice. addressLine: type: - string - 'null' description: Fiscal address for the invoice. required: - documentType - documentNumber - legalName - addressLine description: >- Invoicing details the buyer requested. Null when no invoice was requested. Distinct from `buyer.documentType` / `buyer.documentNumber`, which are the buyer's own ID. OrderShippingAddress: type: - object - 'null' properties: addressLine1: type: - string - 'null' description: Primary delivery street address. addressLine2: type: - string - 'null' description: Secondary address line (apartment, reference). Optional. geoLevel1: type: - object - 'null' properties: name: type: string example: Miraflores description: Division name. code: type: - string - 'null' example: '150122' description: >- Official code the country's statistical agency assigns to this division — in Peru the INEI ubigeo, whose digits accumulate down the levels (`15` departamento, `1501` provincia, `150122` distrito). Null for countries that publish no code system. required: - name - code description: >- Broadest administrative division of the address (e.g. departamento in Peru). geoLevel2: type: - object - 'null' properties: name: type: string example: Miraflores description: Division name. code: type: - string - 'null' example: '150122' description: >- Official code the country's statistical agency assigns to this division — in Peru the INEI ubigeo, whose digits accumulate down the levels (`15` departamento, `1501` provincia, `150122` distrito). Null for countries that publish no code system. required: - name - code description: >- Second administrative division (e.g. provincia in Peru). Null when the country uses fewer levels. geoLevel3: type: - object - 'null' properties: name: type: string example: Miraflores description: Division name. code: type: - string - 'null' example: '150122' description: >- Official code the country's statistical agency assigns to this division — in Peru the INEI ubigeo, whose digits accumulate down the levels (`15` departamento, `1501` provincia, `150122` distrito). Null for countries that publish no code system. required: - name - code description: >- Third administrative division (e.g. distrito in Peru). Null when the country uses fewer levels. geoLevel4: type: - object - 'null' properties: name: type: string example: Miraflores description: Division name. code: type: - string - 'null' example: '150122' description: >- Official code the country's statistical agency assigns to this division — in Peru the INEI ubigeo, whose digits accumulate down the levels (`15` departamento, `1501` provincia, `150122` distrito). Null for countries that publish no code system. required: - name - code description: >- Fourth administrative division. Null when the country uses fewer levels. coordinates: $ref: '#/components/schemas/DeliveryCoordinates' recipientName: type: - string - 'null' description: Person receiving the delivery, if different from the buyer. recipientPhone: type: - string - 'null' description: Recipient phone in E.164 format, if provided. instructions: type: - string - 'null' description: Free-text delivery notes from the buyer. customerAddressId: type: - string - 'null' description: >- UUID of the customer's saved address this snapshot was copied from. Null for guest or one-off addresses. The snapshot stays frozen even if that address later changes. required: - addressLine1 - addressLine2 - geoLevel1 - geoLevel2 - geoLevel3 - geoLevel4 - coordinates - recipientName - recipientPhone - instructions - customerAddressId description: Delivery address snapshot. Null on `PICKUP` orders. OrderPayment: type: object properties: methodKind: type: - string - 'null' enum: - MANUAL - CARD - CREDIT - null description: >- How the chosen method settles: `MANUAL` (out-of-band), `CARD` (gateway charge) or `CREDIT` (the buyer's credit line). methodName: type: - string - 'null' description: Payment method the buyer chose at checkout, snapshotted. paidVia: type: - string - 'null' enum: - CARD - CASH - BANK_TRANSFER - CARD_OFFLINE - OTHER - null description: >- Channel the money was actually received through. Set when the merchant records a payment or a card charge succeeds, so it can legitimately differ from `methodName` — a buyer picks a transfer, the merchant records `CASH`. Null while nothing is received. installments: type: - integer - 'null' example: 12 description: >- Instalment count (`cuotas`) on the attempt in flight — rewritten on every retry, whether or not it was approved. For the approved plan read the `SUCCESS` entry in `transactions`. Null for a single payment. installmentsInterest: type: - string - 'null' enum: - WITH_INTEREST - WITHOUT_INTEREST - null description: >- Whether the in-flight instalment plan carries issuer interest. Null when there is no plan. reference: type: - string - 'null' description: Buyer-supplied reconciliation reference (transfer/voucher id). paidAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: When payment was recorded. Null while unpaid. amountPaid: type: string example: '1234.56' description: Amount recorded as paid so far. required: - methodKind - methodName - paidVia - installments - installmentsInterest - reference - paidAt - amountPaid description: >- The method the buyer chose and what has been received against `paymentStatus`. Per-attempt gateway facts live in `transactions`. OrderCancellation: type: - object - 'null' properties: reason: type: - string - 'null' description: >- Why the order was cancelled: an operator code (`CUSTOMER`, `INVENTORY`, `FRAUD`, `STAFF_ERROR`, `OTHER`) or an automatic payment cancel (`PAYMENT_EXPIRED`, and on older orders `PAYMENT_DECLINED` / `PAYMENT_3DS_UNSUPPORTED`). Migrated orders may carry the source platform's own text. Treat unknown values as `OTHER` — the set grows. note: type: - string - 'null' description: >- Free-text note the operator wrote when cancelling. Internal — never shown to the buyer. Null when none was given. byMemberId: type: - string - 'null' description: >- Member UUID of the operator who cancelled. Null for automatic payment-failure cancels, for cancellations made through this API (a key is the organization, not a person), and once that member is removed — `byName` still holds. byName: type: - string - 'null' description: >- Operator name, snapshotted at cancellation time. Null when no person cancelled. required: - reason - note - byMemberId - byName description: >- Why and by whom the order was cancelled. Null unless `status` is `CANCELLED`. OrderFulfillment: type: object properties: carrier: type: - string - 'null' description: Carrier handling the shipment. Delivery orders only. trackingNumber: type: - string - 'null' description: Carrier tracking/guide number. Delivery orders only. trackingUrl: type: - string - 'null' description: URL to track the shipment. Delivery orders only. preparingAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: When preparation started. Null when it was skipped. fulfilledAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: When the shipment was dispatched. Null until then. deliveredAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: When the shipment was delivered. Null until then. required: - carrier - trackingNumber - trackingUrl - preparingAt - fulfilledAt - deliveredAt OrderInvoice: type: object properties: id: type: string description: Invoice UUID. Use it to address this specific invoice. number: type: string description: External invoice number as the issuer formats it. issuedAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: Fiscal issuance date reported by the issuer. Null when not reported. registeredAt: type: string example: '2026-06-30T14:12:00Z' description: When the invoice was registered on the platform. required: - id - number - issuedAt - registeredAt OrderPromotion: type: object properties: id: type: string description: >- Promotion application id. Reference key for a line's `discountAllocations[].promotionId`. code: type: - string - 'null' description: Entered promotion code. Null for automatic promotions. title: type: string description: Human-readable promotion label. class: type: string enum: - GOODS - ORDER - SHIPPING description: >- What the promotion discounted: `GOODS`, `ORDER`, or `SHIPPING`. GOODS and ORDER are summed into the order `discountTotal`; SHIPPING shows as a reduced `shippingTotal`. amount: type: string example: '1234.56' description: Discount amount, as the buyer saw it. required: - id - code - title - class - amount OrderLineItem: type: object properties: id: type: string description: Line item identifier. variantId: type: - string - 'null' description: Product variant UUID. Null if the line isn't tied to a variant. variantSku: type: - string - 'null' description: Variant SKU. Null if the line isn't tied to a variant. productId: type: - string - 'null' description: Product UUID. Null if the product was later removed. productName: type: string description: Product name, snapshotted at order time. productImageUrl: type: - string - 'null' description: Product image URL, snapshotted at order time. Null if none. quantity: type: integer description: Units ordered. example: 2 price: type: string example: '1234.56' description: Unit price charged, before promotions. listPrice: type: - string - 'null' example: '1234.56' description: >- The variant's list price when the order was placed. Null when the variant carries none. discountTotal: type: string example: '1234.56' description: >- Promotion discount on this line, as the buyer saw it. Not the list-vs-charged gap ((listPrice − price) × quantity), which is derivable. discountAllocations: type: array items: $ref: '#/components/schemas/OrderLineItemDiscountAllocation' description: >- Per-line breakdown of `discountTotal` by promotion (Shopify DiscountAllocation). Each entry references an order-level `promotions[].id`; allocations of one promotion across all lines sum to that promotion's `amount`. `discountTotal` remains the aggregate for this line. subtotal: type: string example: '1234.56' description: >- Net goods base for this line, on the discounted amount. subtotal + taxTotal = total. taxTotal: type: string example: '1234.56' description: Goods tax for this line. total: type: string example: '1234.56' description: subtotal + taxTotal. components: type: array items: $ref: '#/components/schemas/OrderLineComponent' description: >- Bundle composition frozen at order time, in stable display order. Empty for standard (non-bundle) lines. required: - id - variantId - variantSku - productId - productName - productImageUrl - quantity - price - listPrice - discountTotal - discountAllocations - subtotal - taxTotal - total - components PaymentTransaction: type: object properties: id: type: string description: Transaction identifier. kind: type: string enum: - AUTHORIZATION - SALE description: '`SALE` (authorize + capture) or `AUTHORIZATION` (hold only).' status: type: string enum: - PENDING - SUCCESS - FAILURE - ERROR description: >- `PENDING` (awaiting the gateway), `SUCCESS`, `FAILURE` (declined), or `ERROR` (the call itself failed — outcome unknown, reconcile against the gateway). amount: type: string example: '1234.56' description: Amount charged, in the order's `currencyCode`. provider: type: string enum: - OPENPAY - CULQI description: Gateway that processed it. gatewayTransactionId: type: - string - 'null' description: >- The gateway's own charge id — the reconciliation key. Null when the attempt never reached the gateway. cardBrand: type: - string - 'null' description: Card brand, lowercase (e.g. `visa`). Null for non-card methods. cardLast4: type: - string - 'null' description: Last 4 digits of the card. Null if the gateway didn't report them. cardType: type: - string - 'null' enum: - CREDIT - DEBIT - PREPAID - UNKNOWN - null description: Card funding type. Null if the gateway doesn't report one. installments: type: - integer - 'null' example: 12 description: >- Instalment count (`cuotas`) asked of the gateway on this attempt — on the `SUCCESS` entry, the approved plan. Null for a single payment. installmentsInterest: type: - string - 'null' enum: - WITH_INTEREST - WITHOUT_INTEREST - null description: >- Whether this attempt's instalment plan carries issuer interest. Null when the attempt had no plan. authorizationCode: type: - string - 'null' description: Processor authorization code. Null on declines. gatewayResultCode: type: - string - 'null' description: The gateway's raw outcome/decline code, as it reported it. errorCode: type: - string - 'null' description: >- Gateway-independent failure code (e.g. `CARD_DECLINED`, `INSUFFICIENT_FUNDS`). Null on success. Treat unknown values as a generic failure — the set grows. test: type: boolean description: The charge ran against the gateway's test mode. processedAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: When the attempt was processed. createdAt: type: string example: '2026-06-30T14:12:00Z' description: When the attempt was recorded. required: - id - kind - status - amount - provider - gatewayTransactionId - cardBrand - cardLast4 - cardType - installments - installmentsInterest - authorizationCode - gatewayResultCode - errorCode - test - processedAt - createdAt DeliveryCoordinates: type: - object - 'null' properties: latitude: type: number example: -12.046374 description: Latitude in decimal degrees (WGS84). longitude: type: number example: -77.042793 description: Longitude in decimal degrees (WGS84). required: - latitude - longitude description: Confirmed drop-off point. Null when the buyer didn't pin one. OrderLineItemDiscountAllocation: type: object properties: promotionId: type: string description: References an order-level `promotions[].id`. amount: type: string example: '1234.56' description: That promotion's slice of this line's discount. required: - promotionId - amount OrderLineComponent: type: object properties: id: type: string description: Component snapshot identifier. variantId: type: - string - 'null' description: Component variant UUID. Null if the variant was later removed. variantSku: type: - string - 'null' description: Component variant SKU. Null if none. productId: type: - string - 'null' description: Component product UUID. Null if the product was later removed. productName: type: string description: Component product name, snapshotted at order time. quantityPerBundle: type: integer description: >- Units of this component inside one bundle. Multiply by the line's `quantity` for the total units to fulfill. example: 3 required: - id - variantId - variantSku - productId - productName - quantityPerBundle securitySchemes: BearerAuth: type: http scheme: bearer description: 'Public API key presented as `Authorization: Bearer rq_live_…`.' ````