Portal Plans
List the full plan catalogue
Credential: a company's API key or OAuth token.
Returns every ACTIVE plan with a PUBLISHED version in the API key's tenant, projected as its canonical native card and ordered by display order. This is the integrator's FULL catalogue — it does NOT run the per-buyer rule engine, does NOT filter by any plan-routing visibility rule, and mints NO token. Use it to read all your plans (e.g. to build pricing pages), as opposed to resolve, which returns only the subset a specific buyer matches.
Required Scope
portal-catalog-read
query Parameters
customerTypeBuyer customer type for gross-price resolution.
vatNumberBuyer VAT number for gross-price resolution. Accepted only with customerType: 'BUSINESS' (a coded 400 otherwise). Requires a country hint to have any effect. On the resolve read it is ignored when customerId is supplied — a customer-backed resolve stays net-only.
currencyPresentment currency for every card's pricing. Must be in each card's availableCurrencies; cards that can't resolve it render null prices. Defaults to each card's own currency.
languageLanguage the resolved cards are localized to. Defaults to en.
countryBuyer country (ISO 3166-1 alpha-2) for gross-price resolution. With customerType, each card's vat block resolves through the same VAT authority the checkout quote uses; without hints every card is net-only (vat.resolved: false).
discountCodeA discount code a buyer typed. Each SUBSCRIPTION card then carries discount: the code priced for that card's first period exactly as the checkout quote prices it (the first invoice before VAT with the code, firstPeriodNetMinor; what the code takes off it, firstPeriodAmountOffMinor; and the day the regular price starts, endsAt). A card the code cannot price carries discount: null. A code that is unknown, used up or not for this buyer is refused with its DISCOUNT_* code. A request naming a code spends one use of the code-attempt budget this API key shares with the checkout quote, the session and the discount cart check. Without it, or with a code of spaces alone, no card carries discount.
List the full plan catalogue › Responses
Every ACTIVE plan with a PUBLISHED version in the API key's tenant, projected as its canonical native card and ordered by display order. This is the integrator's full catalogue — NOT filtered by any per-visitor visibility rule and NOT run through the plan-routing rule engine — though a plan whose every card references a retired/archived subscription template is omitted (nothing renderable or sellable remains). Each entry carries the full card content the integrator renders.
Get a plan
Credential: a company's API key or OAuth token.
Returns a single plan by its id, projected as its canonical native card — the integrator's by-id read. Does NOT run the rule engine and does NOT filter by visibility rules: every published plan of the tenant resolves here. Returns 404 PORTAL_PLAN_NOT_FOUND only when the plan id is unknown to the tenant or has no published version.
Required Scope
portal-catalog-read
path Parameters
planIdThe plan id (uuid).
query Parameters
customerTypeBuyer customer type for gross-price resolution.
vatNumberBuyer VAT number for gross-price resolution. Accepted only with customerType: 'BUSINESS' (a coded 400 otherwise). Requires a country hint to have any effect. On the resolve read it is ignored when customerId is supplied — a customer-backed resolve stays net-only.
currencyPresentment currency for every card's pricing. Must be in each card's availableCurrencies; cards that can't resolve it render null prices. Defaults to each card's own currency.
languageLanguage the resolved cards are localized to. Defaults to en.
countryBuyer country (ISO 3166-1 alpha-2) for gross-price resolution. With customerType, each card's vat block resolves through the same VAT authority the checkout quote uses; without hints every card is net-only (vat.resolved: false).
discountCodeA discount code a buyer typed. Each SUBSCRIPTION card then carries discount: the code priced for that card's first period exactly as the checkout quote prices it (the first invoice before VAT with the code, firstPeriodNetMinor; what the code takes off it, firstPeriodAmountOffMinor; and the day the regular price starts, endsAt). A card the code cannot price carries discount: null. A code that is unknown, used up or not for this buyer is refused with its DISCOUNT_* code. A request naming a code spends one use of the code-attempt budget this API key shares with the checkout quote, the session and the discount cart check. Without it, or with a code of spaces alone, no card carries discount.
Get a plan › Responses
A single plan projected as its canonical native card. Returns 404 PORTAL_PLAN_NOT_FOUND when the plan id is unknown to the API key's tenant, has no published version, or every card on the published version references a retired/archived subscription template (nothing renderable or sellable remains) — never filtered by visibility rules or the rule engine.
Resolve the gated pricing catalogue for an identified buyer (partner display)
Credential: a company's API key or OAuth token.
Runs the plan-routing rule engine for the buyer identified by customerId (or the no-customer-yet countryCode/customerType hints) within the API key's tenant, and returns the plans that buyer can SEE and CHECK OUT — including non-public (gated) plans the buyer matches — plus a reusable, read-only load-time catalog token. The partner returns the token to each embed iframe (via its fetchCatalogToken provider) to authorize the by-id pricing-card / checkout-document reads. Does NOT consult allowSelfSignup and never publishes to the CDN.
Required Scope
portal-catalog-read
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Resolve the gated pricing catalogue for an identified buyer (partner display) › Request Body
customerTypeBuyer customer type for gross-price resolution.
vatNumberBuyer VAT number for gross-price resolution. Accepted only with customerType: 'BUSINESS' (a coded 400 otherwise). Requires a country hint to have any effect. On the resolve read it is ignored when customerId is supplied — a customer-backed resolve stays net-only.
currencyPresentment currency for every card's pricing. Must be in each card's availableCurrencies; cards that can't resolve it render null prices. Defaults to each card's own currency.
customerIdThe buyer's LedgerBee customer id (an identity HANDLE — the server hydrates customer group / country / type from it; raw rule attributes are never accepted). The customer must exist in the API key's tenant (a 404 CUSTOMER_NOT_FOUND otherwise). When present, the server-resolved identity wins and the countryCode/customerType hints are ignored.
buyerEmailThe specific person (their email) the partner is acting on behalf of under customerId — e.g. the user currently signed in on the partner's site. Bound into the catalog token: when that token is later exchanged for a portal login handoff, THIS person is logged in (or bootstrapped credential-less under the customer's organization), instead of the customer's contact email / first member. Ignored without customerId; does not affect catalog visibility.
countryCodeISO 3166-1 alpha-2 country hint for the no-customer-yet preview (drives the country rule clause). Ignored when customerId is supplied.
planIdsResolve only these plan ids. Omit to resolve every ACTIVE plan of the tenant. Each must be a uuid.
languageLanguage the resolved cards are localized to. Defaults to en.
discountCodeA discount code a buyer typed. Each SUBSCRIPTION card then carries discount: the code priced for that card's first period exactly as the checkout quote prices it (the first invoice before VAT with the code, firstPeriodNetMinor; what the code takes off it, firstPeriodAmountOffMinor; and the day the regular price starts, endsAt). A card the code cannot price carries discount: null. A code that is unknown, used up or not for this buyer is refused with its DISCOUNT_* code. A request naming a code spends one use of the code-attempt budget this API key shares with the checkout quote, the session and the discount cart check. Without it, or with a code of spaces alone, no card carries discount. With customerId, that customer's own uses of the code count against its per-customer limit.
Resolve the gated pricing catalogue for an identified buyer (partner display) › Responses
The plans visible AND checkout-able to the resolved buyer, each carrying the full card content the partner renders. Non-public (gated) plans appear here when the buyer matches their rule.
catalogTokenOpaque, reusable, read-only load-time catalog token (43-char base64url). The partner returns it to each embed iframe via its fetchCatalogToken provider; the iframe presents it as a Bearer token to the by-id pricing-card / checkout-document reads. Scoped to the resolved buyer + the returned plans — replay yields only the same already-authorized cards. Treat it as a client secret (TLS-only, never log, never put on a URL).
expiresAtISO-8601 expiry of the catalog token.
Why plans were (or were not) returned — the "why is my catalogue empty" answer.