1. Open checkout
create_checkout opens the merchant checkout page and reads it. Returns status, line_items, totals, fulfillment.methods, and review_hash. Nothing is placed.
If the cart is empty, the call fails with cart_empty. If sign-in is needed, it fails with sign_in_required. If items went out of stock, it fails with out_of_stock and lists the unavailable_items.
2. Set the address
update_checkout with fulfillment.address writes the shipping address. US addresses only. At least one name (first_name or last_name) is required. Optional fields: extended_address, phone_number.
The response includes updated totals with estimated tax. These are estimates until complete_checkout.
3. Choose fulfillment
update_checkout with fulfillment.method selects shipping, delivery, or pickup. Use an id from fulfillment.methods in the checkout response. kind is "shipping", "delivery", or "pickup".
The checkout response also includes fulfillment.delivery_date when the page shows one: { earliest, latest, text }. latest is null for a single date. This field is informational and not part of review_hash.
4. Add payment
update_checkout with payment.instruments adds a vaulted card. The credential.value is Evervault ev: ciphertext, collected through the console’s /collect page. No raw card numbers.
After payment is set, status moves from "incomplete" to "ready".
5. Commit the order
complete_checkout places the order. It requires both review_hash and total_minor from the checkout. If either has changed since your last read, the call fails and nothing is placed. See Review and safety for details.
On success, returns status: "completed" with order.id and test. The session ends.
Reading the checkout
get_checkout re-reads the open checkout without changing anything. Use it to get a fresh review_hash and totals after a review_changed error.
Cancelling
cancel_checkout leaves checkout without placing. Returns status: "canceled". The cart stays open — you can modify it and start checkout again.
Test keys
With a test key (am_test_), complete_checkout runs the full flow — reads the review, verifies the hash — but does not submit to the merchant. The order is stored with test: true and permalink_url is empty. No fee is charged.