Orders

Orders are the durable record of a sale. They fix what the customer is buying, coordinate payment, expose invoice and receipt workflows, and track whether fulfillment is complete.

Use MCP for order operations

An authenticated AI agent can inspect orders, create catalog-backed orders after confirmation, send invoices or receipts after confirmation, and summarize order analytics without exposing unnecessary customer details.

MCP tools: list_orders, get_order, create_order, send_order_invoice, send_order_receipt, render_order_card or get_order_analytics

Confirmed MCP actions require explicit form confirmation before Inttegro changes state.

Use this page to understand how orders behave. Use the Orders API reference for exact request attributes, response shapes, and examples.

What orders are for

An order is the commercial object your business can safely build around. It connects customer intent, cart contents, payment state, invoice state, and fulfillment state in one record.

A purchase intent is the reusable offer or Buy link that can create an order when a customer checks out. The order is the resulting transaction record. Keep that distinction clear: purchase intents describe what can be bought; orders record what a specific customer actually bought.

Part	What it represents
Customer snapshot	Who the order is for, captured at order time.
Line items	The products, services, fees, shipping, taxes, discounts, or other supported order entries.
Amounts	Currency-specific totals in integer minor units.
Payment	How money is collected and what customer action may still be required.
Invoice and receipt	Customer-facing documents and delivery workflows.
Fulfillment	Whether the paid order has been completed by your business.
Origin	Whether the order came from direct API creation, a Buy link, or another Inttegro flow.

Catalog-backed products and prices are snapshotted when the order is created. Changing the catalog later does not rewrite an existing order.

Resource boundaries and IDs

Order resources often carry IDs from adjacent systems. Store them separately; they are not interchangeable.

order.id identifies the transaction and starts with or_.
order.line_item_group.line_items[].product.id identifies the product line on this order and starts with oli_. It is not a catalog product ID.
order.line_item_group.line_items[].product.product_id, when present, identifies the catalog product copied into the order.
order.payment.id identifies the payment attached to the order and starts with py_.
order.created_from.resource_id, when present, identifies the purchase intent or other Inttegro resource that created the order.

This is why product reporting and order reconciliation should not join on a single generic “product ID.” A catalog product, an order line item, and a payment are different records with different lifecycles.

Lifecycle

Order status answers “what happened to the sale?” Payment status answers “what happened to money collection?” Always read both.

Order status	Meaning	Typical next step
`preparing`	Editable draft.	Update, finalize, or pay.
`requires_payment`	Finalized and awaiting payment.	Send invoice, execute payment, or cancel if appropriate.
`paid`	Money was collected, but fulfillment is not complete.	Fulfill the order.
`completed`	Fulfillment is recorded.	Treat as terminal.
`canceled`	Stopped before completion.	Treat as terminal.
`expired`	Passed expiry before completion.	Create a new order if the customer still wants to buy.
`unknown`	Current state could not be determined.	Look up the order again before mutating it.

Payment status may be requires_action, executed, paid, failed, or another provider-aware state. executed means an attempt started; it is not proof of payment. When payment.next_action is present, follow that customer-confirmation path.

Terminal order states take precedence when Inttegro reports order.status: canceled, completed, paid, expired, finalized-but-unpaid, then draft. For example, a completed order reports completed even though it was paid first.

Creation patterns

Use the creation pattern that matches your checkout flow.

Pattern	Use when	Main operation
Draft order	You need to assemble or review the cart before showing it to the customer.	Create an order
Finalized invoice	You want a hosted invoice or payment page the customer can pay later.	Create an order with finalization, or Finalize an order
Immediate payment	You already have payment method data and want to start collection.	Pay for an order
Hosted checkout	You want Inttegro to handle the payment UI.	Inttegro Checkout
Buy link	You want a reusable or single-use product offer URL.	Purchase intents

Once payment confirmation or execution starts, mutability narrows. Do not build flows that change line items underneath an active payment.

Mutability

A draft order is editable. Finalizing it seals the line items and total so the amount presented for payment cannot change underneath checkout.

Before payment confirmation or execution starts, you can still update supported fields. Replacing line_items reopens the economic content of the order, so send an explicit finalize decision with that update: leave the revised order open, or reseal it in the same request.

Updating custom_data, invoice content, order numbers, or an eligible payment method does not by itself reopen a sealed order. Paid, completed, canceled, and expired orders cannot be updated.

Line items and totals

Line items are the financial content of the order. Product line items can be fully inline, copied from a catalog product, or tied to a catalog product and price. The order stores a snapshot so later catalog edits do not alter the customer’s transaction.

Operational rules:

use the same currency across all priced line items in one order;
use integer minor units for all amounts;
keep line items within the configured limit, currently 64 by default;
use product_id for catalog-backed orders when you want product reporting; and
use stable references or custom data when your system needs to match the order back to an internal cart.

The order total is computed from line items. Do not send a separate total and expect it to override line-level amounts.

Invoices, hosted checkout, and receipts

Finalized orders can produce invoice URLs. The web invoice is the hosted checkout entry point; the PDF invoice is useful for printing or email attachments.

Use invoice delivery when payment should happen outside your own UI. Use receipts only after payment succeeds. Sending an invoice does not mean the customer paid, and sending a receipt before a paid state creates bad records for support and finance.

Refunds and post-payment changes

After payment, do not mutate the paid order to “undo” the sale. Use refunds for money that should go back to the customer, and use completion state for fulfillment.

Use POST /refunds/create for new refund integrations. POST /orders/refund exists as an orders-side compatibility alias and is documented in the Orders API reference.

Where MCP helps

MCP is useful for assisted order operations:

list recent orders and summarize which ones need attention;
look up a specific order without exposing raw contact data;
create a catalog-backed order after confirmation;
send an invoice or receipt after confirmation;
render an order card for support review; and
fetch order analytics for a period and currency.

MCP does not execute payment. Your application should still own unattended order creation, payment execution, fulfillment automation, and webhook or polling decisions.

Implementation checklist

Before using orders in production:

create orders from a trusted backend;
use idempotency keys for create and mutation requests;
store or_..., oli_..., and payment IDs separately;
treat catalog product IDs and order line-item IDs as different IDs;
verify payment state before fulfillment;
keep line items immutable after payment starts;
send invoices before payment and receipts after payment;
reconcile money through balances, balance transactions, payouts, and refunds; and
build clear handling for customer confirmation and failed payment states.

Orders API reference - Complete order operation contract.
Order lifecycle - Detailed state transitions and operational handling.
Inttegro Checkout - Hosted payment pages for finalized orders.
Purchase intents - Product-specific Buy links that create orders.
Refunds - Returning money for paid order line items.
Balance transactions - Money movement records created around payments and refunds.