> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.papertracc.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.papertracc.com/_mcp/server.

# Overview

Shoppers can follow an order after checkout in two ways.

| Who               | How                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| Signed-in shopper | List Orders and Get Order, with the `shopper-token` header.                                                         |
| Guest             | Look Up Order, with the order reference and either the email entered at checkout or the `key` from the order email. |

A signed-in shopper's history includes orders placed while signed in and orders placed as a guest with the same email. It never includes an order placed with a different email, even if the shopper was matched to the same customer by phone.

## States

| `state`     | Meaning                                                                      |
| ----------- | ---------------------------------------------------------------------------- |
| `RECEIVED`  | The order is recorded and waiting for the merchant.                          |
| `CONFIRMED` | The merchant confirmed the order or invoiced it.                             |
| `PAID`      | The order has been paid in full.                                             |
| `FULFILLED` | The merchant has fulfilled the order, for example sent it or handed it over. |
| `CANCELLED` | The merchant declined or voided the order.                                   |

`fulfilled_at` is the time the merchant marked the order as fulfilled, and `null` until then. The merchant can undo it, which takes the order back to its earlier state and `fulfilled_at` back to `null`. Delivery itself is not tracked yet, so there is no delivered state or tracking number.

## Items not in stock yet

An order can hold items that were backordered, pre-ordered or made to order. On List Orders, Get Order and Look Up Order, `expected_on` is the latest date the order was promised to ship by. On Get Order and Look Up Order, each line's `sell_mode` shows how it was promised, and `ships_on` gives that line's date. Lines sent from stock have `sell_mode` `STOCK` and no `ships_on`.

## Paying for an order

Get Shop returns `checkout.enabled: true` when the workspace takes payment online. Checkout Cart then returns a `checkout_url` for the new order. List Orders, Get Order and Look Up Order return it too, while the payment link is open and the order is `RECEIVED` or `CONFIRMED`. Show a pay button whenever it is present. The checkout page shows the bank details, takes the shopper's "I have paid" note, and shows the payment as paid once the merchant confirms it.

A payment link stays open for an hour, and longer while the shopper is on the payment step. Until then the order's items are held for the shopper. After that the items go back on sale and `checkout_url` is gone. Renew Payment Link opens a new link if the items are still in stock, and returns `422` if they are not.

`checkout_status` tells you where the payment link stands, even after `checkout_url` is gone:

| `checkout_status` | Meaning                                                                  |
| ----------------- | ------------------------------------------------------------------------ |
| `PENDING`         | Waiting for payment.                                                     |
| `PARTIALLY_PAID`  | Part of the total has been paid.                                         |
| `COMPLETED`       | Paid in full.                                                            |
| `EXPIRED`         | The link ran out before it was paid. Renew Payment Link opens a new one. |
| `CANCELLED`       | The order was voided.                                                    |

## Guest lookup

A wrong reference or email returns `404` without saying which one was wrong. A shopper who fails 10 lookups in 15 minutes must wait before trying again.

## Order emails

The shopper gets an order email from the merchant. Pass `order_url` at checkout to point it at your order page: its **Pay now** button and **view your order** link go there with `reference` and `key` added to the query string. Send both to Look Up Order to show the order without asking for the email, then Renew Payment Link if the shopper wants to pay. Without `order_url`, **Pay now** opens the payment link directly, which stops working after an hour.

A store sends at most 5 emails an hour to one address. Orders placed after that still go through, without an email.

Unpaid orders are removed once the order's quote expires.

## Delivery progress

Get Order and Look Up Order return `delivery`, what the shopper chose at checkout, and `deliveries`, one entry per parcel or pickup with its items and `status`. An order splits into several deliveries when items ship at different times: a pre-order waits as `SCHEDULED` until its `ships_on` date. Statuses then follow the merchant: `TO_PACK`, `READY`, `OUT_FOR_DELIVERY` and `DELIVERED`, or `READY_FOR_PICKUP` and `COLLECTED` for pickup, with `FAILED_ATTEMPT` when a delivery could not be completed. `fulfilment` is `FULFILLED` once every delivery is delivered or collected. The shopper is emailed when a delivery goes out, arrives, fails, is ready for pickup or is collected.