Skip to content

Checkout

Take a customer from a cart to a paid order, confirming the payment with Stripe.js in your own page.

Updated

A purchase is a cart the customer fills, presents for payment and pays in your page, with Stripe.js. Every step needs a signed-in customer whose token holds checkout:write (Authentication); reading carts needs read. The examples use the client from Your own front end.

  1. Open a cart

    POST /v1/stores/{store}/checkouts opens one in a currency, the currency of the offers you show.

    curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/checkouts' \
      --header 'Authorization: Bearer ctk_...' \
      --header 'Content-Type: application/json' \
      --data '{ "currency": "eur" }'
  2. Put prices in it

    PUT /v1/stores/{store}/checkouts/{checkout}/items sets a line: the offer’s id as the price, and a quantity (1 to 99; 0 takes the line out). Each line is priced at the offer the customer gets now.

    curl --request PUT 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/checkouts/<checkout id>/items' \
      --header 'Authorization: Bearer ctk_...' \
      --header 'Content-Type: application/json' \
      --data '{ "price": { "id": "<price id>" }, "quantity": 1 }'

    A tip or a donation also takes the display_name it’s left under (up to 20 characters) and a message (up to 255), which null clears; the order’s line keeps them.

    An event’s tickets take guests: an email and an optional name for each ticket past the buyer’s own, or for every ticket when the buyer isn’t going. Freezing the cart refuses it with invalid while a ticket has no guest, or names the buyer, one person twice, someone already going or a guest erased since (erased, a slot with an empty email, which asks for someone else); the error’s path points at the line and the guest (items, the line, guests, the guest). An event that waits for the seller’s approval takes no guests, as its request seats the buyer alone.

  3. Answer the product's questions

    A product may ask its buyers questions, listed in order as questions on its product read. While the cart holds it, PUT /v1/stores/{store}/products/{product}/answers answers them; see Registration questions.

  4. Apply a coupon

    PUT /v1/stores/{store}/checkouts/{checkout}/coupon names one as its code: a discount’s code, or its id, as an affiliate link carries it. null takes it off.

    curl --request PUT 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/checkouts/<checkout id>/coupon' \
      --header 'Authorization: Bearer ctk_...' \
      --header 'Content-Type: application/json' \
      --data '{ "code": "WELCOME10" }'
  5. Present it for payment

    POST /v1/stores/{store}/checkouts/{checkout}/freeze checks every line still prices as it did, holds an event’s seats, and the cart stops changing. An event without enough seats left answers 409 conflict on items, with current the fewest seats left, and a product whose required questions the customer hasn’t all answered, or whose text answers don’t all fit their pattern, answers 409 conflict on questions.

  6. Start paying

    POST /v1/stores/{store}/checkouts/{checkout}/pay answers what your page confirms with Stripe, or the order when nothing is due.

  7. Confirm in your page, then here

    Confirm the payment with Stripe.js, then call POST /v1/stores/{store}/checkouts/{checkout}/confirm, which reads it back from Stripe and answers the order once it’s paid.

Opening a cart, setting a line or a coupon, freezing it and abandoning it each answer the cart as it stands; pay and confirm answer the payment’s state instead (below):

setCheckoutItem 200json
{
  "id": "<checkout id>",
  "status": "open",
  "currency": "eur",
  "exponent": 2,
  "items": [
    {
      "id": "<line id>",
      "product_id": "<product id>",
      "price_id": "<price id>",
      "product": { "id": "<product id>", "slug": "intro-course", "title": "Intro course", "category": "course", "deleted": false },
      "quantity": 1,
      "amount": 4900,
      "discount": 490,
      "discount_id": "<discount id>",
      "total": 4410,
      "mode": "purchase",
      "autorenew": null,
      "display_name": null,
      "message": null,
      "refund_policy": "30d",
      "refund_until": "2026-12-03T10:00:00.000Z"
    }
  ],
  "totals": { "amount": 4900, "discount": 490, "total": 4410 },
  "coupon": "WELCOME10",
  "refund_consent": null,
  "refund_waiver": null,
  "card_required": null,
  "under_minimum": null,
  "order": null,
  "expires_at": "2026-11-03T11:00:00.000Z"
}

A cart is open while it changes, frozen once presented for payment, paid once its order exists (order, { id, number }), and abandoned or expired otherwise. A line’s mode is purchase, upgrade (a higher tier of what the customer holds) or renewal. A plan a customer subscribes to while a grant with an end still gives them its tier charges nothing now: its offer and, once frozen, its line read first_charge_at, when the first charge falls (a day before the grant ends, as every renewal is charged a day ahead), and the subscription starts billing then; null on every other line. A line’s refund_policy is the refund window it sells under as the store sets it now, a frozen cart included (none, 24h, 72h, 7d, 14d or 30d; the price’s own, else its product’s; null when neither sets one), and refund_until, while the cart is open or frozen, is until when a purchase made now may be refunded (null for none, no policy, or a cart that can no longer be paid). Show it as is: it moves on each time you read the cart. A frozen cart keeps the policy the customer consented to in refund_waiver.

Registration questions

A product’s questions each have a kind: text (one line, up to 300 characters), long_text (up to 3,000, line breaks kept), select (one of its options), multi_select (any of them, as a list) or checkbox (true or false). A required one must be answered before the cart freezes, and a required checkbox must be ticked. A text question may carry a pattern, which the whole answer must match; match it in your page by the same rules the API does, a safe subset of JavaScript’s syntax (characters, ., classes, \d \w \s, groups, |, repeats up to 100), so a buyer sees the problem before continuing. A patterned question may carry an example too, an answer that fits its pattern (null for none): show it as the format to follow, under the question and in the error when an answer doesn’t fit. A free product asks them when it’s claimed, through the same freeze, and a subscription once when it starts; its renewals ask nothing.

PUT /v1/stores/{store}/products/{product}/answers takes answers, one per question, each naming its question by id and its value, and the checkout they’re given in: named, it must be the customer’s own open or frozen cart holding the product, or nothing is written and it answers 404 not_found on checkout, so a page left open as someone else never writes over the signed-in customer’s answers. A question left out keeps its answer, and null clears one that isn’t required. Text is trimmed, a value that doesn’t fit its question, its pattern included, answers 422 invalid at its path, and clearing or unticking a required one answers invalid with the reason required. It takes answers only while one of the customer’s open carts holds the product, or while their access to it holds or is due to, and otherwise answers 409 conflict on items.

GET /v1/stores/{store}/products/{product}/answers reads the customer’s answers back, so your page can fill them in: a customer buying again keeps theirs, and is asked only a question added since, one whose choice was taken off, or one whose answer no longer fits a pattern changed since. A stored answer reads back as given, so match it against its question’s pattern before continuing. The answers of a customer who never registers go once no cart of theirs holds the product and no payment of theirs may still settle: soon after a cart is given up, expires or loses the product’s line.

curl --request PUT 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/<product id>/answers' \
  --header 'Authorization: Bearer ctk_...' \
  --header 'Content-Type: application/json' \
  --data '{ "answers": [{ "question": "<question id>", "value": "Ada Lovelace" }, { "question": "<question id>", "value": true }] }'

When a line’s refund policy is shorter than the customer’s statutory window, the customer must consent to it in your page. An open cart says so ahead in refund_consent, the policy to consent to (none, 24h, 72h or 7d; null when none is asked), so your page asks before freezing. Send their consent as refund_waiver, the policy they consented to (true is taken too):

curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/checkouts/<checkout id>/freeze' \
  --header 'Authorization: Bearer ctk_...' \
  --header 'Content-Type: application/json' \
  --data '{ "refund_waiver": "24h" }'

Without it, or with a policy other than the one asked now, the freeze answers 422 invalid at ["args", "refund_waiver"], naming the policy: read the cart and ask again. A frozen cart keeps the consent as refund_waiver, with when it was given.

An app the store hasn’t verified is refused a cart that asks for this consent, and any refund_waiver, as 403 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.

Paying

pay answers one of these, by status:

status Do
paid Nothing is due: show the order.
requires_payment Confirm the payment with Stripe.js, then call confirm.
processing The payment is settling: call confirm again later.
requires_setup Nothing is charged now, but a plan in the cart will charge its first renewal: save a card with Stripe.js’s confirmSetup, then call confirm.
setup_processing Stripe is checking the card: call confirm again later.
cancelled The payment was called off.
refunded, refund_pending, refund_failed The payment was given back, is being given back, or couldn’t be (the store settles it with the customer). A refund the customer’s bank returns later turns refunded into refund_failed.
payCheckout 200json
{
  "status": "requires_payment",
  "payment": {
    "processor": "stripe",
    "client_secret": "pi_..._secret_...",
    "publishable_key": "pk_live_...",
    "account": "acct_...",
    "instrument": null,
    "confirm_by": "2026-11-03T11:15:00.000Z",
    "amount": 4410,
    "currency": "eur",
    "exponent": 2
  }
}

Load Stripe.js with the payment’s publishable_key, its account as the connected account, and its client_secret. showOrder, showWaiting, showProblem and the other show functions stand for your page’s own:

import { loadStripe, type Stripe, type StripeElements } from '@stripe/stripe-js';
import { Problem, sherpo } from './sherpo';

type Payment = {
  client_secret: string;
  publishable_key: string;
  account: string;
  instrument: string | null;
  confirm_by: string;
};
type Pay =
  | { status: 'paid'; order: { id: string; number: number } }
  | { status: 'requires_payment' | 'processing'; payment: Payment & { amount: number; currency: string; exponent: number | null } }
  | { status: 'requires_setup' | 'setup_processing'; setup: Payment }
  | { status: 'cancelled' | 'refunded' | 'refund_pending' | 'refund_failed' };

/** Starts paying a frozen cart and mounts the payment form when there is something to confirm. */
export async function startPaying(checkout: string, token: string) {
  const answer = await sherpo<Pay>(`/checkouts/${checkout}/pay`, { token, method: 'POST', body: {} });
  if (answer.status !== 'requires_payment' && answer.status !== 'requires_setup') return show(answer);
  const { publishable_key, account, client_secret, confirm_by } = 'payment' in answer ? answer.payment : answer.setup;
  const stripe = await loadStripe(publishable_key, { stripeAccount: account });
  if (stripe === null) throw new Error('Stripe.js could not load.');
  const elements = stripe.elements({ clientSecret: client_secret });
  elements.create('payment').mount('#payment');
  return { stripe, elements, setup: answer.status === 'requires_setup', confirm_by };
}

type Form = { stripe: Stripe; elements: StripeElements; setup: boolean; confirm_by: string };

/** When the customer presses Pay: confirms with Stripe, then reads the outcome back. */
export async function submitPayment(checkout: string, token: string, { stripe, elements, setup, confirm_by }: Form) {
  const confirmParams = { return_url: 'https://www.example.com/checkout/return' };
  const { error } = setup
    ? await stripe.confirmSetup({ elements, redirect: 'if_required', confirmParams })
    : await stripe.confirmPayment({ elements, redirect: 'if_required', confirmParams });
  // A card the customer must fix stays here; any other error may hide a payment that went through.
  if (error?.type === 'card_error' || error?.type === 'validation_error') return showProblem(error.message);
  let answer: Pay;
  try {
    answer = await sherpo<Pay>(`/checkouts/${checkout}/confirm`, { token, method: 'POST', body: {} });
  } catch (failed) {
    return recover(checkout, token, failed, confirm_by);
  }
  return show(answer);
}

/** After a failed `confirm`: the payment may have gone through, so read the cart back before offering to pay again. */
async function recover(checkout: string, token: string, failed: unknown, confirmBy: string) {
  const cart = await sherpo<{ status: string; order: { id: string; number: number } | null }>(
    `/checkouts/${checkout}`,
    { token },
  ).catch((readBack: unknown) => {
    const said = failed instanceof Error ? failed.message : String(failed);
    throw new AggregateError([failed, readBack], `The payment and the cart could not be read: ${said}`);
  });
  if (cart.order !== null) return showOrder(cart.order);
  // A refusal stays refused, as does a fault of the API's own; anything else may pass.
  const fault = failed instanceof Problem && String(failed.body.type).endsWith('#client-fault');
  const passing =
    !(failed instanceof Problem) || (!fault && (failed.status < 400 || failed.status === 429 || failed.status >= 500));
  // `confirm` still answers on an expired cart until `confirm_by`, so a settling payment is worth waiting on until then.
  const open = cart.status === 'frozen' || (cart.status === 'expired' && Date.now() < Date.parse(confirmBy));
  if (open && passing) return showWaiting(confirmBy);
  throw failed;
}

/** Shows what `pay` or `confirm` answered. */
function show(answer: Pay) {
  switch (answer.status) {
    case 'paid':
      return showOrder(answer.order);
    case 'processing':
    case 'setup_processing':
      // Settling: call `confirm` again in a while.
      return showWaiting('payment' in answer ? answer.payment.confirm_by : answer.setup.confirm_by);
    case 'requires_payment':
    case 'requires_setup':
      return showProblem('Your payment didn\'t go through. Try again, or use another method.');
    default:
      // Called off or given back: the cart can't be paid any more.
      return showClosed(answer.status);
  }
}

confirm 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 method that redirects (a bank’s page) comes back to your return_url: call confirm there.

For requires_setup, the snippet confirms with stripe.confirmSetup and the setup’s publishable_key, account and client_secret instead. Tell the customer nothing is charged now and the card pays the first renewal, on the line’s first_charge_at when it has one. confirm then 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. An open or frozen cart that will ask for one reads card_required: { "reason": "renewal" } ahead.

Time to confirm

The payment or setup carries confirm_by, the latest time confirm takes it: the cart’s expires_at plus 15 minutes, or 15 minutes after the payment started on a cart that never expires. 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 answers 409 conflict (expired), though confirm still answers until confirm_by. A payment not confirmed by then is called off, unless it’s already processing, and the cart may close sooner. Asking to pay again answers the same payment.

Saved cards

To pay with a card the customer saved, send its id from GET /v1/stores/{store}/billing_profile as instrument:

{ "instrument": { "id": "<instrument id>" } }

It counts only when the payment starts: naming another card while one is still to confirm answers 409 conflict (paying), a card that isn’t the customer’s answers 404 not_found, and a cart that saves a card for its renewals (requires_setup) takes a saved card alone, any other saved method answering 422 invalid on instrument. The payment or setup names the saved card it runs on as instrument (null for a new card), 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) while it’s still to confirm, as 403 not_permitted (principal): abandon that cart and open another, which the customer pays with a card entered in your page.

Totals under the minimum charge

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; it 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 is granted free then: pay answers paid (or requires_setup, when a plan in it will charge its first renewal), and under_minimum.minimum is null.

The store’s Meta pixel

Where the store sends purchase events to its Meta pixel, pay also takes attribution: the _fbp and _fbc cookies (fbp, fbc), the customer’s client_ip_address, client_user_agent, country, city, region, postal_code and the source_url the payment started from. They’re kept for that event alone.

Giving up, and failures

POST /v1/stores/{store}/checkouts/{checkout}/abandon gives a cart up; a frozen one hands its coupons and an event’s seats back. A frozen cart nobody pays expires on its own at expires_at and hands them back too; while a payment it started is still out, they stay held for it.

No write takes an idempotency key. After a call that failed or never answered, read the cart back (GET /v1/stores/{store}/checkouts/{checkout}, or the customer’s open and frozen carts with GET /checkouts) before trying again, rather than opening another.

A store that pauses new purchases answers 403 not_permitted (paused), while renewing what the customer already holds still goes through.

After the purchase

Guests

GET /products/{product}/guests lists the guests a customer bought an event’s tickets for, each with the order_id it came in, its status and opened_at, set once the guest signed in holding it or was let in at the door, attending, whether the customer is going themselves, and lines, which of their order lines kept a ticket for them (buyer_ticket). Until the guest opens their ticket, and before the event starts (changeable), PUT /products/{product}/guests/{guest} hands it to someone else (an email and an optional name), and while it stands (resendable), POST /products/{product}/guests/{guest}/resend sends its email again. A burst of resends sends one email, and once a guest got three in a day, a resend is refused with not_permitted and a retry_at. A guest the store erased has no address left, so their ticket isn’t resendable and a resend is refused with conflict on status, current erased.

A paid cart reads its order. What the customer bought then shows in their library: GET /entitlements, and owned and access on the product.

Approval and waitlists

A product whose settings.approval is required lets each buyer in only once the seller approves them. It sells one-time offers alone, free or paid: a recurring price isn’t among its offers (the seller’s checkout preview names it approval_required), and neither is an upgrade to a higher tier for a customer who already holds it. A product bought again and again, like a tip, asks again with each purchase. Its checkout runs as above and its order is recorded, but the customer isn’t granted it: the purchase settles as a request, pending, and the customer is emailed that it was sent. An event keeps the seats the order took while the request waits. Once the seller approves, the customer holds the product and is emailed; a decline gives the seats back and emails them too.

At a paid offer, nothing is charged at checkout: the cart’s card_required reads { "reason": "approval" }, open, frozen and once paid, and paying it answers a setup (as for a plan’s first renewal) that saves the customer’s card. Tell them the card is charged once the seller approves. Such a line checks out alone: presenting a cart that holds anything beside it answers 409 conflict on items. The seller’s approval charges the saved card. When the card refuses it, the request stays pending with its payment due and a checkout to pay it through, and the customer is emailed a link to it: pay that cart as any other, and once it’s paid, the request is approved. Once the event’s last session ended, or the event was canceled, paying it answers 409 conflict on request with current closed and reason the event has ended, and a payment the customer made as it ended is given back.

A product whose settings.approval_payment is hold holds the total on the customer’s card instead: the cart’s card_required reads { "reason": "hold" }, and paying it answers a payment (cards only) that Stripe authorizes rather than charges. Tell them the total is held now and charged once the seller approves. confirm answers paid once it’s held, with the order the request recorded, though the cart stays frozen until the seller decides: approving takes the amount held, declining releases it. Card holds last about 7 days, so one the seller hasn’t decided a day before it lapses is released, the request is declined and the customer is emailed that nothing was charged. A hold that can’t be taken on approval leaves the request due, paid as above.

The product reads (GET /products and GET /products/{product}) carry the signed-in customer’s open request for it, else their latest, null for none and for a visitor:

{ "id": "<request id>", "status": "pending", "tier_rank": 1, "payment": null, "checkout": null, "created_at": "2026-11-02T18:40:00.000Z" }

status is pending (waiting for the seller), waitlisted, approved or declined, and tier_rank the rank of the tier it asks for. A paid request’s payment is saved while its card waits for the seller, held while its total is held on the card, charging once approved and due once the customer is to pay it themselves, through the cart checkout names; null for a free one. Show a pending or waitlisted request in place of the buy button, and a due one as a way to pay. While the product requires approval and one waits, adding it to a cart, presenting a cart that holds it or paying for one presented before the request was sent answers 409 conflict on request, with current its status. A cart refused at payment stays presented and keeps its seats until it expires or is abandoned. A payment that started before another cart sent the request still settles, but its approval line opens no second request and takes no seat; a total held on the card instead is let go, and the cart reads cancelled. A declined customer may ask again.

An event whose event.waitlist is true takes a waitlist once the seats a customer asks for are gone (sold_out, or a ticket type’s spots_left under the quantity). POST /v1/stores/{store}/products/{product}/waitlist, with checkout:write, puts the signed-in customer on it at a one-time offer, free or paid, for a quantity of 1 to 99 (1 when left out):

curl --request POST 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/<product id>/waitlist' \
  --header 'Authorization: Bearer ctk_...' \
  --header 'Content-Type: application/json' \
  --data '{ "price": { "id": "<price id>" }, "quantity": 1 }'

It answers the request, waitlisted, with paid saying whether its ticket is charged on promotion, and the customer is emailed they’re on the list. They hold no seat while they wait. Once seats free, the seller can let them in: an order takes their seats, and a free ticket is theirs at once, by email too. A paid one is charged then, at the price they joined at, on the card they saved for their place, else on their default saved card; with neither, or when the charge fails, they’re emailed a link to pay for the seat held for them. It answers 409 conflict on request with current available while the seats are left (buy instead), closed for an event with no waitlist or one no longer sold, held for a customer who already holds a ticket, and pending or waitlisted while they already have an open request for it; a product that isn’t an event answers conflict on category, and a recurring price 422 invalid at ["args", "price"]. A customer who buys a freed seat themselves leaves the waitlist, their request approved.

At a paid ticket, save the card the promotion charges: POST /v1/stores/{store}/products/{product}/waitlist/card, with checkout:write, answers requires_setup with a setup to confirm with stripe.confirmSetup (cards only, nothing charged), or setup_processing while Stripe checks it. Call it again once confirmed: it answers saved once the card is kept on the place. A place with no paid ticket answers 409 conflict on request with current free, and one the customer doesn’t hold 404 not_found. An app the store hasn’t verified can’t call it.

Type to search…

↑↓ navigate↵ selectEsc close