# Order checkout

> Charge several items in one payment. Your server creates an order, and the buyer pays on a hosted page or on your web page.

<CopyAiContextButton pageTitle="Order checkout" pagePath="/multi-item-checkout" />

An **order** is a list of items the buyer pays for in one payment. For example, a $10 t-shirt
plus a $15 monthly course, charged together.

Selling one plan? Use [Embedded checkout](/embedded-checkout). One price your code works out?
Use [Custom amount checkout](/custom-amount-checkout).

## How it works

1. **Your server** creates the order with your API key and gets back an `orderId` and a
   `checkoutUrl`.
2. **The buyer pays**, in one of two ways:
   - **Redirect:** send the buyer to `checkoutUrl`. Payments AI shows the items, takes payment,
     and shows the receipt. No web page code.
   - **Embed:** mount the payment fields on your own page with the `orderId`. Your page shows
     the items.
   - **Saved card:** for a customer who already paid, your server charges one of their saved
     cards, with no buyer present. See [Charge a saved card](#charge-a-saved-card).

An order cannot change after you create it. For different items, create a new order.

## On your server

### 1. Create an order {#create-an-order}

Call `POST /v1/public-api/merchants/{merchantId}/orders` with your API key. Always call it from
your server, never from the browser.

```js title="server.js"
app.post('/api/checkout/order', async (req, res) => {
  const cart = await loadCart(req.session.cartId);

  const response = await fetch(
    `https://sandbox.mor.payments.ai/api/v1/public-api/merchants/${MERCHANT_ID}/orders`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.PAI_API_KEY}`, // pai_test_* in sandbox
        'Content-Type': 'application/json',
        'Idempotency-Key': cart.id, // same key returns the same order
      },
      body: JSON.stringify({
        currency: 'usd',
        items: [
          { planId: 'YOUR_PLAN_ID', quantity: 1 },
          { label: 'T-shirt', unitPrice: 10.0, quantity: 1, type: 'one_time' },
        ],
        metadata: { cart_order_number: cart.orderNumber }, // optional, your own key/value pairs
      }),
    },
  );

  const order = await response.json();
  // Redirect: send the buyer to order.checkoutUrl
  // Embed: pass order.orderId to your web page
  res.status(response.status).json(order);
});
```

Each item is one of three kinds. Its fields decide which:

| Item    | Fields                                                               | Price comes from |
| ------- | -------------------------------------------------------------------- | ---------------- |
| Plan    | `planId`, `quantity`                                                 | The plan         |
| Custom  | `label`, `unitPrice`, `quantity`, `type` (`one_time` or `recurring`) | You              |
| Invoice | `invoiceId`                                                          | The invoice      |

- A recurring custom item also needs `billingPeriod` (`day`, `week`, `month`, or `year`) and
  `periodLength`. `billingPeriod: "day"` with `periodLength: 30` means every 30 days.
- On a recurring custom line you can set `trialPeriodDays` (1–730). Recurring lines charge nothing
  today; the first recurring charge happens after the trial. Omit it when there is no trial. Every
  recurring line in the order — catalogue plan or custom — must use the **same** trial length.
- Do not mix `planId` with `label` / `unitPrice` on the same item; that combination is rejected.
- If a `planId` does not exist, or belongs to another merchant, create is rejected.
  We do not use `label` or `unitPrice` instead.
- Prices are in major units: `10.0` means $10.00.

Every order is checked against these limits before it is created. A request that breaks one gets
`400` with the field and a `Recovery:` step, and no order is created:

| Limit                               | Value                                                                                                                                      |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `currency`                          | One of the [supported currencies](/public-api#supported-currencies)                                                                        |
| `unitPrice`                         | At most the currency's [maximum](/public-api#supported-currencies), and no more decimal places than the currency has (whole yen for `jpy`) |
| One line (`unitPrice` × `quantity`) | At most the currency's maximum                                                                                                             |
| Order total, today and on renewal   | At most the currency's maximum (`order.amount_above_ceiling`)                                                                              |
| `quantity`                          | At most `10000` per line                                                                                                                   |
| `periodLength`                      | At most one year: `365` day, `52` week, `12` month, `1` year                                                                               |
| `trialPeriodDays` (recurring only)  | At most `730`; must match across all recurring lines in the order                                                                          |
| `metadata`                          | At most `50` keys; key `1` to `40` characters; value at most `500` characters                                                              |

The currency limit applies to every order, including one that only pays invoices: an invoice in
another currency cannot be paid through an order. The hosted invoice page applies the currency and
total limits when it opens the order, so an invoice outside them gets `422`
`checkout.invoice_not_payable` instead of a checkout that cannot be paid. That response includes
`details.status` (`open` or `past_due`) and no other invoice fields. The same `422` is returned
when the invoice is `draft`, `paid`, `void`, or `uncollectible`, again with only `details.status`.

The same limits are checked again when the buyer pays. An open order outside them, such as one
created before a limit applied, cannot be paid: confirming it returns `422`
`order.outside_limits`, and nothing is charged. Create a new order within the limits instead.

The `Idempotency-Key` header is optional and unique per merchant. Sending the same key again
returns the existing order with its **current** `status`, `transactionId`, and subscription
linkage (not a frozen snapshot from the first create). Without it, every call creates a new order.

`metadata` is optional: your own key/value pairs for the order, such as a CRM or ERP order number.
It is a flat object whose values are all strings, as in Stripe. Send at most `50` keys; a key is
`1` to `40` characters and a value is at most `500` characters. A longer key or value, more keys,
an empty key, or a value that is not a string gets `400` `Validation failed` naming `metadata`.
Omit it and the order carries `{}`. Keys and values are stored and returned exactly as sent, so
`cf_order_id`, `cfOrderId` and `Order-Ref` stay three different keys. Payments AI does not
interpret metadata and does not require it to be unique. It is returned on every API-key order read
and on the `payment.*` and `subscription.*` [webhooks](/webhooks#event-catalog) that name the order,
including renewals. It is never shown to the buyer (the keyless hosted checkout reads omit it) and
never sent to the payment processor. A replay with the same `Idempotency-Key` returns the original
metadata.

The response is `201 Created`:

```json
{
  "orderId": "0199f0b2-3c4d-7e5f-9012-23456789abcd",
  "checkoutUrl": "https://checkout.payments.ai/payment/order/{orderId}",
  "currency": "usd",
  "amountDue": 25.0,
  "recurringAmount": 15.0,
  "billingPeriod": "day",
  "periodLength": 30,
  "trialPeriodDays": null,
  "items": [
    {
      "label": "T-shirt",
      "unitPrice": 10.0,
      "quantity": 1,
      "lineTotal": 10.0,
      "itemType": "one_time"
    },
    {
      "label": "Course",
      "unitPrice": 15.0,
      "quantity": 1,
      "lineTotal": 15.0,
      "itemType": "recurring",
      "billingPeriod": "day",
      "periodLength": 30
    }
  ],
  "metadata": { "cart_order_number": "SO-10482" }
}
```

| Field             | Meaning                                                                                                                                                                                                                                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metadata`        | The metadata you sent on create, exactly as sent. `{}` when you sent none.                                                                                                                                                                                                                                            |
| `status`          | `open`, `completed`, or `expired`. `open` covers unpaid orders and the window after checkout confirm before the payment row is linked.                                                                                                                                                                                |
| `transactionId`   | Internal Payments AI transaction id (`GET .../transactions/{transactionId}`). `null` while unpaid, between checkout confirm and webhook linkage, or when the only matching payment row is `pending` or `failed`. After a successful payment (including later refund or dispute on that row), this is the internal id. |
| `subscriptionId`  | Internal subscription id when the order has one recurring line item and one subscription is linked.                                                                                                                                                                                                                   |
| `subscriptionIds` | Internal subscription ids when the order has two or more recurring line items, or when multiple subscriptions are linked.                                                                                                                                                                                             |

- `amountDue` is what the buyer pays **today**, before tax. See [Tax](#tax).
- `recurringAmount` is what renews later, every `periodLength` × `billingPeriod`. It is `null`
  when nothing renews.
- After the buyer pays, use `transactionId` from `GET .../orders/{orderId}` to load payment
  details from `GET .../transactions/{transactionId}`. Between checkout confirm and webhook
  linkage, `transactionId` stays `null` even though checkout has started.

## Redirect to the hosted page

Send the buyer to `checkoutUrl`. That is all. Payments AI shows every item, takes payment, and
shows the receipt. Sandbox URLs end in `?isSandbox=true`.

## Embed on your web page

The embed shows payment fields only. Your page shows the items, using the public
`GET /v1/checkout/orders/{orderId}` (no API key).

```html title="checkout.html"
<pre id="summary"></pre>
<p id="total"></p>
<div id="checkout"></div>
<button id="pay" disabled>Pay</button>
<p id="message"></p>

<script src="https://js.mor.payments.ai/v1/checkout.js"></script>
<script>
  const API = 'https://sandbox.mor.payments.ai/api';
  const orderId = 'ORDER_ID_FROM_YOUR_SERVER';

  async function getJson(url) {
    const response = await fetch(url);
    if (!response.ok) throw new Error(`Request failed (${response.status})`);
    return response.json();
  }

  function showMessage(text) {
    document.getElementById('message').textContent = text;
  }

  async function start() {
    // 1. Show the items
    const order = await getJson(`${API}/v1/checkout/orders/${orderId}`);
    const currency = order.currency.toUpperCase();
    const lines = order.items.map(
      (item) => `${item.label} × ${item.quantity}: ${item.lineTotal} ${currency}`,
    );
    lines.push(`Due today, before tax: ${order.amountDue} ${currency}`);
    document.getElementById('summary').textContent = lines.join('\n');

    // 2. Mount the payment fields
    const checkout = await PaymentsAICheckout.mount(document.getElementById('checkout'), {
      orderId,
      environment: 'sandbox',
      onTaxChange: (tax) => {
        // 3. Show tax and the total once the buyer enters their address
        if (!tax.calculated) return;
        document.getElementById('total').textContent =
          `Tax ${tax.taxAmount}, total ${tax.total} ${tax.currency.toUpperCase()}`;
      },
      onComplete: async (result) => {
        // 5. Show the receipt
        const receipt = await getJson(
          `${API}/v1/checkout/orders/${result.orderId}/receipts/${result.receiptId}`,
        );
        showMessage(`Paid ${receipt.total} ${receipt.currency.toUpperCase()}, tax included`);
      },
    });

    // 4. Pay
    const pay = document.getElementById('pay');
    pay.disabled = false;
    pay.addEventListener('click', async () => {
      try {
        await checkout.submit();
      } catch (error) {
        showMessage(error.message);
      }
    });
  }

  start().catch((error) => showMessage(error.message));
</script>
```

`onTaxChange` gives you the tax and the total due today once the buyer has entered a full
billing address. `onComplete` gives you `{ orderId, receiptId }`. The receipt has `subtotal`,
`taxAmount`, `total`, and `currency`.

Options, controls, and errors work the same as in
[Embedded checkout](/embedded-checkout#reference), with `orderId` in place of `planId`. You can
use the same `email`, `billingDetails`, and `hideBuyerFields` mount options to prefill or hide
buyer fields. You can pass `promoCode` to prefill a store-wide code. When nothing is due today (for example a free
trial on recurring lines), hosted checkout and the embed mount the payment fields in setup mode: the buyer saves a
card without a charge today, and confirming the order starts the trial on the order's linked `externalPlanId`. The
buyer is charged after the trial ends. If the order has no `externalPlanId`, payment can't be mounted.

## Charge a saved card {#charge-a-saved-card}

For a returning customer, your server can pay the order with a card they already saved, so
nobody opens a checkout:

1. List the customer's cards with
   `GET /v1/public-api/merchants/{merchantId}/customers/{customerId}/payment-methods` and pick
   one `id`. The card must be the order buyer's: an order with a customer email only takes a
   card of the customer with that email.
2. Charge the order to it:

   ```bash
   curl -X POST "$API/v1/public-api/merchants/$MERCHANT_ID/orders/$ORDER_ID/confirm" \
     -H "Authorization: Bearer $API_KEY" \
     -H "Idempotency-Key: renewal-upsell-1001" \
     -H "Content-Type: application/json" \
     -d '{ "paymentMethodId": "'"$PAYMENT_METHOD_ID"'" }'
   ```

3. The answer is `{ "paymentId": "pay_…", "status": "processing" }`. Treat the order as paid
   only when `payment.completed` with its `orderId` arrives. A recurring item starts a
   subscription that renews on the same card.

**If `payment.failed` arrives with the order's `orderId`,** the card was refused after the
answer. Nothing was charged and the order is open again. Charge it again with a new
`Idempotency-Key` (`declineReason` says why the card was refused), or send the buyer to the
checkout.

**If the answer is `409` `order.requires_on_session_payment`,** the card needs the buyer to
authenticate. Nothing was charged. Send the buyer to the order's `checkoutUrl`, or
[embed the checkout](#embed-on-your-web-page), to pay it.

**If the answer is `402` `order.payment_declined`,** the card was refused right away and the
order is still open. Ask the customer for another card, or send them to the checkout. A `422`
`order.payment_refused` means the payment provider refused the charge itself: nothing was charged,
and the same steps apply.
After 5 declined charges of the order in 24 hours, or 10 of the card in an hour (its charges in
progress on other orders count too), the answer is `429` `order.payment_attempts_exceeded` and
nothing is charged: send the buyer to the checkout.

A repeat with the same `Idempotency-Key` returns the first answer and never charges twice. While
the payment provider is still deciding a charge, repeat it with the same key; another key gets
`409` `order.payment_in_flight`. All statuses and codes:
[Pay an order with a saved card](/public-api#pay-an-order-with-a-saved-card).

## Examples

### T-shirt plus course

**$25.00 today, then $15.00 every 30 days.** The renewal is for the course only.

```json
{
  "currency": "usd",
  "items": [
    {
      "label": "T-shirt",
      "unitPrice": 10.0,
      "quantity": 1,
      "type": "one_time"
    },
    {
      "label": "Course",
      "unitPrice": 15.0,
      "quantity": 1,
      "type": "recurring",
      "billingPeriod": "day",
      "periodLength": 30
    }
  ]
}
```

### Your own prices only

Charge **$59** today (setup plus the first week), then **$40** every 7 days. No plans needed.

```json
{
  "currency": "usd",
  "items": [
    { "label": "Setup", "unitPrice": 19.0, "quantity": 1, "type": "one_time" },
    {
      "label": "Membership",
      "unitPrice": 40.0,
      "quantity": 1,
      "type": "recurring",
      "billingPeriod": "day",
      "periodLength": 7
    }
  ]
}
```

### Two plans you already created

```json
{
  "currency": "usd",
  "items": [
    { "planId": "0199f0a1-2b3c-7d4e-8f90-123456789abc", "quantity": 1 },
    { "planId": "0199f0c3-4d5e-7f60-1234-3456789abcde", "quantity": 1 }
  ]
}
```

Both plans must belong to `{merchantId}`. If both are recurring, they must share the same
billing schedule.

### Pay open invoices

```json
{
  "currency": "usd",
  "items": [{ "invoiceId": "0199f0a1-2b3c-7d4e-8f90-123456789abc" }]
}
```

The invoice must be open or past due, belong to the same merchant, and not already be on another
order. You can put several invoices in one order if they share a currency. Paying the order does
not by itself mark the invoice paid.

Invoice list and detail also return a `payUrl` for open or past-due invoices with an amount
above zero. It opens `/invoice/{invoiceId}` on the hosted page. Otherwise `payUrl` is `null`.

## Tax

`amountDue` on the order is the price before tax. Tax is one amount for the whole order, not a
separate rate on each item. The buyer pays more than `amountDue` once tax is known.

Tax is calculated in live only. In sandbox, every tax preview is `calculated: false` with
`taxAmount: 0`, and `calculated: false` is not a tax of zero.

Show that tax before they pay:

- **Hosted page:** the tax and the total update as soon as the billing address is complete.
- **Embed:** `onTaxChange` is called with `calculated: true` once tax is known. `taxAmount` is
  the tax and `total` is what the buyer pays today. `calculated: false` means tax is not known
  yet: keep showing `amountDue` without tax. That is not a tax of zero. When `taxBehavior` is
  `inclusive`, `subtotal` already includes the tax, so use `total` and do not add `taxAmount`
  on top.
- **Your own UI:** `POST /v1/checkout/orders/{orderId}/tax` with the billing address, for
  example `{ "address": { "country": "US", "state": "NY", "postalCode": "10001" } }`. Add
  `promoCode` when a code is applied so tax matches the discounted price. The route
  is public and does not charge the buyer. Use `taxAmount` and `total` only when `calculated`
  is true. When tax cannot be calculated, the route answers HTTP 200 with `calculated: false`.
  A rejected address or tax ID gets the same answer. Keep showing the price without tax.
- **Promo preview:** `POST /v1/checkout/orders/{orderId}/promo-code-preview` with
  `{ "code": "SPRING25" }`. This does not charge the buyer. Confirm with the same `promoCode`
  on `POST /v1/checkout/orders/{orderId}/confirm`. A code that only applies to one product is
  rejected the same way as an unknown code.

A business buyer's valid tax ID (`payerType: 'business'`) is included. If it exempts them,
`calculated` is true and `taxAmount` is `0`. The order itself has no tax field. The receipt
shows the tax that was charged.

## Limits

1. Up to **20 items** per order.
2. One billing schedule per order, and one trial length for all recurring items. Different
   schedules are rejected at create.
3. One membership per order. Quantity on a recurring item multiplies its renewal (3 × $15/month
   = $45/month, one membership).
4. One tax amount for the whole order.
5. Store-wide promo codes work on an order. A code limited to one product does not.
6. You cannot change an order. Create a new order instead.
7. Custom items (you set the price) need an API key, so create orders from your server only.
8. A `planId` or `invoiceId` from another merchant is rejected.
9. Each paid amount must meet the minimum of its currency, listed with the
   [supported currencies](/public-api#supported-currencies) (for example 1 for `usd`, 50 for
   `jpy`).

10. A recurring item renewing daily needs `periodLength` of at least 2. `periodLength: 1` returns
    `400` at create, in sandbox and live. A plan cannot be updated below 2 days either
    (`400` `plan.billing_period_too_short`).

## Testing renewals in sandbox

Sandbox has no test clock, "renew now", or "end trial now" call. Wait for the period to pass.

- **Shortest renewal:** `billingPeriod: "day"` and `periodLength: 2`. See [Limits](#limits) item 10.
- **Shortest trial:** `trialPeriodDays: 1`. Any whole number of days from 1 up is accepted.
- **Webhooks:** each renewal or trial-end charge sends `payment.completed` or `payment.failed`.
  `orderId` is set for subscriptions bought through an order, but can be `null` otherwise, so
  handle both. See [Webhooks](/webhooks).

## Embed: consent and errors

Order mode shows the same consent links and `onError` `code` values as
[Embedded checkout](/embedded-checkout#handle-errors). Policy URLs come from
`GET /v1/checkout/orders/{orderId}`.

## Reference

| Route                                                                 | Auth    | Use                               |
| --------------------------------------------------------------------- | ------- | --------------------------------- |
| `POST /v1/public-api/merchants/{merchantId}/orders`                   | API key | Create an order (your server)     |
| `GET /v1/public-api/merchants/{merchantId}/orders/{orderId}`          | API key | Read an order (your server)       |
| `POST /v1/public-api/merchants/{merchantId}/orders/{orderId}/confirm` | API key | Charge a saved card (your server) |
| `GET /v1/checkout/orders/{orderId}`                                   | None    | Show the items (web page)         |
| `GET /v1/checkout/orders/{orderId}/receipts/{receiptId}`              | None    | Show the receipt (web page)       |

The embed calls `POST /v1/checkout/orders/{orderId}/confirm` for you during `submit()`. Full
schemas are in the [API Reference](/api).

## Next steps

- [Embedded checkout](/embedded-checkout): sell one plan
- [Custom amount checkout](/custom-amount-checkout): one price your code works out
- [Merchant Public API](/public-api): API keys and server routes
