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; a tip or a donation also takes the display_name it is left under, up to 20 characters, and a message, up to 255, which null clears and the order's line keeps in its descriptor), and name a coupon with PUT /checkouts/{checkout}/coupon (null takes it off): a discount's code, or its id, which coupon on the product reads takes too. A product may ask its buyers questions, listed as questions on its product read, a text one perhaps with a pattern the whole answer must match: while the cart holds it, answer them with PUT /products/{product}/answers and read them back with GET /products/{product}/answers. POST /checkouts/{checkout}/freeze presents it for payment: every line must still price as it did, every required question of a product in it but a renewal must be answered (else conflict on questions), 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 with the policy they consented to (true is taken too); without it, or with a policy other than the one asked now, the freeze is refused as invalid at args.refund_waiver, naming the policy, so your page reads the cart and asks again. An open cart reads that policy ahead as refund_consent (null when none is asked), so your page can ask before freezing. Each line reads its own refund_policy as the store sets it now (the price's, else its product's; a frozen cart keeps the consent it was given in refund_waiver) and, while the cart is open or frozen, refund_until, until when a purchase made now may be refunded, so your page shows the window without dating it itself. An app the store hasn't verified is refused a cart that asks for that consent, and any refund_waiver, as not_permitted (principal): abandon the cart and send the customer to the product's page on the store's own site, where they consent themselves.
A total above zero but under the payment processor's minimum charge is granted free, since the processor refuses to take it: the cart reads under_minimum with the amount waived and the processor's minimum, so your page can say why the customer pays nothing. The freeze discounts its lines whole, so totals.discount includes the waived amount and totals.total is zero, asks no refund_waiver, and the order carries the same statements.under_minimum for its receipt. A total the processor still refuses as too small when paid (in a currency whose minimum isn't known ahead, or one it settles in another currency) is granted free then: pay answers paid (or requires_setup, below, when a plan in it will charge its first renewal), and under_minimum.minimum is null.
POST /checkouts/{checkout}/pay starts the payment. A cart with nothing due answers paid with its order at once, unless it buys a plan whose first renewal will charge (a coupon or the processor's minimum making the first period free): the cart reads card_required (reason renewal, null otherwise, while it is open or frozen), and pay answers requires_setup with a setup. A cart buying a product that requires approval at a price that charges reads reason approval instead, open, frozen and once paid: its setup saves the card the seller's approval charges, and the customer's purchase waits as a request. Tell the customer nothing is charged now and the card pays the first renewal, confirm it with Stripe.js's confirmSetup (same publishable_key, account and client_secret as a payment), then call confirm, which answers paid once the card is saved, setup_processing while Stripe checks it, or requires_setup to try again; the checkout can't complete without a card. 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. The payment or setup carries confirm_by, the latest time confirm takes it: the cart's expires_at plus a grace of 15 minutes, or 15 minutes after the payment started on a cart that never expires (a renewal's). Tell the customer this time when the method leaves them instructions to follow (a voucher, a QR code, an approval in their bank's app); past expires_at, pay is refused as conflict (expired), though confirm still answers until confirm_by. A payment not confirmed by then is called off, unless it is already processing, and the cart may close sooner. A payment called off answers cancelled, and one given back refunded, refund_pending (Stripe is still making the refund, or will let it through later) or refund_failed (the store settles it with the customer). Asking to pay again answers the same payment. To pay with a card the customer saved (an app the store verified, or the merchant's own client), send its id from GET /billing_profile as instrument: { id }: it counts only when the payment starts, so naming another card while one is still to confirm is refused as conflict (paying), a card that isn't the customer's answers not_found, and a cart that saves a card for its renewals (requires_setup) takes a saved card alone, any other saved method answering invalid on instrument. The payment or setup carries the saved card it runs on as instrument (null for a new card, or once the customer entered another), so after a reload your page confirms it with no card form. An app the store hasn't verified is refused instrument, and any payment that runs on a saved card, one the customer started on the store's own site included, as not_permitted (principal), while it is still to confirm: abandon that cart and open another, which the customer pays with a card entered in your page. A paid cart reads its order ({ id, number }, null before). 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.
A customer holds one email address, listed at GET /contacts. POST /contacts/change mails a code to a new address, and POST /contacts/verify proves it with that code, which then replaces the old address: until then the old one stays and still signs the customer in, and asking for another address replaces the one waiting for its code. A proven address signs the customer in, so these need contact:write, which the customer grants on its own and only a client the merchant created holds: an app that registered itself is refused it (the authorization server's metadata lists only the scopes such an app may hold), so manage the address from a backend with a confidential client, and ask for it only there. A customer is mailed five such codes an hour at most, a code sent again included, and a store mails two hundred an hour across every customer, whatever app or page asked: past either, /contacts/change answers 429 with the reason limit until the hour ends.