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