> ## 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. # Fulfill (dispatch / mark ready) > Advance the order to FULFILLED. Delivery orders may include carrier + tracking; pickup orders must send an empty body. Requires the `fulfillment:write` scope. ## OpenAPI ````yaml /new-api/openapi.json post /orders/{id}/fulfillment/fulfill 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}/fulfillment/fulfill: post: tags: - Fulfillment summary: Fulfill (dispatch / mark ready) description: >- Advance the order to FULFILLED. Delivery orders may include carrier + tracking; pickup orders must send an empty body. Requires the `fulfillment:write` scope. parameters: - schema: type: string format: uuid example: 0b2e9f5a-1c3d-4e6f-8a9b-0c1d2e3f4a5b required: true name: id in: path requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/FulfillmentTracking' 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' '422': description: The transition is not allowed from the order's current state. content: application/json: schema: $ref: '#/components/schemas/Error' security: - BearerAuth: [] components: schemas: FulfillmentTracking: type: object properties: carrier: type: - string - 'null' minLength: 1 maxLength: 255 description: Carrier name. Required together with `trackingNumber`. trackingNumber: type: - string - 'null' minLength: 1 maxLength: 255 description: Carrier tracking/guide number. Required together with `carrier`. trackingUrl: type: - string - 'null' maxLength: 2000 format: uri description: URL to track the shipment. Optional. Order: type: object properties: id: type: string description: Order UUID. Stable primary key; use it for lookups. number: type: integer description: Per-organization sequential order number (shown as `#123`). example: 1042 status: type: string enum: - PLACED - CANCELLED description: 'Lifecycle status: `PLACED` or `CANCELLED`.' paymentStatus: type: string enum: - UNPAID - PARTIALLY_PAID - PAID - ERROR description: 'Payment state: `UNPAID`, `PARTIALLY_PAID`, `PAID`, or `ERROR`.' source: type: string enum: - STOREFRONT - PURCHASE_ORDER 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. Null until placed. cancelledAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: When the order was cancelled. Null unless `status` is `CANCELLED`. cancelReason: type: - string - 'null' description: Reason code for cancellation. Null unless cancelled. customerId: type: - string - 'null' description: Registered customer UUID. Null for guest checkouts. buyerFirstName: type: string description: First name the buyer provided at checkout. buyerLastName: type: string description: Last name the buyer provided at checkout. buyerEmail: type: - string - 'null' description: Buyer email, if provided. buyerPhone: type: - string - 'null' description: Buyer phone in E.164 format (e.g. `+51999100001`), if provided. documentType: type: - string - 'null' description: Personal ID document type (e.g. `DNI`). Null if not collected. documentNumber: type: - string - 'null' description: Personal ID document number. Null if not collected. fiscalDocumentType: type: - string - 'null' description: Invoice document type requested by the buyer. Null if no invoice. fiscalDocumentNumber: type: - string - 'null' description: Tax ID for the invoice (e.g. `RUC`). Null if no invoice. fiscalLegalName: type: - string - 'null' description: Legal name for the invoice. Null if no invoice. fiscalAddressLine: type: - string - 'null' description: Fiscal address for the invoice. Null if no invoice. shippingType: type: - string - 'null' enum: - DELIVERY - PICKUP - null description: '`DELIVERY` (ship to address) or `PICKUP` (collect at a location).' shippingMethodLabel: type: - string - 'null' description: Shipping method name chosen at checkout, snapshotted. deliveryAddressLine1: type: - string - 'null' description: Primary delivery street address. Set for `DELIVERY` orders. deliveryAddressLine2: type: - string - 'null' description: Secondary address line (apartment, reference). Optional. deliveryGeoLevel1: type: - string - 'null' description: >- Broadest administrative division of the delivery address (e.g. departamento in Peru). Set for `DELIVERY` orders. deliveryGeoLevel2: type: - string - 'null' description: >- Second administrative division (e.g. provincia in Peru). Null when the country uses fewer levels. deliveryGeoLevel3: type: - string - 'null' description: >- Third administrative division (e.g. distrito in Peru). Null when the country uses fewer levels. deliveryGeoLevel4: type: - string - 'null' description: >- Fourth administrative division. Null when the country uses fewer levels. deliveryAddressId: type: - string - 'null' description: >- UUID of the customer's saved address this delivery snapshot was copied from. Null for guest or one-off addresses. The snapshot fields stay frozen even if that address later changes. deliveryCoordinates: $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. deliveryInstructions: type: - string - 'null' description: Free-text delivery notes from the buyer. pickupLocationName: type: - string - 'null' description: Resolved pickup location name. Set for `PICKUP` orders. fulfillmentStatus: type: string enum: - UNFULFILLED - IN_PROGRESS - FULFILLED - DELIVERED description: >- Preparation state, forward-only: `UNFULFILLED` → `IN_PROGRESS` → `FULFILLED` → `DELIVERED`. shippingCarrier: 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 the order entered `IN_PROGRESS`. Null until preparation starts. fulfilledAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: When the order reached `FULFILLED` (dispatched). Null until then. deliveredAt: type: - string - 'null' example: '2026-06-30T14:12:00Z' description: When the order reached `DELIVERED`. Null until delivered. paymentMethod: type: - string - 'null' description: Payment method label chosen at checkout. paymentReference: 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. 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.' 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. required: - id - number - status - paymentStatus - source - createdAt - updatedAt - placedAt - cancelledAt - cancelReason - customerId - buyerFirstName - buyerLastName - buyerEmail - buyerPhone - documentType - documentNumber - fiscalDocumentType - fiscalDocumentNumber - fiscalLegalName - fiscalAddressLine - shippingType - shippingMethodLabel - deliveryAddressLine1 - deliveryAddressLine2 - deliveryGeoLevel1 - deliveryGeoLevel2 - deliveryGeoLevel3 - deliveryGeoLevel4 - deliveryAddressId - deliveryCoordinates - recipientName - recipientPhone - deliveryInstructions - pickupLocationName - fulfillmentStatus - shippingCarrier - trackingNumber - trackingUrl - preparingAt - fulfilledAt - deliveredAt - paymentMethod - paymentReference - paidAt - amountPaid - currencyCode - subtotal - taxTotal - shippingTotal - discountTotal - total - promotions - items Error: type: object properties: error: type: object properties: code: type: string message: type: string requestId: type: string required: - code - message - requestId required: - error 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 for the delivery. Null when the buyer didn't pin one. 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 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_…`.' ````