Check out a cart
checkout_cart
Order every part of a cart with ONE payment link. Each part needs a pick that comes to exactly one option (its selection_match reads "one"). A part whose shop still has to confirm it (get_cart shows checkout.state "needs_check" or "checking") is confirmed by this call itself: its one shop is asked — or the ask already running is joined — and the call waits up to wait_s for the answers; no check_offer and no reconfirm read is needed first. Pass max_total_cents: the cart total_cents the user agreed to. ALL OR NOTHING: if any part cannot be ordered, nothing is created, nothing is charged, and the answer (cart_not_ready) names each such part and why — fix those and call again. Pass only_selected true to leave the parts with nothing picked in the cart and order the rest. Returns checkout_url — ONE secure payment page for the whole cart; give it to the user to pay. After payment AFN places one order per part with its own shop; each part ships by itself unless by_shop[].shipping.mode in the answer reads "combined" for its shop (then that shop takes its parts as one order and ships them together); each order sends its own confirmation email, and get_order_status with the checkout_id shows them all. idempotency_key: make up one unique string for this attempt and send the SAME string only to repeat the very same call — it then returns the same checkout and payment link, never a second set of orders. After ANYTHING changed (the address, the coupon, a part, a pick) make up a NEW string: the old one is refused (idempotency_key_reused), because its payment link is for the cart as it was. A part already paid for by itself is named in the refusal like any other part. When a shop's answer did not come inside wait_s, the cart is refused with that part named (offer_not_ready): send the SAME call again with the SAME idempotency_key (a refused call never uses its key) — it joins the asks already running and nothing is asked twice. When the cart's confirmed total is higher than the user agreed to, the call stops ONCE (price_went_up: old_total_cents, new_total_cents, and items naming the parts that rose) and nothing is created: tell the user, then call again with the new max_total_cents and the same idempotency_key. A coupon applies once, to the cart total. This tool takes NO personal details: never ask for — and never pass — a name, address, email, or phone; the secure payment page collects the shipping address, email, and phone once for the whole cart, even when the user volunteered them in chat. Never ask the user for card details in chat.THE CHECKOUT RULE, enforced by the network for every client: an offer can be ordered only when the shop's own system has accepted this part at this price — its manufacturability check has passed, the price is the shop's own number (price_basis "vendor_api"), and no price confirmation is outstanding. That acceptance is good for 15 minutes (the offer's confirmed_until). THE CHECKOUT CONFIRMS WHAT NEEDS CONFIRMING ITSELF: when the option's shop has not confirmed it, or did more than 15 minutes ago, the checkout asks that ONE shop (it joins the ask already running when choosing the option started one) and waits up to wait_s for the answer; when the wait runs out first the answer is offer_not_ready with retry_after_s — send the SAME call again, it joins the ask and nothing is asked twice. THE PAY RULE: the same or a lower price goes straight to the payment link; a price the shop confirmed HIGHER than the user agreed to stops ONCE (price_went_up, with old_total_cents and new_total_cents) and nothing is created — tell the user both figures, then send the call again (with the new max_total_cents when you sent one); the new price stands for 15 minutes and no shop is asked again. A passed offer whose price_refresh is still "pending" is refused the same way (offer_not_ready, with retry_after_s): the shop is still confirming its price — re-read the quote and retry then. An offer whose check failed, whose price_refresh reads "failed", or whose fulfillment is "not_connected" cannot be ordered at all (offer_check_failed) — offer the user another option or re-quote. Nothing is charged on any refusal. An offer whose shop could not confirm the part — it declined the part, or did not answer within two minutes of being asked — leaves the quote: it is no longer listed in offers, and its id is refused the same way. If an offer you showed earlier is missing when you re-read the quote, tell the user plainly that the shop could not confirm the part, and carry on with the offers that are listed. SHIPPING IN A CART: by_shop[].shipping says how each shop's parts ship. mode "ships_separately" = each part is its own order with that shop and its own package, and pays its own shipping; mode "combined" = the shop takes those parts as ONE order and ships them together. Tell the user which it is, in the words of shipping.reason. Name a shipping saving ONLY when shipping.saved_cents is above zero, and only that amount — never promise or hint at a saving for buying several parts from one shop otherwise. When shipping.code is "speeds_differ", the parts of that shop are picked at different shipping speeds; you may tell the user that the shop sends parts together only at one speed, and read the cart again after they change a pick — do not state what it would save before the cart shows it. HOW A CART WORKS: each part in a cart IS a quote — its material, finish, quantity, rules and its pick (selection) live on that part's quote, and nothing is kept twice. To change a part, call refine_quote on its quote_id and pass cart_item_id: the cart follows the part to the new quote by itself. To pick the option to order for a part, store the pick on its quote (refine_quote selection). The cart_id is the only key to the cart — whoever holds it can read and change it — so give it only to the user it belongs to, and never put it in a link you did not get from the network.
Schema valid · SHA-256 35a50c2e95c8…
View input schema
{
"type": "object",
"properties": {
"cart_id": {
"type": "string",
"description": "The cart to check out (cart_…)"
},
"idempotency_key": {
"type": "string",
"minLength": 8,
"maxLength": 200,
"description": "One unique string for THIS attempt to pay for the cart, made up by you (letters and digits, 8 or more). Send the same string only to repeat the very same call; after any change to the cart or the details, make up a new one"
},
"only_selected": {
"type": "boolean",
"description": "true = order the parts that have a pick and leave the rest in the cart. Default: a part with nothing picked refuses the whole cart"
},
"coupon": {
"type": "string",
"description": "Coupon code, only if the user provided one. Applied once to the cart total. Never invent or guess a code."
},
"check": {
"type": "boolean",
"description": "Default true: each picked part whose shop has to confirm it is confirmed by this call (one shop per part), which waits for the answers (wait_s). false = ask nobody and judge the cart as it stands. Usually OMIT"
},
"wait_s": {
"type": "integer",
"minimum": 0,
"maximum": 120,
"description": "Seconds this call may wait for the shops (default 45). When it runs out first the cart is refused with the waiting parts named — send the same call again"
},
"max_total_cents": {
"type": "integer",
"minimum": 0,
"description": "The most the user agreed to pay for the cart, in cents, before any coupon: the cart's total_cents as you showed it. At or under it the checkout is made; a higher confirmed total is refused once (price_went_up) and nothing is created. Leave it out and the network compares with the prices it last told this cart's reader"
},
"pay": {
"type": "string",
"enum": [
"saved"
],
"description": "\"saved\" = charge the card saved on your AFN key instead of returning a payment page. Needs that key on the connection, plus idempotency_key, the shipping address, the buyer's email and max_total_cents. Usually OMIT"
},
"return_url": {
"type": "string",
"description": "Exact URL of the page the user is on right now, IF the client application knows it. The page after payment shows a 'Return to <site>' button pointing here. Omit when unknown — never invent one."
}
},
"required": [
"cart_id",
"idempotency_key"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}