Checkout and addresses

A purchase is a cart the customer fills, presents for payment and pays in your page. Open one with POST /v1/stores/{store}/checkouts and a currency, put prices in it with PUT /checkouts/{checkout}/items (a quantity of zero takes a line out), and name a coupon with PUT /checkouts/{checkout}/coupon (null takes it off). POST /checkouts/{checkout}/freeze presents it for payment: every line must still price as it did, and the cart stops changing. When a line's refund policy is shorter than the statutory window, the customer must consent to it in your page and you send refund_waiver: true; without it the freeze is refused as invalid at args.refund_waiver, naming the policy.

POST /checkouts/{checkout}/pay starts the payment. A cart with nothing due answers paid with its order at once. Any other answers requires_payment with a payment: confirm it in your page with Stripe.js, loaded with its publishable_key and account as the connected account, using its client_secret. Then call POST /checkouts/{checkout}/confirm, which reads the payment back from Stripe, never from your page, and answers paid with the order once it went through, processing while it settles, or requires_payment when the customer has to try again. A payment called off answers cancelled, and one given back refunded, refund_pending (Stripe will let the refund through later) or refund_failed (the store settles it with the customer). Asking to pay again answers the same payment. POST /checkouts/{checkout}/abandon gives a cart up. These need checkout:write.

No write takes an idempotency key, so after a failed or unanswered call read the cart back (GET /checkouts) before trying again, rather than opening another.

The customer's email addresses are listed at GET /contacts. POST /contacts/add mails a code to a new address, POST /contacts/verify proves it with that code, and POST /contacts/remove takes one off, never the last proven one. A proven address signs the customer in, so these need contact:write, which the customer grants on its own; ask for it only where your app manages their addresses.