💳 BillingService - Gatekeeper Docs

Plan catalog, subscription lookup, feature entitlements, invoice preview, and payment-provider wiring (configs, plan mappings, checkout/portal sessions). Bearer required.

Subscriptions are not created here. Use the platform lane (PlatformBillingService.overrideSubscription) to set or override a tenant's subscription.

import { GatekeeperCore, BillingService } from '@orkait/sdk';
 
const billing = new BillingService(core);

Methods#

Method	Returns	Notes
`plans()`	`Page<Plan>`	catalog (any authenticated user)
`getSubscription(tenantId)`	`Subscription`	defaults to free
`entitlement(tenantId, feature, usage?)`	`EntitlementCheck`	joins plan limit with live `usage`
`invoicePreview(tenantId)`	`InvoicePreview`	this period's metered cost
`providerConfigs(tenantId)`	`Page<PaymentProviderConfig>`	configured payment providers; credentials stripped
`createProviderConfig(input)`	`PaymentProviderConfig`	`CreatePaymentProviderConfigInput`
`createPlanMapping(input)`	`PaymentPlanMapping`	maps a plan to a provider's external product/price
`createCheckoutSession(input)`	`PaymentCheckoutSession`	returns a hosted `checkoutUrl`
`createPortalSession(input)`	`PaymentPortalSession`	returns a hosted billing-portal `url`

Example#

const plans = await billing.plans();
const ent = await billing.entitlement('t1', 'api_keys', 3);
if (!ent.allowed) throw new Error('plan limit reached');
const invoice = await billing.invoicePreview('t1');
 
// Provider-backed checkout
const session = await billing.createCheckoutSession({
    tenantId: 't1',
    planId: plans.items[0].id,
    providerConfigId: 'pcfg_1',
    successUrl: 'https://app.example.com/ok',
    cancelUrl: 'https://app.example.com/cancel',
});