Portal SSO

The buyer you are vouching for. This becomes their portal login identity, so the embedded checkout pre-fills it and LOCKS it — a buyer who is not this person uses the checkout's own escape rather than typing over it, and a confirm carrying a different address is refused. Distinct from contactEmail below, which is only where the paperwork goes.

Where invoices and receipts should go, when that differs from the login identity above. Written to the customer's default contact. Omit and billing follows email.

A customer you already hold the LedgerBee id for - typically one whose earlier subscription ended and who is now buying again. The purchase lands on that record instead of a second one, so a returning buyer does not accumulate duplicates. The customer must exist, be active, and belong to the API key's tenant; otherwise the mint returns 404 CUSTOMER_NOT_FOUND and nothing is minted.

This does not make the checkout read-only: the Details step still shows only what you prefilled, never the stored record, and whatever the buyer submits is written over the record at confirm. Omit for a first-time buyer - creating the customer at confirm is the default.

Optional starting values for the checkout Details step. Every field stays EDITABLE — this is a convenience for the buyer, never an assertion of fact, and whatever they submit is what we persist. Anything you omit renders empty.

Whether the buyer may reject the vouched identity and continue as an anonymous buyer (the checkout shows a "Not you?" escape). It does NOT let them type a different address - the vouch is dropped and the checkout restarts unvouched, because we cannot vouch for someone we were not told about. Defaults to true: a buyer who genuinely is not the person you named has no other way out, and stranding them is worse than showing a link. Set false when your authentication makes a wrong identity impossible.

Your own opaque reference for this order (Stripe client_reference_id parity). It rides onto the created subscription (as partnerReferenceId), into every later subscription webhook, AND onto the customer.created event — which is the only field that maps a brand-new customer back to the cart that created it. Pass it. Server-to-server only; it never reaches a client/iframe surface. Max 200 chars, [A-Za-z0-9_-] only.

Email of the partner-provisioned user. Links a first-time SSO login to an existing invited customer-portal user.

The partner's stable, unique identifier for the user. Keyed together with the per-tenant handoff issuer to resolve the portal user across logins.

At least one customer membership to grant this user — required. The customer's portal organization (an opaque internal container) and the membership are created automatically server-side at redeem, so a prior provision call is NOT needed; you only ever reference customers, never organizations. Validated at mint: a customerId that isn't a customer of the API key's tenant, or an unknown role, is rejected with a 400 (rather than failing the user's browser redirect). A handoff with no membership can't establish a portal session, so an empty/omitted array is rejected here rather than minting a ref that would fail at redeem.

Display name of the user; used to populate the customer-portal user's name on first login.

Email of the portal user to grant access to. A credential-less portal user is created if none exists.

The customer's LedgerBee id. The customer must already exist in the API key's tenant; this endpoint never creates one from an id (a 404 CUSTOMER_NOT_FOUND is returned if it doesn't). Supply either customerId or a customer payload.

A customer to upsert, identified idempotently by its customerNumber: an existing customer of the API key's tenant with that number is reused, otherwise a new one is created with this payload. Same shape as the gated POST /customers request (so vatZone and countryCode are required here). If customer.email is omitted, the portal-user email below is used as the customer's contact email (and its auto-created default contact). Supply either this or customerId.

Membership role to grant. Defaults to USER; the org's first member is force-assigned OWNER regardless.

Display name of the portal user (set on first creation).

Display name for the customer organization (first-invite bootstrap).

When true, also mint a back-channel handoff reference in the same call (one round-trip "Go to portal"). Requires the API key to ALSO carry the portal-sso-mint scope, and the tenant to have back-channel handoff enabled.

The partner's stable, unique user identifier — required when mintHandoff is true; keys the handoff identity (with the per-tenant handoff issuer).

When true, also mint a one-time CHECKOUT-BIND reference in the same call — an opaque token the partner's fetchBindToken provider returns to the embed at checkout-start so the embedded checkout subscribes directly against THIS customer instead of staging an anonymous magic-link signup. Requires the API key to ALSO carry the portal-sso-mint scope. Independent of mintHandoff (login): a checkout-bind ref can never mint a login session.

Your own opaque reference for this order (Stripe client_reference_id parity), e.g. your internal order or cart id. It rides the minted checkout-bind ref onto the resulting subscription (as partnerReferenceId) and into every later subscription webhook, so you can reconcile our subscription to your record. Server-to-server only — it never reaches a client/iframe surface. Max 200 chars, [A-Za-z0-9_-] only.

The partner's stable subject id for the user — the same sub used when minting their handoff. Every active portal session of that user is force-refreshed.