Skip to main content
Checkout flow: propose, review gate, approve, commit Checkout is five steps: open, address, fulfillment, payment, commit. Nothing moves money until commit.

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.