---
title: "Orders"
description: "Reference for creating, paying, updating, and reading Inttegro orders."
canonical: "https://studio.inttegro.com/api/orders"
format: inttegro-machine-docs/v1
language: "cURL"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/curl/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 690
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: ["get_order","list_orders","get_order_analytics"]
estimated_tokens: 22621
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Reference for creating, paying, updating, and reading Inttegro orders. This cURL representation preserves HTTP paths and JSON wire names.

### Five questions

#### Q1. Is Orders the right source for this task?

Use this reference for reference for creating, paying, updating, and reading inttegro orders. For the complete outcome or lifecycle, start with [Orders product guide](https://studio.inttegro.com/machine/curl/products/orders.md); return here for exact operations and fields.

#### Q2. How do I recover an interrupted order workflow?

**Read the latest order before recovering an interrupted workflow.** Treat
omitted optional properties as absent, not as empty values, and use the
returned order and payment states rather than reconstructing state from an
earlier response.

#### Q3. What must happen before presenting hosted payment?

**Finalize before presenting hosted payment.** Build or update the draft,
then [finalize](#finalize-an-order) it to obtain invoice URLs. Finalizing an
already sealed order is safe; changes to seal-sensitive fields may require an
explicit reopen-and-finalize cycle described by [Update an
order](#update-an-order).

#### Q4. How should I handle an uncertain payment attempt?

**Do not replace an uncertain payment attempt.** Repeat the same logical
operation with its stable [idempotency key](https://studio.inttegro.com/machine/curl/api/idempotency.md), then lookup the
order before deciding whether another payment action is needed.

#### Q5. Which order states constrain later operations?

**Terminal state constrains the workflow.** Paid, completed, canceled, or
expired orders cannot simply re-enter every earlier operation. Use
[Error codes](https://studio.inttegro.com/machine/curl/api/error-codes.md#orders) and the latest resource state to choose
a recovery path.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`get_order`](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#get_order) — read; no mutation confirmation. Gets one order by ID with a minimized, contact-free projection of order, payment, and timing state.
- [`list_orders`](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#list_orders) — read; no mutation confirmation. Lists a bounded page of recent orders with totals and status, excluding customer contact and address data.
- [`get_order_analytics`](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#get_order_analytics) — analytics read; no mutation confirmation. Compares order volume, paid orders, cancellations, expirations, and gross sales for a 7, 30, or 90 day period with exact daily values and a Flint chart.

## Document content

# Orders

Use this reference for exact Orders API request attributes, response envelopes, object shape, and examples. For lifecycle, checkout patterns, ID boundaries, and fulfillment behavior, start with the [Orders product guide](https://studio.inttegro.com/machine/curl/products/orders.md).

## Choose the next order operation from current state

The four decision rules are in the machine preamble above.

## The order object

Every single-order endpoint returns an `order` envelope. Page returns the same object inside `page.orders`. Optional fields are omitted until they exist; treat omission as absence, not as an empty value. When an order has refunds, `order.refunds` contains every refund in newest-first order and each entry uses the complete shared [refund object](https://studio.inttegro.com/machine/curl/api/refunds.md#the-refund-object). Orders without refunds omit the attribute entirely; they do not return an empty or null `order.refunds` value.

### Properties

- `canceled_at` — `timestamp`

  When the order was canceled. Omitted until cancellation.

- `checkout_settings`

  Optional hosted-checkout redirects. Omitted when not configured.

  - `checkout_settings.cancel_url` — `string`

    URL to redirect customers who cancel or abandon payment. Strongly recommended to handle cancellations gracefully.

  - `checkout_settings.redirect_url` — `string`

    URL to redirect customers after successful payment. Strongly recommended for a seamless customer experience.

- `completed_at` — `timestamp`

  When the order was completed. Omitted until completion.

- `created_from`

  Origin attribution for an order created from another public resource. Omitted for direct API-created orders.

  - `created_from.resource_id` — `string`

    ID of the originating resource, such as a purchase intent.

  - `created_from.resource_type` — `string`

    Originating resource type. Currently `"purchase_intent"` when present.

  - `created_from.source` — `string`

    Checkout source recorded by Inttegro. Omitted when unavailable.

- `custom_data` — `object`

  Your string key-value data. Omitted when empty.

- `customer`

  Customer who placed this order.

  - `customer.billing_address` — `object`

    Customer billing address. Omitted when unavailable.

  - `customer.email_address` — `string`

    Email for receipts and updates.

  - `customer.guest` — `boolean`

    Whether the customer was created as a guest during checkout.

  - `customer.id` — `string`

    Customer ID.

  - `customer.name` — `string`

    Full name for billing and communication.

  - `customer.phone_number` — `string`

    Phone number for OTP and notifications.

  - `customer.shipping_address` — `object`

    Customer shipping address. Omitted when unavailable.

- `expires_at` — `timestamp`

  When the order expires. Omitted when no expiry applies.

- `id` — `string`

  Unique identifier for this order—use it for lookups, updates, and payment
  operations.

- `initiated_at` — `timestamp`

  When we started processing this order.

- `invoice`

  Hosted invoice links. Omitted while the order is a draft.

  - `invoice.format` — `object`

    Invoice viewing links.

    - `invoice.format.pdf` — `object`

      PDF download.

      - `invoice.format.pdf.url` — `string`

        Direct PDF link.

    - `invoice.format.web` — `object`

      Hosted page.

      - `invoice.format.web.url` — `string`

        Web URL for viewing the invoice.

  - `invoice.number` — `string`

    Invoice number. Omitted when unset.

- `invoice_settings`

  Customer-facing invoice content. Omitted when not configured.

  - `invoice_settings.custom_data` — `object`

    String key-value data. Omitted when empty.

  - `invoice_settings.footer` — `string`

    Invoice footer. Omitted when unset.

  - `invoice_settings.memo` — `string`

    Invoice memo. Omitted when unset.

  - `invoice_settings.number` — `string`

    Invoice number. Omitted when unset.

- `line_item_group`

  Cart contents and totals.

  - `line_item_group.line_items` — `array`

    Array of products, fees, and shipping charges—each with a `order.line_item_group.line_items[].type` discriminator.

    - `line_item_group.line_items.discount` — `object`

      Discount details when `order.line_item_group.line_items[].type` is discount. Reserved for orders that contain a discount line.

    - `line_item_group.line_items.fee` — `object`

      Fee details when `order.line_item_group.line_items[].type` is `"fee"` —covers service charges, convenience fees, etc.

      - `line_item_group.line_items.fee.amount` — `object`

        Fee amount.

        - `line_item_group.line_items.fee.amount.currency` — `string`

          Currency code.

        - `line_item_group.line_items.fee.amount.value` — `integer`

          Amount in smallest currency unit.

      - `line_item_group.line_items.fee.description` — `string`

        Internal note about what this fee covers.

      - `line_item_group.line_items.fee.id` — `string`

        Order-line identifier generated for this fee. Starts with oli\_.

      - `line_item_group.line_items.fee.label` — `string`

        Customer-facing label for this fee.

      - `line_item_group.line_items.fee.tax_code` — `string`

        Tax classification code for this fee.

    - `line_item_group.line_items.product` — `object`

      Product details when `order.line_item_group.line_items[].type` is `"product"` .

      - `line_item_group.line_items.product.about` — `string`

        Long-form description or marketing copy.

      - `line_item_group.line_items.product.category` — `string`

        Catalog or inline product category. Omitted when unset.

      - `line_item_group.line_items.product.custom_data` — `object`

        Your own key-value string pairs—exactly the same shape as the `order.line_item_group.line_items[].product.custom_data` field in the API.

      - `line_item_group.line_items.product.id` — `string`

        Order-line identifier generated for this product snapshot. Starts with oli\_; it is not a catalog product ID.

      - `line_item_group.line_items.product.name` — `string`

        Product name shown to the customer.

      - `line_item_group.line_items.product.price` — `object`

        Per-unit price.

        - `line_item_group.line_items.product.price.currency` — `string`

          Currency code.

        - `line_item_group.line_items.product.price.value` — `integer`

          Price in smallest currency unit.

      - `line_item_group.line_items.product.price_id` — `string`

        Catalog price copied into this line. Omitted for inline or explicitly priced products.

      - `line_item_group.line_items.product.product_id` — `string`

        Catalog product copied into this line. Omitted for inline products.

      - `line_item_group.line_items.product.quantity` — `integer`

        How many units the customer is purchasing.

      - `line_item_group.line_items.product.reference` — `string`

        Your SKU or internal product reference.

      - `line_item_group.line_items.product.tax_code` — `string`

        Tax classification code for this item.

      - `line_item_group.line_items.product.type` — `string`

        Product type: `"cause"` , `"custom"` , `"digital"` , `"physical"` , `"service"` , or `"voucher"` .

    - `line_item_group.line_items.shipping` — `object`

      Shipping details when `order.line_item_group.line_items[].type` is `"shipping"` .

      - `line_item_group.line_items.shipping.fee` — `object`

        Shipping cost.

        - `line_item_group.line_items.shipping.fee.currency` — `string`

          Currency code.

        - `line_item_group.line_items.shipping.fee.value` — `integer`

          Amount in smallest currency unit.

      - `line_item_group.line_items.shipping.id` — `string`

        Order-line identifier generated for this shipping charge. Starts with oli\_.

      - `line_item_group.line_items.shipping.label` — `string`

        Customer-facing label for this shipping charge.

      - `line_item_group.line_items.shipping.tax_code` — `string`

        Tax classification code for this shipping charge.

    - `line_item_group.line_items.type` — `string`

      Line item type: discount, `"fee"` , `"product"` , or `"shipping"` .

  - `line_item_group.total` — `object`

    Sum of all line items after any adjustments.

    - `line_item_group.total.currency` — `string`

      ISO currency code. Supported values for order creation are `"ghs"` , `"usd"` , `"gbp"` , `"eur"` , and `"cny"` .

    - `line_item_group.total.value` — `integer`

      Amount in smallest unit (cents, pesewas, etc.).

- `number` — `string`

  Human-friendly reference like `ORDER-1234` for your
  internal systems and customer communication.

- `payment`

  Payment collection record tied to this order. Its status is independent from fulfillment state.

  - `payment.amount` — `object`

    Total amount being charged.

    - `payment.amount.currency` — `string`

      Currency code. Supported values for order creation are `"ghs"` , `"usd"` , `"gbp"` , `"eur"` , and `"cny"` .

    - `payment.amount.value` — `integer`

      Amount in smallest unit.

  - `payment.balance_transaction` — `object`

    Ledger entry available after money movement is recorded. Its type is `"payment"` or `"refund"` , with exactly one matching strong reference.

    - `payment.balance_transaction.amount` — `object`

      Net funds that hit your balance for this payment.

      - `payment.balance_transaction.amount.currency` — `string`

        Currency code. Supported values for order creation are `"ghs"` , `"usd"` , `"gbp"` , `"eur"` , and `"cny"` .

      - `payment.balance_transaction.amount.value` — `integer`

        Amount in smallest unit.

    - `payment.balance_transaction.available_at` — `timestamp`

      When the funds become available for payout. Omitted until known.

    - `payment.balance_transaction.claimed_at` — `timestamp`

      When the funds were claimed for payout. Omitted until claimed.

    - `payment.balance_transaction.created_at` — `timestamp`

      When the balance transaction was created.

    - `payment.balance_transaction.id` — `string`

      Balance transaction ID.

    - `payment.balance_transaction.order_id` — `string`

      Order that created this balance transaction.

    - `payment.balance_transaction.paid_at` — `timestamp`

      When the payout was completed. Omitted until paid.

    - `payment.balance_transaction.payment_id` — `string`

      Strong source reference present when `order.payment.balance_transaction.type` is `"payment"` . Omitted for `"refund"` .

    - `payment.balance_transaction.payout_id` — `string`

      Payout that will disburse the funds. Omitted until scheduled.

    - `payment.balance_transaction.refund_id` — `string`

      Strong source reference present when `order.payment.balance_transaction.type` is `"refund"` . Omitted for `"payment"` .

    - `payment.balance_transaction.type` — `enum`

      Semantic source of the entry: `"payment"` or `"refund"` . This is a cause, not a direction indicator.

  - `payment.billing_details` — `object`

    Billing owner details associated with the payment method. Omitted when unavailable.

  - `payment.canceled_at` — `timestamp`

    When payment was canceled. Omitted until canceled.

  - `payment.customer` — `object`

    Customer snapshot associated with this payment. Omitted when unavailable.

  - `payment.receipt` — `object`

    Receipt issued for this payment. Omitted until the order is paid or completed.

    - `payment.receipt.number` — `string`

      Merchant-provided receipt number. Omitted when unset.

    - `payment.receipt.format` — `object`

      Hosted receipt representations.

      - `payment.receipt.format.web` — `object`

        Hosted receipt page.

        - `payment.receipt.format.web.url` — `string`

          Hosted receipt URL.

      - `payment.receipt.format.pdf` — `object`

        Receipt PDF.

        - `payment.receipt.format.pdf.url` — `string`

          Receipt PDF URL.

    - `payment.receipt.delivery_summary` — `object`

      Receipt delivery history. Omitted until sent.

  - `payment.due_at` — `timestamp`

    When payment is due. Omitted when unset.

  - `payment.executed_at` — `timestamp`

    When payment execution began. Omitted until execution.

  - `payment.expired_at` — `timestamp`

    When payment expired. Omitted until expired.

  - `payment.failed_at` — `timestamp`

    When payment failed. Omitted until failed.

  - `payment.id` — `string`

    Payment ID—use it to correlate confirmation and payment operations.

  - `payment.initiated_at` — `timestamp`

    When Inttegro created the payment.

  - `payment.latest_error` — `object`

    Structured error for the latest failed payment operation. Omitted when unavailable.

  - `payment.latest_attempt` — `object`

    Details about the most recent charge attempt. Omitted before the first attempt.

    - `payment.latest_attempt.error` — `object`

      Attempt error details. Omitted when no error is available.

    - `payment.latest_attempt.initiated_at` — `timestamp`

      When this attempt started.

    - `payment.latest_attempt.payment_method_id` — `string`

      Payment method that was charged.

    - `payment.latest_attempt.payment_method_type` — `string`

      Payment rail used for this attempt.

    - `payment.latest_attempt.reference` — `string`

      Gateway reference or transaction ID.

    - `payment.latest_attempt.status` — `string`

      Attempt status: `"initiated"` , `"executed"` , `"succeeded"` , `"canceled"` , `"expired"` , `"failed"` , or `"unknown"` .

    - `payment.latest_attempt.succeeded_at` — `timestamp`

      Set when the attempt succeeds. Omitted otherwise.

  - `payment.next_action` — `object`

    What needs to happen next to complete the payment.

    - `payment.next_action.confirm_payment` — `object`

      OTP confirmation flow details.

      - `payment.next_action.confirm_payment.expires_at` — `timestamp`

        When this OTP token expires.

      - `payment.next_action.confirm_payment.request` — `object`

        Details about the OTP we sent.

        - `payment.next_action.confirm_payment.request.id` — `string`

          Unique ID for this OTP delivery.

        - `payment.next_action.confirm_payment.request.recipient` — `string`

          Phone number or email that received the token.

        - `payment.next_action.confirm_payment.request.sender_id` — `string`

          Sender name shown to the customer (e.g., zverify).

        - `payment.next_action.confirm_payment.request.sent_via` — `string`

          Delivery channel: `"sms"` or `"email"` .

        - `payment.next_action.confirm_payment.request.token_size` — `integer`

          Length of the OTP code (usually 6).

      - `payment.next_action.confirm_payment.scheme` — `string`

        Auth scheme: typically inttegro\_defined\_auth.

    - `payment.next_action.type` — `string`

      Action required: `"confirm_payment"` , authorize\_payment, etc.

  - `payment.paid_at` — `timestamp`

    When funds were fully captured and marked as paid. Omitted until paid.

  - `payment.paid_offline` — `boolean`

    Whether payment was recorded out of band. Omitted when unavailable.

  - `payment.payment_method` — `object`

    The payment method being charged.

    - `payment.payment_method.created_at` — `timestamp`

      When this method was added.

    - `payment.payment_method.customer_id` — `string`

      Which customer owns this payment method.

    - `payment.payment_method.id` — `string`

      Saved payment method ID.

    - `payment.payment_method.mobile_money` — `object`

      Mobile money details. Present when `order.payment.payment_method.type` is `"mobile_money"` .

      - `payment.payment_method.mobile_money.account_number` — `string`

        Masked account number.

      - `payment.payment_method.mobile_money.last4` — `string`

        Last four digits of the wallet account.

      - `payment.payment_method.mobile_money.network` — `string`

        Wallet network: `"airtel"` , `"mtn"` , `"telecel"` , or `"vodafone"` .

    - `payment.payment_method.type` — `string`

      Payment rail: `"mobile_money"` , `"card"` , `"bank_account"` , etc.

    - `payment.payment_method.verified` — `boolean`

      Whether the payment method passed verification.

    - `payment.payment_method.verified_at` — `timestamp`

      When verification completed. Omitted if not verified.

  - `payment.payment_method_types` — `array`

    Payment rails allowed for this payment. Omitted when unavailable.

  - `payment.payout_configuration` — `object`

    Payout routing instructions for this payment. Present only when order-level `payout_settings` was specified during order creation.

    - `payment.payout_configuration.destination` — `object`

      Where funds will be paid out.

      - `payment.payout_configuration.destination.financial_account_id` — `string`

        Financial account that will receive the payout.

    - `payment.payout_configuration.enable_fx` — `boolean`

      Compatibility flag for payout routing. It is currently always `false` because cross-currency payouts are unavailable.

  - `payment.statement_descriptor` — `string`

    Statement descriptor assigned to the payment.

  - `payment.status` — `string`

    Payment state: `"initiated"` , `"overdue"` , `"executed"` , `"requires_action"` , `"paid"` , `"failed"` , `"canceled"` , `"expired"` , or `"unknown"` .

- `receipt_number` — `string`

  Merchant-supplied receipt reference for reconciliation. Omitted when unset;
  Inttegro does not enforce uniqueness.

- `paid_at` — `timestamp`

  When the order was paid. Omitted until paid.

- `payment_due_at` — `timestamp`

  When payment is due. Omitted when no due time was supplied.

- `payout_settings`

  Order-specific payout settings. Omitted when not configured.

- `refunds` — `array`

  Complete refund objects for this order in newest-first order. Omitted when the order has no refunds.

  - `refunds.items` — `object`

    Each entry is the complete shared refund object. See the Refunds API reference for the canonical object and lifecycle fields.

    - `refunds.items.canceled_at` — `timestamp`

      When the refund entered the `"canceled"` state. Omitted otherwise.

    - `refunds.items.created_at` — `timestamp`

      When the refund was created.

    - `refunds.items.custom_data` — `object`

      Your metadata, returned as string values. Omitted when empty.

    - `refunds.items.failed_at` — `timestamp`

      When the refund entered the `"failed"` state. Omitted otherwise.

    - `refunds.items.id` — `string`

      Unique refund identifier with the rf\_ prefix.

    - `refunds.items.line_items` — `array`

      Immutable allocations describing how much is refunded for each order line item.

      - `refunds.items.line_items.id` — `string`

        Server-generated refund line-item ID with the rli\_ prefix.

      - `refunds.items.line_items.order_line_item` — `object`

        Immutable snapshot of the original order line. Use order\_line\_item.id to match the refund allocation to the order. Discriminate on `order.refunds[].line_items[].order_line_item.type` before reading the product, fee, or shipping branch. Omitted when the originating order cannot be resolved.

        - `refunds.items.line_items.order_line_item.fee` — `object`

          Fee details captured on the order. Present only when `order.refunds[].line_items[].order_line_item.type` is `"fee"` .

          - `refunds.items.line_items.order_line_item.fee.description` — `string`

            Fee description captured on the order.

          - `refunds.items.line_items.order_line_item.fee.label` — `string`

            Fee label captured on the order.

        - `refunds.items.line_items.order_line_item.id` — `string`

          Original order line-item ID with the oli\_ prefix.

        - `refunds.items.line_items.order_line_item.product` — `object`

          Product details captured on the order. Present only when `order.refunds[].line_items[].order_line_item.type` is `"product"` .

          - `refunds.items.line_items.order_line_item.product.id` — `string`

            Source catalog product ID with the prod\_ prefix. Omitted for inline products.

          - `refunds.items.line_items.order_line_item.product.name` — `string`

            Product name captured on the order.

        - `refunds.items.line_items.order_line_item.quantity` — `integer`

          Quantity captured on the order. Present only when `order.refunds[].line_items[].order_line_item.type` is `"product"` .

        - `refunds.items.line_items.order_line_item.shipping` — `object`

          Shipping details captured on the order. Present only when `order.refunds[].line_items[].order_line_item.type` is `"shipping"` .

          - `refunds.items.line_items.order_line_item.shipping.description` — `string`

            Shipping description captured on the order.

          - `refunds.items.line_items.order_line_item.shipping.label` — `string`

            Shipping label captured on the order.

        - `refunds.items.line_items.order_line_item.type` — `enum`

          `"product"` , `"fee"` , or `"shipping"` .

      - `refunds.items.line_items.original_amount_paid` — `object`

        Amount originally paid for this order line allocation.

        - `refunds.items.line_items.original_amount_paid.currency` — `string`

          Lowercase currency code.

        - `refunds.items.line_items.original_amount_paid.value` — `integer`

          Positive amount in the smallest currency unit.

      - `refunds.items.line_items.reason` — `enum`

        Independent reason for refunding this line. Omitted when not provided.

      - `refunds.items.line_items.reason_details` — `string`

        Line-specific explanation. Omitted when not provided.

      - `refunds.items.line_items.refund_amount` — `object`

        Amount returned for this line.

        - `refunds.items.line_items.refund_amount.currency` — `string`

          Lowercase currency code.

        - `refunds.items.line_items.refund_amount.value` — `integer`

          Positive amount in the smallest currency unit.

    - `refunds.items.order_id` — `string`

      Paid order covered by this refund, with the or\_ prefix.

    - `refunds.items.processing_at` — `timestamp`

      When refund processing began. Omitted until processing starts.

    - `refunds.items.reason` — `enum`

      Overall refund reason, such as `"item_returned"` , `"order_canceled"` , or `"requested_by_customer"` .

    - `refunds.items.reason_details` — `string`

      Overall explanation. Omitted when not provided.

    - `refunds.items.reference` — `string`

      Your reconciliation reference. Omitted when not provided.

    - `refunds.items.status` — `enum`

      Current state: `"canceled"` , `"failed"` , `"pending"` , `"processing"` , or `"succeeded"` .

    - `refunds.items.succeeded_at` — `timestamp`

      When the refund entered the `"succeeded"` state. Omitted otherwise.

    - `refunds.items.total` — `object`

      Sum of the requested line-item refund amounts.

      - `refunds.items.total.currency` — `string`

        Lowercase currency code.

      - `refunds.items.total.value` — `integer`

        Positive amount in the smallest currency unit.

- `reference` — `string`

  Public order reference. Omitted when unset.

- `sealed_at` — `timestamp`

  When the order was finalized and its economic fields were sealed for
  payment. A qualifying update can reopen it before payment activity starts.

- `shipping`

  Present when shipping details were supplied. The current order response does not expose nested shipping fields.

- `status` — `string`

  Current order state:
  `"preparing"`, `"requires_payment"`, `"paid"`,
  `"completed"`,
  `"canceled"`,
  `"expired"`, or
  `"unknown"`.

## Create an order

Create a new order for a first-time or returning customer, and decide whether to charge it now or later. Product line items can be fully inline, or they can reuse products and prices you already keep in your catalog.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

> **Note:**
>
> Clients should treat the published route in this reference as authoritative
> and should not construct alternative order-creation paths.

### Rules

- Exactly one of `customer_id` or `customer_data` is required.
- Set `execute_payment` to `true` only when a payment method is attached (`payment_method_id` or `payment_method_data`). Omit it or pass `false` to create the order first and charge it later.
- Orders can contain at most 64 line items.
- Every line item in the request must use the same currency.
- Order totals are capped by currency: `"ghs"` orders can total up to 100,000 in the currency's smallest unit, and all other supported currencies can total up to 50,000 in the currency's smallest unit.
- If your business needs higher order limits, contact [support](mailto:support@inttegro.com) before sending larger orders.
- Product line items support three valid shapes: inline product data, `line_items[].product.product_id` plus explicit `line_items[].product.price`, or `line_items[].product.product_id` plus `line_items[].product.price_id`.
- When you send `line_items[].product.product_id`, Inttegro snapshots the current catalog product onto the order. Do not combine it with inline product fields such as `line_items[].product.name`, `line_items[].product.type`, `line_items[].product.about`, `line_items[].product.reference`, `line_items[].product.tax_code`, or `line_items[].product.custom_data`.
- When you send `line_items[].product.product_id`, you must also send either `line_items[].product.price` or `line_items[].product.price_id`. Do not send both. Inttegro does not infer the amount from the product's default unit price.
- Order-line IDs are generated by Inttegro. Do not send a product line's `id`; any `id` supplied inside a fee or shipping input is not preserved in the created order.
- `checkout_settings.redirect_url` and `checkout_settings.cancel_url` must be HTTP or HTTPS URLs and must not already contain an `order_id` query parameter. Inttegro appends the created order ID to the final redirect.
- When provided, `receipt_number` is trimmed, must satisfy the same configured length limits as `number`, and does not need to be unique.

### Required attributes

- `line_items` — `array`

  Cart contents. Provide at least one line item per order.

  - `line_items.type` — `string`

    Discriminator for each entry: `"product"`, `"fee"`, or `"shipping"`. Matches the schemas in our OpenAPI spec.

  - `line_items.product` — `object`

    Required when `line_items[].type` is `"product"`. Use one of three shapes: inline product data, `line_items[].product.product_id` with explicit `line_items[].product.price`, or `line_items[].product.product_id` with `line_items[].product.price_id`.

    - `line_items.product.about` — `string`

      Marketing copy or long-form description. Only used for inline product data.

    - `line_items.product.category` — `string`

      Product category. Only used for inline product data.

    - `line_items.product.custom_data` — `object`

      Key-value strings for your own custom data. Only used for inline product data.

    - `line_items.product.name` — `string`

      Customer-facing label for the product. Only used for inline product data.

    - `line_items.product.price` — `object`

      Per-unit price. Use this for inline product data or when overriding the amount for a catalog-backed product line item.

      - `line_items.product.price.currency` — `string`

        Lowercase ISO 4217 currency code. Supported values for order creation are `"ghs"`, `"usd"`, `"gbp"`, `"eur"`, and `"cny"`.

      - `line_items.product.price.value` — `integer`

        Amount in the smallest currency unit (pesewas, cents, etc.).

    - `line_items.product.price_id` — `string`

      Existing catalog price to use for this line item. It must belong to the same product referenced by `line_items[].product.product_id`. Do not combine this with `line_items[].product.price`.

    - `line_items.product.product_id` — `string`

      Existing catalog product to snapshot onto the order line item.

    - `line_items.product.quantity` — `integer`

      Number of units being purchased (minimum 1). Required for every product line item shape.

    - `line_items.product.reference` — `string`

      Your SKU or internal reference. Only used for inline product data.

    - `line_items.product.tax_code` — `string`

      Tax classification code for this item. Only used for inline product data.

    - `line_items.product.type` — `string`

      `"cause"`, `"custom"`, `"digital"`, `"physical"`, `"service"`, or `"voucher"`. Only used for inline product data.

  - `line_items.fee` — `object`

    Required when `line_items[].type` is `"fee"`. Use this for service or technology charges.

    - `line_items.fee.label` — `string`

      Customer-facing label, e.g., "Service Fee".

    - `line_items.fee.tax_code` — `string`

      Tax classification code for this fee.

    - `line_items.fee.description` — `string`

      Explain why the fee is being charged.

    - `line_items.fee.amount` — `object`

      Fee amount, using AmountParams.

      - `line_items.fee.amount.currency` — `string`

        Lowercase ISO 4217 currency code.

      - `line_items.fee.amount.value` — `integer`

        Amount in the smallest currency unit.

  - `line_items.shipping` — `object`

    Required when `line_items[].type` is `"shipping"`. Captures fulfillment charges.

    - `line_items.shipping.tax_code` — `string`

      Tax classification code for the shipping fee.

    - `line_items.shipping.fee` — `object`

      Shipping cost, using AmountParams.

      - `line_items.shipping.fee.currency` — `string`

        Lowercase ISO 4217 currency code.

      - `line_items.shipping.fee.value` — `integer`

        Amount in the smallest currency unit.

- `customer_data`

  Inline customer profile for first-time buyers. Mutually exclusive with customer\_id.

  - `customer_data.name` — `string`

    Full customer name exactly as it should appear on invoices and receipts.

  - `customer_data.email_address` — `string`

    Primary email—used for invoices, receipts, and payment notifications.

  - `customer_data.phone_number` — `string`

    Phone number in international format so we can deliver OTPs or status updates.

  - `customer_data.custom_data` — `object`

    Free-form key/value strings for attaching custom attributes (e.g., customer segment).

- `customer_id` — `string`

  Reference an existing customer. Mutually exclusive with `customer_data`.

### Product line item shapes

Use the shape that matches how you manage your catalog and pricing:

### Inline

Define the product and its price directly on this order.

```json
{
  "line_items": [
    {
      "type": "product",
      "product": {
        "name": "Utility Sneakers",
        "type": "physical",
        "quantity": 1,
        "price": {
          "currency": "ghs",
          "value": 20000
        }
      }
    }
  ]
}
```

### Set price

Reference a catalog product and set its price for this order.

```json
{
  "line_items": [
    {
      "type": "product",
      "product": {
        "product_id": "prod_abc123xyz",
        "quantity": 2,
        "price": {
          "currency": "usd",
          "value": 4100
        }
      }
    }
  ]
}
```

### Price ID

Reference a catalog product and one of its saved prices.

```json
{
  "line_items": [
    {
      "type": "product",
      "product": {
        "product_id": "prod_abc123xyz",
        "price_id": "pr_xyz789",
        "quantity": 2
      }
    }
  ]
}
```

When you reference `line_items[].product.product_id`, Inttegro snapshots the product data onto the order at creation time. Later edits to the catalog product or price do not rewrite an order that already exists. You can also mix catalog-backed and inline product line items in the same order, as long as every line item uses the same currency.

The complete HTTP examples below use inline product data. If you already keep products and prices in your catalog, replace the `line_items[].product` payload with either catalog-backed shape shown above.

### Optional attributes

- `request_meta`

  Request-specific controls that do not change the order being created.

  - `request_meta.idempotency_key` — `string`

    Optional request key for this logical order creation.

- `payment_method_id` — `string`

  ID of a saved payment method to charge. Only works with `customer_id`—the method must belong to that customer.

- `receipt_number` — `string`

  Optional merchant-supplied receipt reference for reconciliation. Inttegro trims whitespace, applies the same configured length validation used for `number`, and does not enforce uniqueness.

- `statement_descriptor` — `string`

  Exact descriptor shown on the customer's bank or mobile money statement. Mutually exclusive with `statement_descriptor_prefix`.

- `statement_descriptor_prefix` — `string`

  Static prefix, between 2 and 10 characters, used to build the descriptor as `prefix*order_id`. Inttegro appends enough characters from the generated order ID to fit the final descriptor limit.

- `payment_method_data`

  Inline payment details for new payment instruments.

  - `payment_method_data.type` — `enum`

    Currently only `"mobile_money"` is supported for inline collection.

  - `payment_method_data.mobile_money` — `object`

    Required when `payment_method_data.type` is `"mobile_money"`. Provides wallet details.

    - `payment_method_data.mobile_money.network` — `enum`

      Wallet network: `"airtel"`, `"mtn"`, `"telecel"`, or `"vodafone"`.

    - `payment_method_data.mobile_money.account_number` — `string`

      Subscriber MSISDN in international format (e.g., +23354...).

- `execute_payment` — `boolean`

  Whether to charge the order immediately. Defaults to `false`—you'll call `/orders/pay` later.

- `finalize` — `boolean`

  Set to `true` to seal the order and generate its hosted invoice. When omitted or `false`, an order without executable payment details remains a draft and its response omits `order.invoice`.

- `invoice_settings`

  Optional customer-facing invoice content.

  - `invoice_settings.custom_data` — `object`

    String key-value data attached to the invoice.

  - `invoice_settings.footer` — `string`

    Text shown at the bottom of the invoice.

  - `invoice_settings.memo` — `string`

    Customer-facing invoice note.

  - `invoice_settings.number` — `string`

    Invoice number.

- `payment_due_after` — `timestamp`

  RFC 3339 timestamp for when payment is due. The order response exposes it as `order.payment_due_at` when set.

- `custom_data` — `object`

  Arbitrary string key-value pairs for application-specific needs. Attach internal order IDs, fulfillment workflows, tracking identifiers, or any metadata your system requires. Maximum size when serialized: 25 KB. See the [Custom Data guide](https://studio.inttegro.com/machine/curl/api/custom-data.md) for best practices.

- `checkout_settings`

  Checkout configuration for this order. Strongly recommended to provide both checkout\_settings.redirect\_url and checkout\_settings.cancel\_url for a delightful customer experience.

  - `checkout_settings.redirect_url` — `string`

    URL where customers land after completing payment. Include order tracking parameters to show order status and next steps.

  - `checkout_settings.cancel_url` — `string`

    URL where customers land if they abandon checkout without paying. Use this to show incomplete order details or offer alternative payment methods.

- `billing_details`

  Contact info for invoicing and receipt delivery.

  - `billing_details.name` — `string`

    Billing contact name.

  - `billing_details.email_address` — `string`

    Billing email address.

  - `billing_details.phone_number` — `string`

    Billing phone number.

  - `billing_details.address` — `object`

    Optional postal address for invoices.

    - `billing_details.address.name` — `string`

      Recipient name if different from customer.

    - `billing_details.address.phone_number` — `string`

      Contact phone for delivery or verification.

    - `billing_details.address.line1` — `string`

      Street address line 1.

    - `billing_details.address.line2` — `string`

      Street address line 2 (optional).

    - `billing_details.address.city` — `string`

      City or town.

    - `billing_details.address.region` — `string`

      State, province, or region.

    - `billing_details.address.country` — `string`

      Country name.

    - `billing_details.address.post_code` — `string`

      Postal or ZIP code.

- `shipping`

  Optional shipping destination for physical fulfillment.

  - `shipping.address` — `object`

    Where the package should go. Uses AddressParams.

    - `shipping.address.name` — `string`

      Recipient name.

    - `shipping.address.phone_number` — `string`

      Phone number for delivery coordination.

    - `shipping.address.line1` — `string`

      Street address line 1.

    - `shipping.address.line2` — `string`

      Street address line 2 (optional).

    - `shipping.address.city` — `string`

      City or town.

    - `shipping.address.region` — `string`

      State, province, or region.

    - `shipping.address.country` — `string`

      Country name.

    - `shipping.address.post_code` — `string`

      Postal or ZIP code.

- `payout_settings`

  Order-specific payout configuration. Overrides your application-level payout settings for this order—useful for marketplace scenarios where different orders route to different sellers.

  - `payout_settings.destination` — `object`

    Where funds from this order should be paid out.

    - `payout_settings.destination.financial_account_id` — `string`

      ID of an existing financial account to receive the payout. The account must exist and have push capability enabled. Create financial accounts via the dashboard or \[Financial Accounts API]\(/api/financial-accounts).

  - `payout_settings.enable_fx` — `boolean`

    Optional compatibility flag. Omit it or set it to `false`; `true` is rejected because cross-currency payouts are not currently available.

**Request — POST /orders/create**

```bash
curl https://api.inttegro.com/orders/create \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request_meta": {
    "idempotency_key": "order_checkout_ORDER-NUMBER-2"
  },
  "number": "ORDER-NUMBER-2",
  "receipt_number": "RCPT-NUMBER-2",
  "statement_descriptor": "STMTDESC",
  "execute_payment": true,
  "finalize": true,
  "checkout_settings": {
    "redirect_url": "https://google.com/thank-you",
    "cancel_url": "https://google.com/order-cancelled"
  },
  "customer_data": {
    "name": "Customer Name",
    "email_address": "customer@example.com",
    "phone_number": "+233242058841"
  },
  "payment_method_data": {
    "type": "mobile_money",
    "mobile_money": {
      "network": "mtn",
      "account_number": "0242057831"
    }
  },
  "line_items": [
    {
      "type": "product",
      "product": {
        "type": "physical",
        "name": "Utility Sneakers",
        "quantity": 1,
        "price": {
          "currency": "ghs",
          "value": 20000
        }
      }
    }
  ],
  "billing_details": {
    "name": "Customer Name",
    "email_address": "customer@example.com",
    "phone_number": "+233242058841",
    "address": {
      "name": "Customer Name",
      "phone_number": "+233242058841",
      "line1": "23 Adenta High Street",
      "town": "Accra",
      "region": "Greater Accra",
      "country": "GH"
    }
  }
}'
```

```json
{
  "order": {
    "id": "or_f8y1p1",
    "number": "ORDER-NUMBER-2",
    "receipt_number": "RCPT-NUMBER-2",
    "status": "requires_payment",
    "initiated_at": "2025-01-13T10:00:00Z",
    "sealed_at": "2025-01-13T10:00:01Z",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "oli_utility",
            "type": "physical",
            "tax_code": "apparel",
            "name": "Utility Sneakers",
            "price": { "currency": "ghs", "value": 20000 },
            "quantity": 1,
            "reference": "utility-sneakers"
          }
        }
      ],
      "total": { "currency": "ghs", "value": 20000 }
    },
    "payment": {
      "id": "py_3deNYy",
      "statement_descriptor": "STMTDESC",
      "payment_method": {
        "id": "pm_wveyHj",
        "customer_id": "cu_a1b2c3",
        "type": "mobile_money",
        "mobile_money": {
          "account_number": "****7831",
          "last4": "7831",
          "network": "mtn"
        },
        "created_at": "2025-01-13T10:00:00Z",
        "verified": false
      },
      "amount": { "currency": "ghs", "value": 20000 },
      "next_action": {
        "type": "confirm_payment",
        "confirm_payment": {
          "confirmed": false,
          "expires_at": "2025-01-13T10:08:00Z",
          "scheme": "inttegro_defined_auth",
          "request": {
            "id": "token_req_1",
            "recipient": "0242057831",
            "sent_via": "sms",
            "token_size": 6,
            "sender_id": "zverify"
          },
          "status": "pending"
        }
      },
      "status": "requires_action",
      "initiated_at": "2025-01-13T10:00:00Z"
    },
    "invoice": {
      "format": {
        "web": { "url": "https://pages.inttegro.com/invoices/or_f8y1p1" },
        "pdf": { "url": "https://pages.inttegro.com/invoices/or_f8y1p1/pdf" }
      }
    },
    "customer": {
      "id": "cu_a1b2c3",
      "email_address": "customer@example.com",
      "phone_number": "+233242058841",
      "guest": false,
      "name": "Customer Name"
    }
  }
}
```

## Search orders

Search orders by customer, invoice, or other remembered text, and narrow the
result set by status. Results are discovery summaries: use the returned
order ID with [Lookup an order](#lookup-an-order) before fulfillment,
collection, cancellation, or any other state-dependent action.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

## Use order search for discovery, then read the order

- Send `text`,
  `filters`,
  or both. This route accepts only the wire field name
  `status` as a filter or facet; field names are unqualified.
- Treat `results`
  as discovery summaries. Read the canonical order by
  `results[].resource.id`
  before relying on payment, fulfillment, refund, or amount data.
- When `has_more`
  is true, replay the same request with
  `next_cursor`
  as the request cursor. Never decode, edit, or combine cursors.
- `total`
  and facets describe the complete search result set;
  `result_count`
  describes the current page. Check
  `total.relation`.
- Inspect `freshness`
  before presenting search data as current. Use order lookup whenever stale
  data could change a user-visible or monetary action.

### Request attributes

- `cursor` — `string`

  Opaque continuation cursor returned by the previous page. Replay the
  same request and add this value for the next page.

- `facets` — `array`

  Fields to group and count. This route accepts only status.

  - `facets.field` — `string` — required

    Route-local field name. Use status.

  - `facets.limit` — `integer`

    Maximum buckets, from 1 through 50. Defaults to 10.

- `filters` — `array`

  Exact status constraints.

  - `filters.field` — `string` — required

    Route-local field name. Use status.

  - `filters.operator` — `enum` — required

    eq for one value or in for any supplied value.

  - `filters.values` — `array` — required

    One value for eq; one through 20 values for in.

- `page_size` — `integer`

  Results per page, from `1` through `100`. Defaults to `20`.

- `sort`

  Result ordering.

  - `sort.direction` — `enum` — required

    asc or desc. Relevance supports desc only.

  - `sort.field` — `enum` — required

    relevance or updated\_at.

- `text` — `string`

  Search text, from 1 through 512 characters. Supply search text, exact
  filters, or both.

### Response

Returns a typed search page with discovery summaries, requested facet
counts, page and total counts, an optional `next_cursor`,
and `freshness` metadata. Read the canonical order before
acting on a result.

**Request — POST /orders/search**

```bash
curl https://api.inttegro.com/orders/search \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "INV-1042" }'
```

```json
{
  "search": {
    "results": [
      {
        "resource": { "type": "order", "id": "or_48ZW7BGvYUBWc1i6" },
        "title": "INV-1042",
        "summary": "Ama Mensah",
        "status": "paid",
        "amount": { "currency": "ghs", "value": 20000 },
        "updated_at": "2026-09-21T10:30:00Z"
      }
    ]
  }
}
```

## Pay for an order

Start or retry payment on an existing order without recreating it. This operation finalizes an open draft before collection. Four ways to use it:

- **Already has a payment method**: Just send `order_id`—we'll charge the attached method.
- **Swap to a different saved method**: Send `order_id` and `payment_method_id`.
- **Use a new payment method once**: Send `order_id` and `payment_method_data`.
- **Offline payment**: Send `order_id` and set `paid_out_of_band` to `true`—this marks the payment as received outside Inttegro (cash, bank transfer, check). Complete the order separately when fulfillment is done.

### Rules

- Pass either `payment_method_id`, `payment_method_data`, or `paid_out_of_band`, never multiple.
- `paid_out_of_band` is mutually exclusive with payment method parameters.
- Any `payment_method_id` must belong to the order's customer.
- The order must be `"preparing"` or `"requires_payment"`. Paid, completed, canceled, expired, and unknown orders are not payable.
- A successful response can still require customer action. Inspect `order.payment.status` and `order.payment.next_action`; do not infer success from HTTP `200` alone.

### Required attributes

- `order_id` — `string`

  ID of the order to pay.

### Optional attributes

- `payment_method_id` — `string`

  ID of a saved payment method belonging to this order's customer.

- `payment_method_data`

  New payment method details to charge.

  - `payment_method_data.type` — `enum`

    Currently only `"mobile_money"` is accepted when supplying inline details.

  - `payment_method_data.mobile_money` — `object`

    Required when `payment_method_data.type` is `"mobile_money"`. Uses MobileMoneyParams.

    - `payment_method_data.mobile_money.network` — `enum`

      Wallet network: `"airtel"`, `"mtn"`, `"telecel"`, or `"vodafone"`.

    - `payment_method_data.mobile_money.account_number` — `string`

      Wallet MSISDN in international or local format (we normalize it).

- `paid_out_of_band` — `boolean`

  Set to `true` when payment was received outside Inttegro (cash, bank transfer, check). Marks the payment as paid offline and completes the payment immediately. Mutually exclusive with `payment_method_id` and `payment_method_data`. Defaults to `false`.

**Request — POST /orders/pay**

```bash
curl https://api.inttegro.com/orders/pay \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
  "payment_method_data": {
    "type": "mobile_money",
    "mobile_money": {
      "network": "mtn",
      "account_number": "0544998605"
    }
  }
}'
```

```json
{
  "order": {
    "id": "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
    "initiated_at": "2026-08-28T09:30:00Z",
    "status": "requires_payment",
    "customer": {
      "guest": true,
      "id": "cu_4pL8rN",
      "name": "Gloria Kesewaa"
    },
    "payment": {
      "amount": { "currency": "ghs", "value": 20000 },
      "id": "py_3deNYy",
      "initiated_at": "2026-08-28T09:30:01Z",
      "statement_descriptor": "INTTEGRO",
      "status": "requires_action"
    }
  }
}
```

## Confirm a payment

Submit the confirmation token for a specific payment and confirmation request. Read `payment_id` from `order.payment.id` and `confirmation_id` from `order.payment.next_action.confirm_payment.request.id` in the preceding create, pay, or request-confirmation response. The response always uses the `order` envelope; an actionable error can include both `order` and an `error` object.

### Required attributes

- `confirmation_id` — `string`

  ID of the confirmation request that issued the token.

- `order_id` — `string`

  ID of the order being paid.

- `payment_id` — `string`

  ID of the payment attached to the order.

- `token` — `string`

  Confirmation token supplied by the customer.

**Request — POST /orders/confirm\_payment**

```bash
curl https://api.inttegro.com/orders/confirm_payment \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmation_id": "otc_req_8Ks2Vn",
    "order_id": "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
    "payment_id": "py_3deNYy",
    "token": "302673"
  }'
```

```json
{
  "order": {
    "customer": {
      "guest": true,
      "id": "cu_4pL8rN",
      "name": "Gloria Kesewaa"
    },
    "id": "or_JoPtqOmsjgZKwkPvqTrqGsopu07wfC7ttoWqmfwt",
    "initiated_at": "2026-08-28T09:30:00Z",
    "status": "paid"
  }
}
```

## Request confirmation

Some payment methods—especially mobile money—require the customer to confirm with an OTP. Call this to send (or resend) the confirmation token.

**Request — POST /orders/request\_confirmation**

```bash
curl https://api.inttegro.com/orders/request_confirmation \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi"
}'
```

```json
{
  "order": {
    "id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
    "status": "requires_payment",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "oli_fNa3i3QPkt4yU5FQHoM042tRFAdthCbcRZJdZnrl",
            "reference": "SKU-GLOVES-001",
            "about": "Tollo victoria advenio crudelis facere crudelis. Aequitas voco correptius suspendo fuga demergo. Angelus texo pecto.",
            "custom_data": {
              "size": "56",
              "color": "blue"
            },
            "tax_code": "gold",
            "name": "Awesome Fresh Gloves",
            "type": "digital",
            "price": {
              "currency": "ghs",
              "value": 20
            },
            "quantity": 1
          }
        },
        {
          "type": "product",
          "product": {
            "id": "oli_deeYHxzydDJWU1w9YCjOvgDirYv37WyYmI9MhdEA",
            "reference": "SKU-TABLE-001",
            "about": "Sunt astrum verecundia cenaculum. Asporto voluptas mollitia voluptate vaco concedo bellum clam aufero taedium. Admiratio cohibeo ullus comis alter.",
            "custom_data": {
              "size": "56",
              "color": "blue"
            },
            "tax_code": "black",
            "name": "Awesome Fresh Table",
            "type": "digital",
            "price": {
              "currency": "ghs",
              "value": 100
            },
            "quantity": 2
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 220
      }
    },
    "initiated_at": "2025-04-09T00:11:47.74569+01:00",
    "sealed_at": "2025-04-09T00:11:48.374979+01:00",
    "payment": {
      "id": "py_8QNM4ujclxXUDZBnL9ujyPfMG4Bk6ZRMBeRtc99l",
      "statement_descriptor": "STATEMENT",
      "payment_method": {
        "id": "pm_acA9cJRhjZHw1Gs4p39fKTbp1AgsFjhBk1AwIuVf",
        "customer_id": "cu_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
        "type": "mobile_money",
        "mobile_money": {
          "network": "mtn",
          "account_number": "****7831",
          "last4": "7831"
        },
        "created_at": "2025-04-09T00:11:47.873476+01:00",
        "verified": false
      },
      "amount": {
        "currency": "ghs",
        "value": 220
      },
      "next_action": {
        "type": "confirm_payment",
        "confirm_payment": {
          "expires_at": "0001-01-01T00:00:00Z",
          "scheme": "inttegro_defined_auth",
          "request": {
            "id": "Jmjup0uRSVI2LvllHfdJ",
            "recipient": "0242057831",
            "sent_via": "sms",
            "token_size": 6,
            "sender_id": "zverify"
          },
          "confirmed": false,
          "status": "pending_verification"
        }
      },
      "status": "requires_action",
      "initiated_at": "2025-04-09T00:11:47.995076+01:00"
    },
    "customer": {
      "id": "cu_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
      "guest": false,
      "email_address": "gloria@kesewaa.co",
      "phone_number": "+233544998605",
      "name": "Gloria Kesewaa"
    }
  }
}
```

## Update an order

Update mutable fields on an existing order and get back the same response shape as [Lookup an order](https://studio.inttegro.com/machine/curl/api/orders.md#lookup-an-order). Use this endpoint for three distinct cases: revising an open draft, reopening a sealed order so it becomes editable again, or applying changes and resealing in the same request.

### What you can change

- Replace the full `line_items` collection
- Change the order `number`
- Set or change the order `receipt_number`
- Change the payment `statement_descriptor`
- Attach a different saved `payment_method_id`
- Tokenize and attach new inline `payment_method_data`
- Remove the attached payment method with `clear_payment_method`
- Replace order-level `custom_data`
- Replace or clear customer-facing `invoice_settings`
- Explicitly open, seal, or reseal the order with `finalize`

### Rules

- Include at least one mutable field besides `order_id`.
- `line_items` is a full replacement field, not a sparse merge, and it cannot be empty when provided.
- If you replace `line_items`, the updated order must stay within the current order limits: at most 64 line items, up to 100,000 for `"ghs"`, and up to 50,000 for all other supported currencies. Contact [support](mailto:support@inttegro.com) if you need these limits increased.
- `payment_method_id`, `payment_method_data`, and `clear_payment_method` are mutually exclusive.
- `payment_method_data` currently supports only `"mobile_money"` for order updates.
- Completed, paid, canceled, and expired orders cannot be updated.
- `custom_data` is metadata-only. Updating it does not require reopen / reseal by itself.
- Omit `receipt_number` to leave it unchanged. When provided, Inttegro trims it and requires a different non-empty value within the same configured length limits as `number`. It cannot be cleared once set, and receipt numbers are not unique.
- If payment confirmation or execution has already started, Inttegro rejects edits that change economics, payment configuration, or require reopening the order.
- When mutating seal-sensitive fields on a sealed order, you must provide `finalize` explicitly:
  - `finalize` set to `false` reopens the order and leaves it editable.
  - `finalize` set to `true` applies the changes and seals the order again in the same request.

### Required attributes

- `order_id` — `string`

  The unique identifier of the order to update.

### Optional attributes

- `clear_payment_method` — `boolean`

  Clears the currently attached payment method. Mutually exclusive with `payment_method_id` and `payment_method_data`.

- `custom_data` — `object`

  Replacement order-level custom data. Provide an empty object to clear the current value.

- `finalize` — `boolean`

  Explicit seal decision. Use `false` to reopen a sealed order and leave it editable, or `true` to seal or reseal the order after applying the requested changes.

- `invoice_settings`

  Full replacement for customer-facing invoice content. Send an empty object to clear the current settings.

  - `invoice_settings.custom_data` — `object`

    String key-value data attached to the invoice.

  - `invoice_settings.footer` — `string`

    Text shown at the bottom of the invoice.

  - `invoice_settings.memo` — `string`

    Customer-facing invoice note.

  - `invoice_settings.number` — `string`

    Invoice number.

- `line_items` — `array`

  Full replacement for the order's current line items. Use the same line-item schema as [Create an order](https://studio.inttegro.com/machine/curl/api/orders.md#create-an-order).

- `number` — `string`

  Replacement order number.

- `payment_method_data`

  New payment method details to tokenize and attach to the order.

  - `payment_method_data.mobile_money` — `object`

    Required when `payment_method_data.type` is `"mobile_money"`. Provide `payment_method_data.mobile_money.network` and `payment_method_data.mobile_money.account_number`.

  - `payment_method_data.type` — `string`

    Currently only `"mobile_money"` is supported for order updates.

- `payment_method_id` — `string`

  ID of a saved payment method to attach to the order.

- `receipt_number` — `string`

  Replacement receipt reference. Must be a different non-empty value when provided.

- `statement_descriptor` — `string`

  Replacement payment statement descriptor for the order's payment.

- `statement_descriptor_prefix` — `string`

  Static prefix, between 2 and 10 characters, used to build the replacement descriptor as `prefix*order_id`. Mutually exclusive with `statement_descriptor`.

### Response shape

- Returns the same `order` object as [Lookup an order](https://studio.inttegro.com/machine/curl/api/orders.md#lookup-an-order).
- If `finalize` is `false`, `order.sealed_at` and `order.invoice` are cleared until the order is sealed again.
- If `finalize` is `true`, Inttegro returns the regenerated invoice and the updated payment amount.
- The returned order object includes top-level `order.custom_data` when present.
- The returned order object includes top-level `order.receipt_number` when set.

**Request — POST /orders/update**

```bash
curl https://api.inttegro.com/orders/update \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
  "receipt_number": "RCPT-2025-041-REV1",
  "line_items": [
    {
      "type": "product",
      "product": {
        "name": "Quarterly support retainer",
        "type": "digital",
        "price": {
          "currency": "ghs",
          "value": 15000
        },
        "quantity": 1
      }
    },
    {
      "type": "fee",
      "fee": {
        "label": "Service fee",
        "amount": {
          "currency": "ghs",
          "value": 500
        }
      }
    }
  ],
  "statement_descriptor": "ORDER REVISION",
  "custom_data": {
    "channel": "dashboard",
    "edited_by": "ops"
  },
  "finalize": true
}'
```

```json
{
  "order": {
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "number": "ORDER-2025-REV2",
    "receipt_number": "RCPT-2025-041-REV1",
    "status": "requires_payment",
    "initiated_at": "2025-05-01T10:00:00Z",
    "sealed_at": "2025-05-01T10:04:00Z",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "oli_VNojv2eX7F9H3mQ5pZr2Ld8",
            "name": "Quarterly support retainer",
            "type": "digital",
            "price": {
              "currency": "ghs",
              "value": 15000
            },
            "quantity": 1
          }
        },
        {
          "type": "fee",
          "fee": {
            "id": "oli_7Nf0wP4sT8kJ2qM6xCz9Rb1",
            "label": "Service fee",
            "amount": {
              "currency": "ghs",
              "value": 500
            }
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 15500
      }
    },
    "payment": {
      "id": "py_3PjQ7mVn2cX5kL8rT1sW4yH6uB9dF0gN",
      "statement_descriptor": "ORDER REVISION",
      "payment_method": {
        "id": "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
        "customer_id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
        "type": "mobile_money",
        "mobile_money": {
          "network": "mtn",
          "account_number": "****0087",
          "last4": "0087"
        },
        "created_at": "2025-05-01T10:00:00Z",
        "verified": true,
        "verified_at": "2025-05-01T10:00:15Z"
      },
      "amount": {
        "currency": "ghs",
        "value": 15500
      },
      "status": "requires_action",
      "initiated_at": "2025-05-01T10:00:00Z"
    },
    "invoice": {
      "format": {
        "web": {
          "url": "https://pages.inttegro.com/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
        },
        "pdf": {
          "url": "https://pages.inttegro.com/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt/pdf"
        }
      }
    },
    "customer": {
      "id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
      "guest": false,
      "email_address": "ops@example.com",
      "phone_number": "+233559714200",
      "name": "Anita Segnom"
    },
    "custom_data": {
      "channel": "dashboard",
      "edited_by": "ops"
    }
  }
}
```

## Finalize an order

Finalize a draft to seal its line items and total for payment. The response exposes the hosted invoice URLs you can share with the customer.

### What finalization means

Finalizing an order is the transition from `"preparing"` to `"requires_payment"`. Before finalization, you can replace line items and change supported order or payment settings. After finalization:

- **Line items freeze**: No additions, removals, or quantity changes unless you later reopen the order with [Update an order](https://studio.inttegro.com/machine/curl/api/orders.md#update-an-order)
- **Totals lock**: The amount due becomes fixed until the order is reopened
- **Invoice generates**: A viewable invoice with web and PDF formats
- **Checkout activates**: The hosted payment page becomes accessible
- **Payment readiness**: The order can accept payment attempts

Use this endpoint when you've finished building the cart and want to present it to the customer for payment. The response includes invoice URLs and the `order.sealed_at` timestamp marking when the order was finalized. Finalizing an already sealed order is safe and leaves the existing state unchanged.

### Required attributes

- `order_id` — `string`

  The unique identifier of the order to finalize.

**Request — POST /orders/finalize**

```bash
curl https://api.inttegro.com/orders/finalize \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'
```

```json
{
  "order": {
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "number": "ORDER-12345",
    "status": "requires_payment",
    "sealed_at": "2025-01-25T10:30:00Z",
    "initiated_at": "2025-01-25T10:25:00Z",
    "expires_at": "2025-02-01T10:25:00Z",
    "customer": {
      "id": "cu_abc123def456",
      "guest": false,
      "name": "Akua Mensah"
    },
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "oli_123",
            "name": "Premium Widget",
            "quantity": 2,
            "price": {
              "currency": "ghs",
              "value": 5000
            }
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 10000
      }
    },
    "invoice": {
      "number": "ORDER-12345",
      "format": {
        "web": {
          "url": "https://pages.inttegro.com/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
        },
        "pdf": {
          "url": "https://pages.inttegro.com/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt/pdf"
        }
      }
    }
  }
}
```

## Send an invoice

Send an order's hosted invoice link to its customer. Inttegro uses the contact details saved for that customer: when both a phone number and email address are available, it sends the link by SMS and email; otherwise it uses the available channel.

The order must be finalized and its invoice must be ready to send. For a draft order, first use [Finalize an order](https://studio.inttegro.com/machine/curl/api/orders.md#finalize-an-order).

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request body

- `order_id` — `string` — required

  The order whose hosted invoice link should be sent.

### Response

Returns the current `order` plus a `delivery` object. If one channel succeeds and another fails, the endpoint may return HTTP `207` with both `delivery.sent_channels` and `delivery.failed_channels`.

- `delivery`

  Delivery result for the hosted invoice link.

  - `delivery.deliveries` — `array`

    Accepted message sends.

    - `delivery.deliveries.channel` — `string`

      `"sms"` or `"email"`.

    - `delivery.deliveries.chime_id` — `string`

      Created delivery ID.

  - `delivery.document_kind` — `string`

    `"invoice"`.

  - `delivery.document_url` — `string`

    Hosted invoice URL sent to the customer.

  - `delivery.failed_channels` — `array`

    Channels that failed to send.

  - `delivery.failures` — `array`

    Failed channel details.

    - `delivery.failures.channel` — `string`

      `"sms"` or `"email"`.

    - `delivery.failures.error` — `string`

      Delivery error.

  - `delivery.sent_channels` — `array`

    Channels accepted for delivery.

Invoice delivery can return `draft_mode_order_has_no_invoice`, `order_delivery_auth_failed`, `order_delivery_contact_missing`, `order_delivery_failed`, or `order_not_found`.

**Request — POST /orders/send\_invoice**

```bash
curl https://api.inttegro.com/orders/send_invoice \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-invoice-or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'
```

```json
{
  "order": {
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "status": "requires_payment",
    "initiated_at": "2025-05-01T10:00:00Z",
    "customer": {
      "id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
      "guest": false,
      "name": "Anita Segnom"
    }
  },
  "delivery": {
    "document_kind": "invoice",
    "document_url": "https://pages.inttegro.com/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "sent_channels": ["sms", "email"],
    "deliveries": [
      {
        "channel": "sms",
        "chime_id": "chm_sms_123"
      },
      {
        "channel": "email",
        "chime_id": "chm_email_456"
      }
    ]
  }
}
```

## Send a receipt

Send the hosted receipt link for an existing paid order. Inttegro uses the same fan-out rules as invoice delivery: SMS and email when both customer contacts exist, otherwise whichever contact method is available.

Receipt delivery is available only after the order is paid. The link points to the hosted receipt path, such as `/invoices/'{order_id}'/receipt`; do not use the invoice PDF path for receipt delivery.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request body

- `order_id` — `string` — required

  The paid order whose hosted receipt link should be sent.

### Response

Returns the current `order` plus a `delivery` object. If one channel succeeds and another fails, the endpoint may return HTTP `207` with both `delivery.sent_channels` and `delivery.failed_channels`.

- `delivery`

  Delivery result for the hosted receipt link.

  - `delivery.deliveries` — `array`

    Accepted message sends.

    - `delivery.deliveries.channel` — `string`

      `"sms"` or `"email"`.

    - `delivery.deliveries.chime_id` — `string`

      Created delivery ID.

  - `delivery.document_kind` — `string`

    `"receipt"`.

  - `delivery.document_url` — `string`

    Hosted receipt URL sent to the customer.

  - `delivery.failed_channels` — `array`

    Channels that failed to send.

  - `delivery.failures` — `array`

    Failed channel details.

    - `delivery.failures.channel` — `string`

      `"sms"` or `"email"`.

    - `delivery.failures.error` — `string`

      Delivery error.

  - `delivery.sent_channels` — `array`

    Channels accepted for delivery.

Receipt delivery can return `order_delivery_auth_failed`, `order_delivery_contact_missing`, `order_delivery_failed`, `order_not_found`, or `order_receipt_missing`.

**Request — POST /orders/send\_receipt**

```bash
curl https://api.inttegro.com/orders/send_receipt \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-receipt-or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'
```

```json
{
  "order": {
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "status": "paid",
    "initiated_at": "2025-05-01T10:00:00Z",
    "customer": {
      "id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
      "guest": false,
      "name": "Anita Segnom"
    }
  },
  "delivery": {
    "document_kind": "receipt",
    "document_url": "https://pages.inttegro.com/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt/receipt",
    "sent_channels": ["sms"],
    "deliveries": [
      {
        "channel": "sms",
        "chime_id": "chm_sms_789"
      }
    ]
  }
}
```

## Complete an order

Mark an order as completed when the customer has received their items or you've fulfilled the service. This transitions the order to the `"completed"` state, indicating the transaction is fully satisfied.

### When to complete orders

Complete an order when:

- **Physical goods**: Items have been delivered or picked up
- **Digital products**: Files have been downloaded or access granted
- **Services**: Work has been performed and accepted
- **Out-of-band payments**: Cash, check, or bank transfer received offline

The order must have a successful payment before completion, unless you're marking an offline payment by setting `paid_out_of_band` to `true`.

### Out-of-band payments

If the customer paid outside Inttegro (cash, bank transfer, check), set `paid_out_of_band` to `true`. This marks both the payment and order as complete in a single operation. The payment gets marked as paid offline before the order is completed.

Use this for:

- Cash on delivery scenarios
- Bank transfer confirmations
- Check payments that cleared
- Any payment method outside the Inttegro platform

### Required attributes

- `order_id` — `string`

  The unique identifier of the order to complete.

### Optional attributes

- `paid_out_of_band` — `boolean`

  Set to `true` if payment was received outside Inttegro (cash, bank transfer, check). When true, the payment is marked as paid offline before completing the order. Defaults to `false`, which requires the payment to already be in `"paid"` status.

**Request — POST /orders/complete**

```bash
curl https://api.inttegro.com/orders/complete \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'
```

```json
{
  "order": {
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
    "number": "ORDER-12345",
    "status": "completed",
    "completed_at": "2025-01-27T11:00:00Z",
    "sealed_at": "2025-01-25T10:30:00Z",
    "initiated_at": "2025-01-25T10:25:00Z",
    "expires_at": "2025-02-01T10:25:00Z",
    "customer": {
      "id": "cu_abc123def456",
      "guest": false,
      "name": "Akua Mensah"
    },
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "oli_123",
            "name": "Premium Widget",
            "quantity": 2,
            "price": {
              "currency": "ghs",
              "value": 5000
            }
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 10000
      }
    }
  }
}
```

## Lookup an order

Fetch the current order and nested payment state by ID. A missing or inaccessible order returns HTTP `400` with error code `order_not_found`; use the error object rather than checking for `404`.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Required attributes

- `order_id` — `string`

  Order ID from the creation response.

**Request — POST /orders/lookup**

```bash
curl https://api.inttegro.com/orders/lookup \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
}'
```

```json
{
  "order": {
    "line_item_group": {
      "line_items": [
        {
          "product": {
            "id": "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
            "about": "Accedo turba doloremque brevis. Despecto administratio vorax verus odit vinculum. Advoco conforto spiritus debeo careo.",
            "custom_data": {
              "size": "56",
              "some": "custom_data"
            },
            "tax_code": "pink",
            "name": "Gorgeous Granite Salad",
            "type": "physical",
            "price": {
              "currency": "ghs",
              "value": 100
            },
            "quantity": 1
          },
          "type": "product"
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 200
      }
    },
    "initiated_at": "2025-09-14T16:24:41.137708909Z",
    "completed_at": "2025-09-14T16:29:45Z",
    "sealed_at": "2025-09-14T16:24:41.312701813Z",
    "payment": {
      "id": "py_OHFv6I3OZBvB1R46TQQGNxPPtgbPR6CXpQ8En9wl",
      "statement_descriptor": "STATEMENT",
      "payment_method": {
        "id": "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
        "customer_id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
        "type": "mobile_money",
        "mobile_money": {
          "network": "mtn",
          "account_number": "****0087",
          "last4": "0087"
        },
        "created_at": "2025-09-14T16:24:41.171905592Z",
        "verified": true,
        "verified_at": "2025-09-14T16:24:51.171905592Z"
      },
      "latest_attempt": {
        "payment_method_type": "mobile_money",
        "payment_method_id": "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
        "reference": "68c6ecbc3bf0a6548973b598",
        "status": "succeeded",
        "initiated_at": "2025-09-14T16:26:36.627271781Z",
        "succeeded_at": "2025-09-14T16:29:45Z"
      },
      "amount": {
        "currency": "ghs",
        "value": 200
      },
      "status": "paid",
      "initiated_at": "2025-09-14T16:24:41.240462376Z",
      "executed_at": "2025-09-14T16:26:36.626961042Z",
      "paid_at": "2025-09-14T16:29:45Z",
      "balance_transaction": {
        "amount": {
          "currency": "ghs",
          "value": 200
        },
        "created_at": "2025-09-14T16:29:45Z",
        "id": "bt_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN",
        "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
        "paid_at": "2025-09-15T08:00:00Z",
        "payment_id": "py_OHFv6I3OZBvB1R46TQQGNxPPtgbPR6CXpQ8En9wl",
        "payout_id": "po_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN",
        "type": "payment"
      }
    },
    "invoice": {
      "format": {
        "web": {
          "url": "https://pages.inttegro.com/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
        },
        "pdf": {
          "url": "https://pages.inttegro.com/invoices/or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt/pdf"
        }
      }
    },
    "refunds": [
        {
            "id": "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd",
            "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
            "status": "succeeded",
            "total": { "currency": "ghs", "value": 100 },
            "line_items": [
                {
                    "id": "rli_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN",
                    "order_line_item": {
                        "id": "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
                        "product": {
                            "id": "prod_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
                            "name": "Canvas backpack"
                        },
                        "quantity": 1,
                        "type": "product"
                    },
                    "original_amount_paid": { "currency": "ghs", "value": 200 },
                    "refund_amount": { "currency": "ghs", "value": 100 },
                    "reason": "item_returned"
                }
            ],
            "settlement": {
                "payment_method": {
                    "id": "pm_xyz789",
                    "mobile_money": {
                        "account_number": "****7831",
                        "last4": "7831",
                        "network": "mtn"
                    },
                    "type": "mobile_money"
                },
                "type": "payment_method"
            },
            "reason": "item_returned",
            "created_at": "2025-09-15T09:00:00Z",
            "processing_at": "2025-09-15T09:00:01Z",
            "succeeded_at": "2025-09-15T09:00:03Z"
        }
    ],
    "customer": {
      "id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
      "guest": false,
      "email_address": "yaw@konadu.ie",
      "phone_number": "+233559714200",
      "name": "Anita Segnom"
    },
    "status": "completed",
    "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt"
  }
}
```

## Cancel an order

Cancel an unpaid, unfulfilled order. Cancellation moves the order to `"canceled"` and records the time of the transition. The `reason` and `execute_refund` inputs are retained as cancellation evidence; they are not returned as order fields.

Paid, completed, expired, and already canceled orders cannot be canceled. Cancellation does not currently void, reverse, or refund an attached payment. If money moved, use the refund flow separately and verify its result before treating funds as returned.

> **Warning:**
>
> `execute_refund` is accepted for contract compatibility but currently records intent only. Setting it to `true` does not execute a refund.

### Request attributes

- `execute_refund` — `boolean`

  Records that refund execution was requested as part of the cancellation. It defaults to `false` and does not currently move funds; use the refund flow separately.

- `order_id` — `string`

  The typed ID of the order to cancel (e.g. `or_abc123`).

- `reason` — `string`

  Optional free-text explanation for the cancellation. Recorded on the order for audit purposes. Defaults to `"unknown"` if not provided. Common values: `"customer_request"`, `"fraud"`, `"inventory_unavailable"`, `"duplicate"`.

**Request — POST /orders/cancel**

```bash
curl https://api.inttegro.com/orders/cancel \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
  "reason": "customer_request",
  "execute_refund": false
}'
```

```json
{
  "order": {
    "id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
    "status": "canceled",
    "initiated_at": "2025-04-09T00:11:47.74569+01:00",
    "line_item_group": {
      "line_items": [
        {
          "type": "product",
          "product": {
            "id": "oli_ZLxM9pQ4wRsN7jKv2cY1tD8hBgFnAo3i",
            "name": "Tailoring Service",
            "price": {
              "currency": "ghs",
              "value": 200
            },
            "quantity": 1
          }
        }
      ],
      "total": {
        "currency": "ghs",
        "value": 200
      }
    },
    "payment": {
      "id": "py_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
      "statement_descriptor": "TAILORING",
      "status": "initiated",
      "amount": {
        "currency": "ghs",
        "value": 200
      },
      "initiated_at": "2025-04-09T00:11:48Z"
    },
    "customer": {
      "id": "cu_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
      "guest": false,
      "name": "Gloria Kesewaa"
    }
  }
}
```

## Page through orders

Retrieve a paginated list of your most recent orders. Orders are sorted by `page.orders[].initiated_at` in descending order, so page 0 contains the freshest activity and subsequent pages step back in time.

Provide `customer_id` to scope the page to a single customer. Omit `customer_id` to browse all recent orders.

`page_size` is required. `page_number` is zero-based, defaults to `0`, and accepts values from 0 through 10. An unknown or inaccessible customer filter returns HTTP `400`; a temporary page lookup failure returns `503` and can be retried unchanged.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Required attributes

- `page_size` — `integer`

  Number of orders requested per page. Must be between 1 and 256.

### Optional attributes

- `customer_id` — `string`

  Optional customer ID to scope the page to one buyer's orders only.

- `page_number` — `integer`

  Zero-based page index from 0 through 10. Defaults to 0 when omitted.

### Response shape

- Top-level `page` object includes `page.number`, `page.size`, and an `page.orders` array.
- Each array entry uses the complete shared [order object](#the-order-object), not a condensed summary.
- Orders created through a purchase intent include `page.orders[].created_from` attribution when available. Public API-key requests cannot filter pages by that attribution.
- Optional fields are omitted when unavailable. Paid or completed orders can include `payment.receipt`; the API does not add a `line_item_group.products_count` summary field.
- When you filter by `customer_id`, every returned order belongs to that customer.

**Request — POST /orders/page**

```bash
curl https://api.inttegro.com/orders/page \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "page_number": 0,
  "page_size": 25
}'
```

```json
{
  "page": {
    "number": 0,
    "size": 2,
    "orders": [
      {
        "id": "or_kAVwBsk6EhQVv2YBUhYAqMf0lktEoQ0S7ZR8y2xi",
        "line_item_group": {
          "line_items": [],
          "total": {
            "currency": "ghs",
            "value": 220
          }
        },
        "initiated_at": "2025-04-09T00:11:47.74569+01:00",
        "sealed_at": "2025-04-09T00:11:48.374979+01:00",
        "status": "requires_payment",
        "customer": {
          "id": "cu_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
          "guest": false,
          "name": "Gloria Kesewaa",
          "email_address": "gloria@kesewaa.co",
          "phone_number": "+233544998605"
        },
        "payment": {
          "id": "py_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
          "amount": { "currency": "ghs", "value": 220 },
          "initiated_at": "2025-04-09T00:11:47.842341+01:00",
          "statement_descriptor": "INTTEGRO",
          "status": "requires_action",
          "payment_method": {
            "id": "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
            "customer_id": "cu_N4IX542ZKixJJhIbc4bQBntdPrRb0DQ7KqEYSyqc",
            "created_at": "2025-04-09T00:11:47.842341+01:00",
            "verified": true,
            "type": "mobile_money",
            "mobile_money": {
              "network": "mtn",
              "account_number": "+233******8605",
              "last4": "8605"
            }
          },
          "latest_attempt": {
            "payment_method_type": "mobile_money",
            "payment_method_id": "pm_hg7D2A5qT6g6mVDSJu6zweKXwsiiNWf3Q85book6",
            "reference": "nsn_57d91e4fd4b8",
            "status": "executed",
            "initiated_at": "2025-04-09T00:11:48.391412+01:00"
          }
        }
      },
      {
        "id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
        "line_item_group": {
          "line_items": [],
          "total": {
            "currency": "ghs",
            "value": 200
          }
        },
        "initiated_at": "2025-09-14T16:24:41.137708909Z",
        "completed_at": "2025-09-14T16:29:45Z",
        "sealed_at": "2025-09-14T16:24:41.312701813Z",
        "status": "completed",
        "customer": {
          "id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn",
          "guest": false,
          "name": "Anita Segnom",
          "email_address": "anita@example.com",
          "phone_number": "+233559714200"
        },
        "refunds": [
            {
                "id": "rf_1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcd",
                "order_id": "or_48ZW7BGvYUBWc1i6WBkL2jr0iPQP5jUy76mmmHpt",
                "status": "succeeded",
                "total": { "currency": "ghs", "value": 100 },
                "line_items": [
                    {
                        "id": "rli_zyxwvutsrqponmlkjihgfedcbaABCDEFGHIJKLMN",
                        "order_line_item": {
                            "id": "oli_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN",
                            "product": {
                                "name": "Custom tailoring"
                            },
                            "quantity": 1,
                            "type": "product"
                        },
                        "original_amount_paid": { "currency": "ghs", "value": 200 },
                        "refund_amount": { "currency": "ghs", "value": 100 }
                    }
                ],
                "settlement": {
                    "type": "offline"
                },
                "reason": "item_returned",
                "created_at": "2025-09-15T09:00:00Z",
                "succeeded_at": "2025-09-15T09:00:03Z"
            }
        ]
      }
    ]
  }
}
```