> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://api-docs.papertracc.com/storefront/checkout/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.papertracc.com/_mcp/server. # Overview Checkout turns a cart into an order for the merchant to confirm. ## What happens 1. **The shopper is matched to a customer.** With a `shopper-token`, the order goes to the signed-in shopper's customer. Otherwise Papertracc looks for a customer in the workspace with the same email, then the same phone number, and creates one if neither matches. An existing customer's details are not changed. 2. **The order is recorded** as a draft quote in Papertracc, with the delivery address, phone and note in its notes. 3. **The cart is closed.** Its token stops working. The response carries the order's `reference`, such as `QUO-0042`. Show it to the shopper: with it and their email, a guest can follow the order with Look Up Order. When the cart held backordered, pre-ordered or made-to-order items, `expected_on` is the date the order was promised to ship by. What each line was promised is saved with the order, so later changes to the product do not change it. ## Delivery and pickup When the merchant has set up delivery, ask for the shopper's address before payment: 1. **Build the address form** from Get Delivery Areas: the states and areas the store delivers to. Shoppers can also type an area that isn't listed. Send `area` and an optional `landmark` with the rest of `shipping_address`. 2. **Show the choices** from Get Delivery Options with the cart token and the shopper's `state` and `area`. Each delivery offer has the merchant's name for it, its `fee` in the cart's currency, and the promised `arrives_by` date (with `arrives_from` when it is a range). Pickup offers name the store, its address and when the order is `ready_at`. Options follow the merchant's cutoff times and closed days, so ask again if the shopper comes back later. 3. **When an offer has a `schedule`**, let the shopper pick one of its `dates`, and one of its `windows` when there are any. 4. **Send the choice** as `delivery` on Checkout Cart: `option_id` for delivery or `pickup_point_id` for pickup, plus `date`, `from` and `to` for scheduled offers. `required: true` means the cart has items to ship and the store has set up delivery or pickup for the channel, so Checkout Cart fails with `422` unless you send a `delivery` choice. When neither list has anything for the address, the store doesn't deliver there: ask for another address or offer pickup. The choice is checked again at checkout and its fee added to the order as an adjustment named after the option, so the order's `total` includes it. Items that ship later, such as pre-orders, move the promised date and hide same-day options. Some options have `fee_type: LATER`: the merchant sets the fee after the order, for places they can't price upfront. Show them as "Fee confirmed after you order". The order comes back with `delivery_fee_pending: true` and no `checkout_url`; once the merchant sets the fee, the shopper is emailed the new total with a payment link. These options can't be used with instalments. ## Payment When the workspace takes payment online, Get Shop returns `checkout.enabled: true` and the order comes back with a `checkout_url`. Send the shopper there to pay by bank transfer, usually in a new tab. The page shows the bank details and the payment as it is confirmed. Once paid, its **Back to store** button goes to the `return_url` you sent with the checkout, or to the workspace's hosted store if you sent none. A shopper who closes the page can pay later: List Orders, Get Order and Look Up Order return the same `checkout_url` while the payment link is open. The link stays open for an hour, longer while the shopper is paying. After that, Renew Payment Link opens a new one if the items are still in stock. See Orders. When `checkout.enabled` is `false`, `checkout_url` is `null` and no payment is taken. Tell the shopper their order has been received; the merchant confirms it and invoices them from Papertracc. ## Pay in instalments When the merchant offers layaway on the channel, Get Shop lists the plans under `checkout.layaway`, with `checkout.layaway_minimum` as the smallest order that can use them. Get Layaway Options works each plan out for the cart: the amount of every payment, when it is due, the payment after which the goods are released, and whether the cart can use the plan at all. When `eligible` is `false`, show the shopper the `problem`. To use a plan, send its `term_id` as `layaway_term_id` on Checkout Cart, with a `shopper-token`: only signed-in shoppers can pay in instalments. The order's `checkout_url` asks for the first payment. If the first payment is not made within 24 hours, the order is cancelled and the shopper is emailed; the email's **Shop again** button goes to the site in your `return_url`. The store holds the goods until the release payment is made. List Orders, Get Order and Look Up Order return the schedule under `instalments`, what has been paid as `amount_paid`, and `layaway.left_to_release`. While a payment is due, `checkout_url` opens the payment link for it. ## Totals can change The order's `total` is calculated at checkout, when the shopper is known. It can differ from the cart's last total if a promotion depends on the customer. If the cart's promotion code no longer applies, checkout fails with `422` and the cart is left as it was; remove the code and try again. ## When checkout fails | Status | Reason | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | A field is missing or invalid, or the email's domain cannot receive mail (it has no mail server). | | `404` | The cart token is unknown or the cart was already checked out. | | `422` | The cart is empty, an item is no longer available, the promotion code does not apply, or the workspace cannot record the order: the Quotes service is off, or the cart's currency is not enabled for the workspace. Also when `layaway_term_id` is sent without a `shopper-token`, names a plan the channel does not offer, or the order is below `layaway_minimum`, and when the `delivery` choice is missing while one is required, is no longer available for the cart and address, or the store doesn't deliver to the address and has no pickup point. | | `429` | The shopper has tried to check out more than 10 times in 15 minutes. | ## API Docs - Checkout [Get Layaway Options](https://api-docs.papertracc.com/storefront/checkout/get-layaway-options.md) - Checkout [Get Delivery Options](https://api-docs.papertracc.com/storefront/checkout/get-delivery-options.md) - Checkout [Get Delivery Areas](https://api-docs.papertracc.com/storefront/checkout/get-delivery-areas.md) - Checkout [Checkout Cart](https://api-docs.papertracc.com/storefront/checkout/checkout.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://api-docs.papertracc.com/openapi.json) - [OpenAPI YAML](https://api-docs.papertracc.com/openapi.yaml)