Checkout Sessions

curl -sg -X POST \
  "$FM_API/ingestions/$TASK_ID/checkout-session" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -H "x-api-key: $FM_API_KEY" \
  -d '{"ui_mode":"embedded","return_url":"https://app.epoch.blue/pay/done","price_checksum":"ef70656f…"}'

{
  "meta": {},
  "links": { "self": "/ingestions/…/checkout-session" },
  "data": {
    "type": "checkout_session",
    "attributes": {
      "ui_mode": "embedded",
      "client_secret": "cs_test_…_secret_…",   // mount the embedded form with this
      "publishable_key": "pk_test_…",          // pass to loadStripe() first
      "url": null,                             // hosted mode sets this instead
      "stripe_session_id": "cs_test_…",
      "status": "pending",
      "units_expected": 5,
      "checkout_source": "fixture",
      "pricing_version": 1,
      "price_checksum": "ef70656f…",           // equal to the estimate's, for the same selection
      "currency": "usd",
      "units": [ /* one entry per billable unit, as on the estimate */ ],
      "checkout_items": [ /* one entry per rolled-up row, as on the estimate */ ],
      "amount_subtotal": 75000,
      "amount_discount": 30000,
      "amount_tax": null,
      "amount_total": 45000,
      "tax": { "behavior": "exclusive", "exempt": "none", "tax_ids": [], "determined": false }
    }
  }
}

The Stripe session and the checkout_session row are written in one request. Stripe can deliver the webhook within milliseconds, so a row written afterwards would race it.

The task must be a screening run, and the caller's org API key must have been issued for the self-serve journey (key_type is self_serve) if it is an org key. A full run is not chargeable through this route, and neither is an org key of another type — both return 422 CHECKOUT_TASK_NOT_ELIGIBLE. A member key carries no key_type, so the rule does not apply to it.

The same rule applies to whoever created the task. An ingestion uploaded with a self_serve org key or by a member (a member key or an OAuth bearer) is chargeable. One a direct org key created is not, whichever key asks, and neither is an ingestion created before the creator was recorded. Both return the same 422 CHECKOUT_TASK_NOT_ELIGIBLE.

The key needs the billing:write scope, which is admin-only. The GET needs only billing:read.

unit_ids takes the same two forms as the estimate: loc:<uuid> for a facility or shed, cluster:<n> for a plot cluster. At most 500.

The body is strict. Any field not listed above is a 400, including anything that looks like it might set the price.

// 400 CHECKOUT_PRICE_CHECKSUM_MISMATCH
{
  "data": {
    "error": "The price changed since this quote. Confirm the new estimate.",
    "code": "CHECKOUT_PRICE_CHECKSUM_MISMATCH",
    "tracking_id": "…",
    "details": {
      "expected": "a8c2bb35…",       // what the selection costs now
      "received": "ef70656f…",       // what you sent
      "estimate": { /* the full fresh estimate */ }
    }
  }
}

// 409 CHECKOUT_SUBSCRIPTION_EXISTS
{
  "data": {
    "error": "This organisation already has a subscription.",
    "code": "CHECKOUT_SUBSCRIPTION_EXISTS",
    "tracking_id": "…",
    "details": { "plan_key": "starter", "status": "active" }
  }
}

Identical in shape to the cost estimate, plus the session fields. The same component renders both.

units_expected = chargeable

A repeated submit for the same task and selection returns the existing session. It does not create a second one. The guarantee is a partial unique index on (asset_task_id, selection_digest) for pending rows, not a read-then-write, so two concurrent requests cannot both win.

The selection is what identifies a purchase — unit_ids, with order and duplicates ignored. A loc: id's uuid is matched case-insensitively, so two spellings of one id are one purchase. (A cluster:<n> id is digits, so case cannot arise.) ui_mode and return_url are excluded: opening the same purchase in an embedded form and in a browser is still one purchase.

Rarely, a concurrent request holds the claim but has not yet recorded its Stripe session id. That answers 409 CHECKOUT_SESSION_PENDING and is retryable.

For a page that reloads mid-payment.

curl -sg "$FM_API/ingestions/$TASK_ID/checkout-session" \
  -H "accept: application/json" -H "x-api-key: $FM_API_KEY"

Returns the pending session in the same shape as the POST, with a fresh client_secret, or 204 when nothing is in flight.

It carries no body, so it cannot name a selection — it returns the newest pending session for the task, priced against the selection that session was created with. 204 also covers a claim that has not finished being created.

Every session is created with automatic_tax, tax_id_collection, billing_address_collection and customer_update set, so Stripe collects a VAT number and computes tax against a billing address.

amount_tax is null until Stripe determines it, and 0 when none is due. They are different answers. Rendering null as zero shows a confident zero where the real answer is "not yet known".

Stripe only collects tax where the account holds an active registration, and reports no error where it does not. A zero tax figure is not proof that no tax is due.

Each line states its own tax_behavior, taken from the estimate rather than left to the Stripe account default. One of the three account settings treats a non-USD amount as tax inclusive, which would quietly contradict the exclusive the response reports.

product_data.tax_code is specified but not implemented. Stripe therefore applies the account's default tax category to every line. Raise it with the billing owner before relying on a per-product rate.

CHECKOUT_NOTHING_CHARGEABLE is not always a failure. Read the message, not just the code — it carries four causes, and only two mean "nothing to pay":

Stripe calls POST /callbacks/stripe, which resolves the row to paid and appends a grant of units_expected to the credit ledger. The grant is keyed on the Stripe event id, so a redelivered event does not grant twice.

Nothing in that path reads a unit count from Stripe metadata. The row is the only source of the granted figure, because metadata is writable by anyone holding an API key.

POST /organizations/:id/checkout-sessions buys a pack of credits into the organisation's balance, with no task behind it. It is what the billing page uses to top up.

{ "units": 40, "ui_mode": "hosted", "return_url": "https://app.epoch.blue/settings/billing" }

• units is 1 to 10060 (UNITS_EXPECTED_MAX). Each credit costs the pay-as-you-go price, which GET /organizations/:id/credits/subscriptions returns as payg_unit_amount. There is no estimate and no price_checksum, because nothing about the price depends on an ingestion. Stripe adds tax at the payment form.
• Only a self-serve org key or a member key can buy. Any other org key gets 422 CREDIT_CHECKOUT_NOT_ELIGIBLE, and so does a member key for an organisation whose credits are not enforced, since its runs never spend them. The route needs billing:write.
• An organisation holds one pending pack at a time. Sending the same units and ui_mode again returns the open session. Sending different ones expires the open session at Stripe and creates a new one, so an abandoned checkout never blocks the next purchase.
• While the previous pack is completing payment, the route answers 409 CHECKOUT_SESSION_PENDING. The balance updates once that payment settles.

After payment the callback grants units_expected, exactly as for a task checkout. Poll GET /organizations/:id/checkout-sessions/:sessionId with the stripe_session_id from the response until it reads paid. A refund reverses the pack's credits, up to the balance still available.

POST /organizations/:id/subscription/checkout-session buys a subscription plan — or upgrades the one the organisation holds — with no task behind it. It is the org-level twin of the pack route above: a pack grants the units bought, a plan grants that tier's yearly allowance. Both write to the same credit ledger, so there is one balance either way.

{ "plan": "growth", "ui_mode": "hosted", "return_url": "https://app.epoch.blue/settings/billing" }

• plan is starter, growth or pro. The body is strict: an unknown key is a 400, and so is plan: null — omit it or name a tier.
• return_url is matched on the parsed origin against the same allowlist the other checkout routes use, so an unlisted origin is a 400.
• ui_mode defaults to hosted, which suits a subscription page. embedded returns a client_secret instead of a url.
• Only a self-serve org key or a member key can buy, and the route needs billing:write. Any other org key gets 422 CREDIT_CHECKOUT_NOT_ELIGIBLE; an organisation outside the key's scope gets 404.

// 200
{
  "meta": {},
  "links": { "self": "/organizations/…/subscription/checkout-session" },
  "data": {
    "type": "subscription_checkout_session",
    "attributes": {
      "ui_mode": "hosted",
      "client_secret": null,             // set for `embedded`, null for `hosted`
      "publishable_key": "pk_test_…",
      "url": "https://checkout.stripe.com/c/pay/cs_test_…",  // null for `embedded`
      "stripe_session_id": "cs_test_…",
      "units_expected": 28,              // Growth credits 28 supplier locations a year
      "plan_key": "growth",
      "amount_subtotal": 300000,         // the annual price in cents, before tax
      "currency": "usd"
    }
  }
}

units_expected is what the completed payment grants into the ledger: exactly the tier's yearly allowance. This route sells no units of its own, so there is no top-up term beside it — that figure belongs to the ingestion checkout above. amount_subtotal is the annual price of the tier alone: Starter 100000, Growth 300000, Pro 500000. Stripe adds tax at the payment form.