---
title: "Orders"
description: "Create durable transaction records that coordinate checkout, payment, invoicing, and fulfillment."
canonical: "https://studio.inttegro.com/products/orders"
format: inttegro-machine-docs/v1
language: "Python"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/python/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: 526
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "curated"
recommended_mcp_tools: ["get_order","create_order","pay_order"]
estimated_tokens: 3159
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Use an order as the durable record of one sale; distinguish its line-item, catalog-product, and payment IDs, then verify money and fulfillment as separate outcomes.

### Five questions

#### Q1. Is a purchase intent the sale record?

No. A purchase intent is an offer that can create an order; the order records a particular customer's transaction. Read [Order creation patterns](https://studio.inttegro.com/machine/python/products/orders.md#creation-patterns) before choosing a Buy link or direct order flow.

#### Q2. Which IDs can be joined or reused?

Keep the order ID, order line-item IDs, catalog product IDs, and payment ID separate. The order's product line has an order-specific ID; its optional catalog product ID identifies the source catalog item. [Resource boundaries](https://studio.inttegro.com/machine/python/products/orders.md#resource-boundaries-and-ids) explains the distinction.

#### Q3. Does an executed payment mean fulfillment is safe?

No. An attempt can be executed without being paid. [Look up the order](https://studio.inttegro.com/machine/python/api/orders.md#lookup-an-order), inspect both order and payment state, and fulfill only after the paid outcome; a completed order also records fulfillment.

#### Q4. Can a paid order be edited to reverse the sale?

No. A paid order remains the sale record. Use [Refunds](https://studio.inttegro.com/machine/python/products/refunds.md) for returned money; treat an invoice as pre-payment communication and a receipt as a post-payment record.

#### Q5. Which MCP actions can assist, and what remains private?

An authenticated client can [create_order](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#create_order) from catalog items, [pay_order](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#pay_order) after exact amount and masked-method confirmation, and [get_order](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#get_order) for current state. New payment details and OTP stay in secure Checkout; your backend owns unattended automation.

## Document content

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

> Mcp Guide Callout is interactive content. Use the canonical page to view it.

Use this page to understand how orders behave. Use the [Orders API reference](https://studio.inttegro.com/machine/python/api/orders.md) 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](https://studio.inttegro.com/machine/python/products/purchase-intents.md) 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](https://studio.inttegro.com/machine/python/api/orders.md#create-an-order) |
| Finalized invoice | You want a hosted invoice or payment page the customer can pay later. | [Create an order](https://studio.inttegro.com/machine/python/api/orders.md#create-an-order) with finalization, or [Finalize an order](https://studio.inttegro.com/machine/python/api/orders.md#finalize-an-order) |
| Immediate payment | You already have payment method data and want to start collection. | [Pay for an order](https://studio.inttegro.com/machine/python/api/orders.md#pay-for-an-order) |
| Hosted checkout | You want Inttegro to handle the payment UI. | [Inttegro Checkout](https://studio.inttegro.com/machine/python/products/checkout.md) |
| Buy link | You want a reusable or single-use product offer URL. | [Purchase intents](https://studio.inttegro.com/machine/python/products/purchase-intents.md) |

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 refund integrations.

## 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;
- start or deliberately retry payment after the customer confirms the exact amount and masked saved method;
- send an invoice or receipt after confirmation;
- render an order card for support review; and
- fetch order analytics for a period and currency.

New payment details and OTP remain in secure Inttegro Checkout, not chat or tool arguments. Your application should still own unattended order creation, payment execution, fulfillment automation, and webhook or polling decisions. Use a current order lookup before treating an MCP payment action as paid.

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

## Related resources

- [Orders API reference](https://studio.inttegro.com/machine/python/api/orders.md) - Complete order operation contract.
- [Order lifecycle](https://studio.inttegro.com/machine/python/guides/order-lifecycle.md) - Detailed state transitions and operational handling.
- [Inttegro Checkout](https://studio.inttegro.com/machine/python/products/checkout.md) - Hosted payment pages for finalized orders.
- [Purchase intents](https://studio.inttegro.com/machine/python/products/purchase-intents.md) - Product-specific Buy links that create orders.
- [Refunds](https://studio.inttegro.com/machine/python/products/refunds.md) - Returning money for paid order line items.
- [Balance transactions](https://studio.inttegro.com/machine/python/api/balance-transactions.md) - Money movement records created around payments and refunds.