--- title: "nuxt-backend/billing" description: "Every export of nuxt-backend/billing, with its signature and where it is defined." canonical_url: "https://nuxt-backend.dev/docs/reference/api/billing" --- # nuxt-backend/billing ## Interfaces ### CatalogCreditGrant Defined in: [src/convex/catalog.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/catalog.ts) A credit grant a plan or pack carries (a provider meter-credit benefit). #### Properties

Property	Type	Description	Defined in
`meter`	`string`	The catalog meter key the credits land on.	src/convex/catalog.ts
`units`	`number`	Units granted (per cycle for plans, once for packs).	src/convex/catalog.ts
`rollover?`	`boolean`	Carry unused credits into the next cycle. Defaults to `false` for plan grants (use-it-or-lose-it monthly allowances) and `true` for packs (purchased credits keep).	src/convex/catalog.ts

--- ### CatalogMeter Defined in: [src/convex/catalog.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/catalog.ts) A usage meter, keyed by the event name spends use (`spendCredits({ meter })`). #### Properties

Property	Type	Description	Defined in
`aggregation?`	`"count"` \| `"sum"`	How events aggregate: `'sum'` (default) sums `property` across events — multi-credit spends in one event; `'count'` counts events (1 credit per event, not refundable).	src/convex/catalog.ts
`property?`	`string`	The metadata property summed by `'sum'` meters. Default `'amount'` .	src/convex/catalog.ts
`eventName?`	`string`	Event name the meter filters on. Defaults to the catalog key.	src/convex/catalog.ts

--- ### CatalogPlan Defined in: [src/convex/catalog.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/catalog.ts) A subscription plan (recurring product). #### Properties

Property	Type	Description	Defined in
`name`	`string`	-	src/convex/catalog.ts
`description?`	`string`	-	src/convex/catalog.ts
`interval`	`"month"` \| `"year"`	Billing interval.	src/convex/catalog.ts
`price`	`number`	Price in cents.	src/convex/catalog.ts
`credits?`	`CatalogCreditGrant`	Credits included with the plan, granted every cycle.	src/convex/catalog.ts
`features?`	`string`	Feature-benefit keys (from BillingCatalog.features ) this plan grants.	src/convex/catalog.ts
`trial?`	`CatalogTrial`	Free trial before the first charge.	src/convex/catalog.ts
`usage?`	`CatalogUsagePrice`	Metered prices charged on top of `price` (pay-as-you-go overage).	src/convex/catalog.ts
`taxBehavior?`	`CatalogTaxBehavior`	Tax treatment of the price. Defaults to the organization's setting.	src/convex/catalog.ts
`customFields?`	`string`	Checkout field keys (from BillingCatalog.customFields ) to collect.	src/convex/catalog.ts

--- ### CatalogPack Defined in: [src/convex/catalog.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/catalog.ts) A one-time credit pack. #### Properties

Property	Type	Description	Defined in
`name`	`string`	-	src/convex/catalog.ts
`description?`	`string`	-	src/convex/catalog.ts
`price`	`number`	Price in cents.	src/convex/catalog.ts
`credits`	`CatalogCreditGrant`	Credits granted once at purchase.	src/convex/catalog.ts
`taxBehavior?`	`CatalogTaxBehavior`	Tax treatment of the price. Defaults to the organization's setting.	src/convex/catalog.ts
`customFields?`	`string`	Checkout field keys (from BillingCatalog.customFields ) to collect.	src/convex/catalog.ts

--- ### CatalogFeature Defined in: [src/convex/catalog.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/catalog.ts) A feature benefit, gate-checked client-side via `useFeatures().has(key)`. Pushed as the provider's native feature-flag benefit; the catalog key rides along in the benefit metadata, which is what the gate matches on. #### Properties

Property	Type	Defined in
`description`	`string`	src/convex/catalog.ts

--- ### BillingCatalog Defined in: [src/convex/catalog.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/catalog.ts) #### Properties

Property	Type	Description	Defined in
`currency?`	`string`	ISO 4217 currency every `price` is created in, lowercase (`'usd'` , `'eur'` ). Defaults to the organization's default presentment currency, which the provider requires on every product.	src/convex/catalog.ts
`meters?`	`Record` <`string` , `CatalogMeter` >	-	src/convex/catalog.ts
`plans?`	`Record` <`string` , `CatalogPlan` >	-	src/convex/catalog.ts
`packs?`	`Record` <`string` , `CatalogPack` >	-	src/convex/catalog.ts
`features?`	`Record` <`string` , `CatalogFeature` >	-	src/convex/catalog.ts
`customFields?`	`Record` <`string` , `CatalogCustomField` >	Checkout fields plans and packs can collect, keyed by catalog key.	src/convex/catalog.ts

--- ### BillingRateLimiter Defined in: [src/convex/integrations/billing/types/base.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/base.ts) A structural rate limiter for throttling `syncEntitlements` — satisfied by `setupRateLimiter(...)` from `nuxt-backend/rate-limit`, which seeds the `billingSync` limit by default. Kept structural (rather than importing the rate-limiter's own type) so any compatible limiter is assignable. #### Methods ##### limit() ```ts limit( ctx, name, options? ): Promise<{ ok: boolean; retryAfter?: number; }>; ``` Defined in: [src/convex/integrations/billing/types/base.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/base.ts) ###### Parameters

Parameter	Type
`ctx`	`RunWriteCtx`
`name`	`"billingSync"`
`options?`	{ `key?` : `string` ; `throws?` : `boolean` ; }
`options.key?`	`string`
`options.throws?`	`boolean`

###### Returns `Promise`<{ `ok`: `boolean`; `retryAfter?`: `number`; }> --- ### SubscriptionTarget Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Shared addressing for the subscription-lifecycle operations. #### Extended by - [`UpdateSubscriptionOptions`](#updatesubscriptionoptions) - [`CancelSubscriptionOptions`](#cancelsubscriptionoptions) - [`PauseSubscriptionOptions`](#pausesubscriptionoptions) #### Properties

Property	Type	Description	Defined in
`subscriptionId?`	`string`	Which subscription to act on. Omit for the account's single live subscription — required once `multipleSubscriptions` ( SetupBillingConfig ) is on and an entity can hold several at once.	src/convex/integrations/billing/types/options.ts

--- ### UpdateSubscriptionOptions Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Options for [Billing.updateSubscription](#updatesubscription) (upgrade / downgrade). #### Extends - [`SubscriptionTarget`](#subscriptiontarget) #### Properties

Property	Type	Description	Inherited from	Defined in
`subscriptionId?`	`string`	Which subscription to act on. Omit for the account's single live subscription — required once `multipleSubscriptions` ( SetupBillingConfig ) is on and an entity can hold several at once.	`SubscriptionTarget` . `subscriptionId`	src/convex/integrations/billing/types/options.ts
`productId?`	`string`	The product to switch to.	-	src/convex/integrations/billing/types/options.ts
`proration?`	`ProrationBehavior`	How to settle the mid-period money difference.	-	src/convex/integrations/billing/types/options.ts

--- ### CancelSubscriptionOptions Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Options for [Billing.cancelSubscription](#cancelsubscription). #### Extends - [`SubscriptionTarget`](#subscriptiontarget) #### Properties

Property	Type	Description	Inherited from	Defined in
`subscriptionId?`	`string`	Which subscription to act on. Omit for the account's single live subscription — required once `multipleSubscriptions` ( SetupBillingConfig ) is on and an entity can hold several at once.	`SubscriptionTarget` . `subscriptionId`	src/convex/integrations/billing/types/options.ts
`atPeriodEnd?`	`boolean`	Keep the subscription running until the period it is paid for ends (default). `false` revokes it immediately — benefits are withdrawn on the spot and the remainder is not refunded.	-	src/convex/integrations/billing/types/options.ts
`reason?`	`CancellationReason`	The customer's own churn reason.	-	src/convex/integrations/billing/types/options.ts
`comment?`	`string`	The customer's own words. Never an internal note — they can read it back.	-	src/convex/integrations/billing/types/options.ts

--- ### PauseSubscriptionOptions Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Options for [Billing.pauseSubscription](#pausesubscription). #### Extends - [`SubscriptionTarget`](#subscriptiontarget) #### Properties

Property	Type	Description	Inherited from	Defined in
`subscriptionId?`	`string`	Which subscription to act on. Omit for the account's single live subscription — required once `multipleSubscriptions` ( SetupBillingConfig ) is on and an entity can hold several at once.	`SubscriptionTarget` . `subscriptionId`	src/convex/integrations/billing/types/options.ts
`resumesAt?`	`Date`	When the paused subscription resumes by itself (must be after the current period ends). Omit to pause until it is resumed by hand.	-	src/convex/integrations/billing/types/options.ts

--- ### OrdersOptions Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Options for [Billing.getOrders](#getorders). #### Properties

Property	Type	Description	Defined in
`limit?`	`number`	Orders per page (1–100, default 10).	src/convex/integrations/billing/types/options.ts
`cursor?`	`string`	An opaque page token from a previous page's `nextCursor` .	src/convex/integrations/billing/types/options.ts
`page?`	`number`	The provider's 1-based page number — the raw form of `cursor` .	src/convex/integrations/billing/types/options.ts

--- ### BillingPage Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) A page of provider records, plus the token that reads the next one. #### Type Parameters

Type Parameter
`Item`

#### Properties

Property	Type	Description	Defined in
`items`	`Item`	-	src/convex/integrations/billing/types/options.ts
`pagination`	{ `totalCount` : `number` ; `maxPage` : `number` ; }	-	src/convex/integrations/billing/types/options.ts
`pagination.totalCount`	`number`	-	src/convex/integrations/billing/types/options.ts
`pagination.maxPage`	`number`	-	src/convex/integrations/billing/types/options.ts
`nextCursor?`	`string`	Pass back as `cursor` to read the next page; absent on the last one.	src/convex/integrations/billing/types/options.ts

--- ### UsageHistoryOptions Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Options for [Billing.getUsageHistory](#getusagehistory). #### Properties

Property	Type	Description	Defined in
`meter?`	`string`	Which meter's consumption to read: a configured credit-meter name (`'credits'` ) or a raw meter id. Omit for every ingested event on the account.	src/convex/integrations/billing/types/options.ts
`limit?`	`number`	Events per page (1–100, default 10).	src/convex/integrations/billing/types/options.ts
`cursor?`	`string`	An opaque page token from a previous page's `nextCursor` .	src/convex/integrations/billing/types/options.ts
`page?`	`number`	The provider's 1-based page number — the raw form of `cursor` .	src/convex/integrations/billing/types/options.ts
`startTimestamp?`	`Date`	Only events at or after this moment.	src/convex/integrations/billing/types/options.ts
`endTimestamp?`	`Date`	Only events at or before this moment.	src/convex/integrations/billing/types/options.ts

--- ### RefundOrderOptions Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Options for [Billing.refundOrder](#refundorder). #### Properties

Property	Type	Description	Defined in
`orderId`	`string`	-	src/convex/integrations/billing/types/options.ts
`amount?`	`number`	Amount to refund in the currency's minor unit (cents). Omit to refund everything still refundable on the order.	src/convex/integrations/billing/types/options.ts
`reason`	`RefundReason`	-	src/convex/integrations/billing/types/options.ts
`revokeBenefits?`	`boolean`	Withdraw the order's benefits as well. The provider only allows this for one-time purchases — a subscription's benefits are withdrawn when the subscription itself is revoked.	src/convex/integrations/billing/types/options.ts
`metadata?`	`Record` <`string` , `string` \| `number` \| `boolean` >	Extra key-value data stored on the refund.	src/convex/integrations/billing/types/options.ts

--- ### RefundRecord Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) The outcome of [Billing.refundOrder](#refundorder), JSON-normalized. #### Properties

Property	Type	Description	Defined in
`id`	`string`	-	src/convex/integrations/billing/types/options.ts
`orderId`	`string`	-	src/convex/integrations/billing/types/options.ts
`status`	`string`	-	src/convex/integrations/billing/types/options.ts
`reason`	`string`	-	src/convex/integrations/billing/types/options.ts
`amount`	`number`	Refunded amount in the currency's minor unit (cents).	src/convex/integrations/billing/types/options.ts
`currency`	`string`	-	src/convex/integrations/billing/types/options.ts
`revokeBenefits`	`boolean`	-	src/convex/integrations/billing/types/options.ts

--- ### DiscountListOptions Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Filters for [BillingDiscounts.list](#list). #### Properties

Property	Type	Description	Defined in
`query?`	`string`	Match against the discount's name.	src/convex/integrations/billing/types/options.ts
`limit?`	`number`	Discounts per page (1–100, default 10).	src/convex/integrations/billing/types/options.ts
`page?`	`number`	The provider's 1-based page number.	src/convex/integrations/billing/types/options.ts

--- ### BillingDiscounts Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Discount (coupon) management. Privileged by design — a public action that mints discounts would let anyone create a 100%-off code — so these are server-side methods, not registered functions: call them from an `internalAction` or an admin-tier action of your own. #### Properties

Property	Type	Description	Defined in
`create`	(`discount` ) => `Promise` <{ `id` : `string` ; `code` : `string` \| `null` ; }>	Create a discount / coupon. Accepts the full provider shape (fixed or percentage).	src/convex/integrations/billing/types/options.ts
`list`	(`options?` ) => `Promise` < `BillingPage` <`Discount` >>	List discounts (newest provider order), one page at a time.	src/convex/integrations/billing/types/options.ts
`remove`	(`discountId` ) => `Promise` <`void` >	Permanently delete a discount. Redemptions already applied stay applied.	src/convex/integrations/billing/types/options.ts

--- ### CheckoutPrefill Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Pre-filled customer details for a checkout session. Every field is only a default the customer can still change — the provider owns the form. #### Properties

Property	Type	Description	Defined in
`name?`	`string`	-	src/convex/integrations/billing/types/options.ts
`email?`	`string`	-	src/convex/integrations/billing/types/options.ts
`billingName?`	`string`	The name that should appear on the invoice, when it differs from `name` .	src/convex/integrations/billing/types/options.ts
`billingAddress?`	{ `country` : `string` ; `line1?` : `string` ; `line2?` : `string` ; `postalCode?` : `string` ; `city?` : `string` ; `state?` : `string` ; }	-	src/convex/integrations/billing/types/options.ts
`billingAddress.country`	`string`	ISO 3166-1 alpha-2 country code — the one field the provider requires.	src/convex/integrations/billing/types/options.ts
`billingAddress.line1?`	`string`	-	src/convex/integrations/billing/types/options.ts
`billingAddress.line2?`	`string`	-	src/convex/integrations/billing/types/options.ts
`billingAddress.postalCode?`	`string`	-	src/convex/integrations/billing/types/options.ts
`billingAddress.city?`	`string`	-	src/convex/integrations/billing/types/options.ts
`billingAddress.state?`	`string`	-	src/convex/integrations/billing/types/options.ts
`taxId?`	`string`	VAT / tax identification number.	src/convex/integrations/billing/types/options.ts
`business?`	`boolean`	Bill a business rather than an individual. Turning this on makes the provider require a full billing address and billing name.	src/convex/integrations/billing/types/options.ts

--- ### CampaignAttribution Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Campaign attribution a checkout carries, as a campaign link's UTM parameters. Stored on the order or subscription as flat `utm_source`, `utm_medium`, … metadata, the way the provider's own checkout links store it; each value is trimmed and cut to 100 characters. #### Properties

Property	Type	Defined in
`source?`	`string`	src/convex/integrations/billing/types/options.ts
`medium?`	`string`	src/convex/integrations/billing/types/options.ts
`campaign?`	`string`	src/convex/integrations/billing/types/options.ts
`term?`	`string`	src/convex/integrations/billing/types/options.ts
`content?`	`string`	src/convex/integrations/billing/types/options.ts

--- ### CheckoutTrial Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) A trial the server grants at checkout in place of the product's own: 1 to 30 days, in days or weeks. No months: the provider counts a month as a calendar month, up to 31 days. #### Properties

Property	Type	Description	Defined in
`interval`	`"day"` \| `"week"`	-	src/convex/integrations/billing/types/options.ts
`count?`	`number`	Number of intervals. Defaults to 1.	src/convex/integrations/billing/types/options.ts

--- ### EntitlementBenefit Defined in: [src/convex/integrations/billing/types/records.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/records.ts) A single granted benefit (entitlement) in a customer's billing state. #### Properties

Property	Type	Description	Defined in
`id`	`string`	-	src/convex/integrations/billing/types/records.ts
`benefitId`	`string`	-	src/convex/integrations/billing/types/records.ts
`type`	`string`	-	src/convex/integrations/billing/types/records.ts
`metadata?`	`Record` <`string` , `string` \| `number` \| `boolean` >	The benefit's live provider metadata (read from the benefit, not the grant-time snapshot in customer state). Lets consumers feature-gate by a friendly key — set e.g. `{ key: 'premium' }` on the benefit and check `useFeatures().has('premium')` .	src/convex/integrations/billing/types/records.ts

--- ### EntitlementMeter Defined in: [src/convex/integrations/billing/types/records.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/records.ts) A credit-meter balance in a customer's billing state (prepaid credits). #### Properties

Property	Type	Description	Defined in
`meterId`	`string`	-	src/convex/integrations/billing/types/records.ts
`consumedUnits`	`number`	-	src/convex/integrations/billing/types/records.ts
`creditedUnits`	`number`	-	src/convex/integrations/billing/types/records.ts
`balance`	`number`	-	src/convex/integrations/billing/types/records.ts
`cycleStart?`	`number`	The granting subscription's current period (epoch ms) — a meter has no period of its own in the provider's model. Absent for meters granted only by one-time credit packs.	src/convex/integrations/billing/types/records.ts
`cycleEnd?`	`number`	-	src/convex/integrations/billing/types/records.ts
`rollover?`	`boolean`	Whether unspent credited units carry into the next cycle.	src/convex/integrations/billing/types/records.ts

--- ### CustomerEntitlements Defined in: [src/convex/integrations/billing/types/records.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/records.ts) A user's full billing entitlement state — active plans, granted benefits, and credit-meter balances — normalized for caching into the reactive component table. #### Properties

Property	Type	Defined in
`customerId`	`string` \| `null`	src/convex/integrations/billing/types/records.ts
`activeProductIds`	`string`	src/convex/integrations/billing/types/records.ts
`benefits`	`EntitlementBenefit`	src/convex/integrations/billing/types/records.ts
`meters`	`EntitlementMeter`	src/convex/integrations/billing/types/records.ts

--- ### CreditMeterConfig Defined in: [src/convex/integrations/billing/types/records.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/records.ts) A named credit meter: how a spend by friendly name (`meter: 'credits'`) resolves to the provider meter and its ingestion shape. Declared in `setupBilling({ credits })` or generated into `billing.generated.ts` by `nuxt-backend billing sync`. #### Properties

Property	Type	Description	Defined in
`meterId`	`string`	The provider meter id the balance guard runs against.	src/convex/integrations/billing/types/records.ts
`eventName?`	`string`	Event name the meter's filter matches. Defaults to the config key.	src/convex/integrations/billing/types/records.ts
`property?`	`string`	For sum-aggregation meters: the metadata property carrying the amount — ingested as `metadata[property] = value` . Omit for count meters (which count events, so each spend is exactly 1 credit).	src/convex/integrations/billing/types/records.ts

--- ### BillingCatalogIds Defined in: [src/convex/integrations/billing/types/records.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/records.ts) The environment-keyed id map `nuxt-backend billing sync` generates. #### Properties

Property	Type	Description	Defined in
`products?`	`Record` <`string` , `string` >	Catalog key → provider product id (plans and packs).	src/convex/integrations/billing/types/records.ts
`packs?`	`string`	The catalog keys of `products` that are credit packs: what a gift may buy.	src/convex/integrations/billing/types/records.ts
`gifts?`	`Record` <`string` , `string` >	Pack key → the provider id of its private gift product: the same prices, no benefits, bought by a purchaser for someone else. Never sold on its own, so it is outside `products` and the checkout allow-list.	src/convex/integrations/billing/types/records.ts
`meters?`	`Record` <`string` , `CreditMeterConfig` >	Catalog key → credit meter config.	src/convex/integrations/billing/types/records.ts

--- ### SpendCreditsEvent Defined in: [src/convex/integrations/billing/types/records.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/records.ts) A prepaid-credit consumption event (drawn from the customer's meter balance). #### Properties

Property	Type	Description	Defined in
`userId?`	`string`	The billing entity id — the workspace id (`billTo: 'organization'` , the default) or the auth user id (`billTo: 'user'` ). Omit to resolve it from the caller's identity (the active workspace / signed-in user).	src/convex/integrations/billing/types/records.ts
`meter?`	`string`	A configured credit meter name (`setupBilling({ credits })` / catalog key) — the preferred spend target: resolves the meter id, event name, and ingestion shape in one word.	src/convex/integrations/billing/types/records.ts
`name?`	`string`	The meter event name. Defaults to the configured meter's `eventName` /key.	src/convex/integrations/billing/types/records.ts
`meterId?`	`string`	A raw credit meter id to guard against (escape hatch when no named meter config exists). When a meter resolves (by `meter` or `meterId` ), the spend is reserved against the cached balance first and blocked (throws) if it is below `value` — keeping credits strictly prepaid (never billed as overage). The reservation settles after the provider event ingests, or releases on failure, so a failed run never consumes credits.	src/convex/integrations/billing/types/records.ts
`value?`	`number`	Credits required for this spend (default `1` ): a finite number above zero. Anything else is refused before the balance or the provider sees it.	src/convex/integrations/billing/types/records.ts
`allowOverage?`	`boolean`	Let the balance go negative instead of refusing the spend — the pay-as-you-go case: the meter has no credit benefit behind it, so every unit is overage the provider invoices at the end of the cycle. Off by default: credits stay strictly prepaid.	src/convex/integrations/billing/types/records.ts
`metadata?`	`Record` <`string` , `string` \| `number` \| `boolean` >	Event properties used by the meter's aggregation/filter.	src/convex/integrations/billing/types/records.ts
`externalId?`	`string`	Idempotency key to prevent double-counting (defaults to a random UUID).	src/convex/integrations/billing/types/records.ts
`timestamp?`	`Date`	Event time (defaults to now).	src/convex/integrations/billing/types/records.ts

--- ### SpendReservation Defined in: [src/convex/integrations/billing/types/records.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/records.ts) A credit reservation's addressing data — serializable, so a spend can reserve in one function and settle/release in another (the streaming HTTP dispatcher does exactly that). Being plain data, it is checked again when it settles: a `value` that is not a finite number above zero is refused. #### Properties

Property	Type	Description	Defined in
`entityId`	`string`	The billing entity the spend belongs to.	src/convex/integrations/billing/types/records.ts
`externalId`	`string`	Idempotency key shared by the reservation and the provider event.	src/convex/integrations/billing/types/records.ts
`reserved`	`boolean`	Whether a meter guard actually reserved cached balance.	src/convex/integrations/billing/types/records.ts
`meter?`	`string`	The configured meter name (when reserved via one).	src/convex/integrations/billing/types/records.ts
`meterId?`	`string`	The raw meter id (when reserved).	src/convex/integrations/billing/types/records.ts
`value`	`number`	Credits reserved.	src/convex/integrations/billing/types/records.ts

--- ### RefundCreditsEvent Defined in: [src/convex/integrations/billing/types/records.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/records.ts) A prepaid-credit refund (compensating event on a sum meter). #### Properties

Property	Type	Description	Defined in
`userId?`	`string`	The billing entity id; omit to resolve from the caller's identity.	src/convex/integrations/billing/types/records.ts
`meter`	`string`	The configured credit meter name to refund on (must be a sum meter).	src/convex/integrations/billing/types/records.ts
`value`	`number`	Credits to give back: a finite number above zero.	src/convex/integrations/billing/types/records.ts
`metadata?`	`Record` <`string` , `string` \| `number` \| `boolean` >	Extra event properties.	src/convex/integrations/billing/types/records.ts
`externalId?`	`string`	Idempotency key (defaults to a random UUID).	src/convex/integrations/billing/types/records.ts

--- ### GiftRecord Defined in: [src/convex/integrations/billing/types/records.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/records.ts) A gift purchase record, as stored by the `backend` component (`components.backend.gifts.*`). #### Properties

Property	Type	Description	Defined in
`id`	`string`	-	src/convex/integrations/billing/types/records.ts
`recipientEmail`	`string`	-	src/convex/integrations/billing/types/records.ts
`purchaserUserId`	`string`	-	src/convex/integrations/billing/types/records.ts
`purchaserEmail?`	`string`	Before 0.2 only: gifts no longer keep the purchaser's email.	src/convex/integrations/billing/types/records.ts
`purchaserName?`	`string`	-	src/convex/integrations/billing/types/records.ts
`productIds`	`string`	The credit pack's provider product: what the recipient's claim grants.	src/convex/integrations/billing/types/records.ts
`message?`	`string`	-	src/convex/integrations/billing/types/records.ts
`status`	`string`	`'pending'` (the purchaser's checkout is open) → `'paid'` (the purchase is paid and claimable) → `'claimed'` , or `'refunded'` when the purchase was refunded before the claim.	src/convex/integrations/billing/types/records.ts
`billingCustomerId?`	`string`	Before 0.2 only: the customer keyed by the recipient's email that the purchase was billed to.	src/convex/integrations/billing/types/records.ts
`billingOrderId?`	`string`	The purchase order, on the purchaser's own customer.	src/convex/integrations/billing/types/records.ts
`purchaserEntityId?`	`string`	The billing entity that paid.	src/convex/integrations/billing/types/records.ts
`pack?`	`string`	The pack's catalog key.	src/convex/integrations/billing/types/records.ts
`giftProductId?`	`string`	The private gift product the purchaser bought.	src/convex/integrations/billing/types/records.ts
`amount?`	`number`	What the purchase charged, in the currency's smallest unit.	src/convex/integrations/billing/types/records.ts
`currency?`	`string`	-	src/convex/integrations/billing/types/records.ts
`discountId?`	`string`	The single-use 100% discount the recipient claims the pack with.	src/convex/integrations/billing/types/records.ts
`claimingEntityId?`	`string`	-	src/convex/integrations/billing/types/records.ts
`claimingUserId?`	`string`	-	src/convex/integrations/billing/types/records.ts
`claimOrderId?`	`string`	-	src/convex/integrations/billing/types/records.ts
`claimedByUserId?`	`string`	-	src/convex/integrations/billing/types/records.ts
`claimedEntityId?`	`string`	-	src/convex/integrations/billing/types/records.ts
`createdAt`	`number`	-	src/convex/integrations/billing/types/records.ts
`paidAt?`	`number`	-	src/convex/integrations/billing/types/records.ts
`notifiedAt?`	`number`	When the recipient's notification email went out — stamped only after the send succeeded.	src/convex/integrations/billing/types/records.ts
`claimedAt?`	`number`	-	src/convex/integrations/billing/types/records.ts
`refundedAt?`	`number`	-	src/convex/integrations/billing/types/records.ts

--- ### BillingComponents Defined in: [src/convex/integrations/billing/types/setup.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/setup.ts) The component handles `setupBilling` reads from your generated `components` object. Pass the whole object — each key is picked structurally: - `polar` — the upstream billing-provider component (checkout / portal / webhooks / customer mapping). - `backend` — the package's all-in-one component: `billing` is the reactive entitlement cache, `gifts` the gift-purchase records, and `email` (optional) delivers gift notifications. #### Properties

Property	Type	Description	Defined in
`polar`	`ComponentApi`	-	src/convex/integrations/billing/types/setup.ts
`backend`	{ `billing` : { `getByUser` : `FunctionReference` <`"query"` , `"internal"` , { `userId` : `string` ; }, `CachedEntitlements` \| `null` >; `upsert` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `customerId?` : `string` ; `activeProductIds` : `string` ; `benefits` : `EntitlementBenefit` ; `meters` : `EntitlementMeter` ; }, `null` >; `userByCustomer` : `FunctionReference` <`"query"` , `"internal"` , { `customerId` : `string` ; }, `string` \| `null` >; `entityProfile` : `FunctionReference` <`"query"` , `"internal"` , { `entityId` : `string` ; }, `EntityProfile` \| `null` >; `claimTrial` : `FunctionReference` <`"mutation"` , `"internal"` , { `ownerUserId` : `string` ; `entityId` : `string` ; `holdMs` : `number` ; }, `boolean` >; `markTrialUsed` : `FunctionReference` <`"mutation"` , `"internal"` , { `ownerUserId` : `string` ; `entityId` : `string` ; }, `null` >; `reserveDiscountCode` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `max` : `number` ; `windowMs` : `number` ; }, \| { `reserved` : `true` ; `windowStart` : `number` ; } \| { `reserved` : `false` ; `retryAfter` : `number` ; }>; `releaseDiscountCode` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `windowStart` : `number` ; }, `null` >; `debit` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `meterId` : `string` ; `amount` : `number` ; `externalId` : `string` ; `allowOverage?` : `boolean` ; }, { `ok` : `boolean` ; `balance` : `number` ; `reason?` : `"no-row"` \| `"no-meter"` \| `"insufficient"` ; }>; `settle` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `externalId` : `string` ; `finalAmount?` : `number` ; }, `null` >; `release` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `externalId` : `string` ; }, `null` >; `credit` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `meterId` : `string` ; `amount` : `number` ; }, `null` >; `clearPendingSpends` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; }, `null` >; `deleteByUser` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; }, `null` >; `getBenefitMetadata` : `FunctionReference` <`"query"` , `"internal"` , { `benefitIds` : `string` ; }, { `benefitId` : `string` ; `metadata` : `Record` <`string` , `string` \| `number` \| `boolean` >; `updatedAt` : `number` ; } >; `upsertBenefitMetadata` : `FunctionReference` <`"mutation"` , `"internal"` , { `entries` : { `benefitId` : `string` ; `metadata` : `Record` <`string` , `string` \| `number` \| `boolean` >; } ; }, `null` >; }; `gifts` : { `create` : `FunctionReference` <`"mutation"` , `"internal"` , { `recipientEmail` : `string` ; `purchaserUserId` : `string` ; `purchaserEntityId?` : `string` ; `purchaserName?` : `string` ; `pack?` : `string` ; `productIds` : `string` ; `giftProductId?` : `string` ; `message?` : `string` ; }, `string` >; `markPaid` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `billingOrderId?` : `string` ; `amount?` : `number` ; `currency?` : `string` ; }, `null` >; `setDiscount` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `discountId` : `string` ; }, `boolean` >; `markNotified` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; }, `boolean` >; `startClaim` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `userId` : `string` ; `entityId` : `string` ; }, `boolean` >; `markClaimed` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `userId` : `string` ; `entityId` : `string` ; `claimOrderId?` : `string` ; }, `null` >; `markRefunded` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; }, `boolean` >; `listByEmail` : `FunctionReference` <`"query"` , `"internal"` , { `email` : `string` ; `status?` : `"paid"` \| `"claimed"` ; }, `GiftRecord` >; `countBought` : `FunctionReference` <`"query"` , `"internal"` , { `purchaserUserId` : `string` ; `since` : `number` ; `pendingSince` : `number` ; `excludeGiftId?` : `string` ; }, { `count` : `number` ; `oldest` : `number` \| `null` ; }>; `get` : `FunctionReference` <`"query"` , `"internal"` , { `giftId` : `string` ; }, `GiftRecord` \| `null` >; `personalEntity` : `FunctionReference` <`"query"` , `"internal"` , { `userId` : `string` ; }, `string` \| `null` >; }; `webhooks` : `WebhookLogRefs` ; }	-	src/convex/integrations/billing/types/setup.ts
`backend.billing`	{ `getByUser` : `FunctionReference` <`"query"` , `"internal"` , { `userId` : `string` ; }, `CachedEntitlements` \| `null` >; `upsert` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `customerId?` : `string` ; `activeProductIds` : `string` ; `benefits` : `EntitlementBenefit` ; `meters` : `EntitlementMeter` ; }, `null` >; `userByCustomer` : `FunctionReference` <`"query"` , `"internal"` , { `customerId` : `string` ; }, `string` \| `null` >; `entityProfile` : `FunctionReference` <`"query"` , `"internal"` , { `entityId` : `string` ; }, `EntityProfile` \| `null` >; `claimTrial` : `FunctionReference` <`"mutation"` , `"internal"` , { `ownerUserId` : `string` ; `entityId` : `string` ; `holdMs` : `number` ; }, `boolean` >; `markTrialUsed` : `FunctionReference` <`"mutation"` , `"internal"` , { `ownerUserId` : `string` ; `entityId` : `string` ; }, `null` >; `reserveDiscountCode` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `max` : `number` ; `windowMs` : `number` ; }, \| { `reserved` : `true` ; `windowStart` : `number` ; } \| { `reserved` : `false` ; `retryAfter` : `number` ; }>; `releaseDiscountCode` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `windowStart` : `number` ; }, `null` >; `debit` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `meterId` : `string` ; `amount` : `number` ; `externalId` : `string` ; `allowOverage?` : `boolean` ; }, { `ok` : `boolean` ; `balance` : `number` ; `reason?` : `"no-row"` \| `"no-meter"` \| `"insufficient"` ; }>; `settle` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `externalId` : `string` ; `finalAmount?` : `number` ; }, `null` >; `release` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `externalId` : `string` ; }, `null` >; `credit` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `meterId` : `string` ; `amount` : `number` ; }, `null` >; `clearPendingSpends` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; }, `null` >; `deleteByUser` : `FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; }, `null` >; `getBenefitMetadata` : `FunctionReference` <`"query"` , `"internal"` , { `benefitIds` : `string` ; }, { `benefitId` : `string` ; `metadata` : `Record` <`string` , `string` \| `number` \| `boolean` >; `updatedAt` : `number` ; } >; `upsertBenefitMetadata` : `FunctionReference` <`"mutation"` , `"internal"` , { `entries` : { `benefitId` : `string` ; `metadata` : `Record` <`string` , `string` \| `number` \| `boolean` >; } ; }, `null` >; }	-	src/convex/integrations/billing/types/setup.ts
`backend.billing.getByUser`	`FunctionReference` <`"query"` , `"internal"` , { `userId` : `string` ; }, `CachedEntitlements` \| `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.billing.upsert`	`FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `customerId?` : `string` ; `activeProductIds` : `string` ; `benefits` : `EntitlementBenefit` ; `meters` : `EntitlementMeter` ; }, `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.billing.userByCustomer`	`FunctionReference` <`"query"` , `"internal"` , { `customerId` : `string` ; }, `string` \| `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.billing.entityProfile`	`FunctionReference` <`"query"` , `"internal"` , { `entityId` : `string` ; }, `EntityProfile` \| `null` >	Who stands behind a workspace entity: its name, whether it is personal, its owner and the workspaces that owner owns; `null` for anything else.	src/convex/integrations/billing/types/setup.ts
`backend.billing.claimTrial`	`FunctionReference` <`"mutation"` , `"internal"` , { `ownerUserId` : `string` ; `entityId` : `string` ; `holdMs` : `number` ; }, `boolean` >	Hold the owner's one trial for this entity's checkout, or say no when it is spent or held for another entity.	src/convex/integrations/billing/types/setup.ts
`backend.billing.markTrialUsed`	`FunctionReference` <`"mutation"` , `"internal"` , { `ownerUserId` : `string` ; `entityId` : `string` ; }, `null` >	Record that a subscription of this entity started its owner's trial.	src/convex/integrations/billing/types/setup.ts
`backend.billing.reserveDiscountCode`	`FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `max` : `number` ; `windowMs` : `number` ; }, \| { `reserved` : `true` ; `windowStart` : `number` ; } \| { `reserved` : `false` ; `retryAfter` : `number` ; }>	Count one discount-code attempt for an entity before the provider is asked, in a fixed window of at most `max` : the window's start, or the wait once `max` are counted.	src/convex/integrations/billing/types/setup.ts
`backend.billing.releaseDiscountCode`	`FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `windowStart` : `number` ; }, `null` >	Give back an attempt `reserveDiscountCode` counted, in the window it was counted in.	src/convex/integrations/billing/types/setup.ts
`backend.billing.debit`	`FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `meterId` : `string` ; `amount` : `number` ; `externalId` : `string` ; `allowOverage?` : `boolean` ; }, { `ok` : `boolean` ; `balance` : `number` ; `reason?` : `"no-row"` \| `"no-meter"` \| `"insufficient"` ; }>	-	src/convex/integrations/billing/types/setup.ts
`backend.billing.settle`	`FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `externalId` : `string` ; `finalAmount?` : `number` ; }, `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.billing.release`	`FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `externalId` : `string` ; }, `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.billing.credit`	`FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; `meterId` : `string` ; `amount` : `number` ; }, `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.billing.clearPendingSpends`	`FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; }, `null` >	Drop every in-flight spend reservation for one entity, without re-crediting: used after a refund, where the provider's balance is already the truth and re-subtracting local reservations would push the cache below it.	src/convex/integrations/billing/types/setup.ts
`backend.billing.deleteByUser`	`FunctionReference` <`"mutation"` , `"internal"` , { `userId` : `string` ; }, `null` >	Delete one entity's entitlement cache row (account erasure).	src/convex/integrations/billing/types/setup.ts
`backend.billing.getBenefitMetadata`	`FunctionReference` <`"query"` , `"internal"` , { `benefitIds` : `string` ; }, { `benefitId` : `string` ; `metadata` : `Record` <`string` , `string` \| `number` \| `boolean` >; `updatedAt` : `number` ; } >	-	src/convex/integrations/billing/types/setup.ts
`backend.billing.upsertBenefitMetadata`	`FunctionReference` <`"mutation"` , `"internal"` , { `entries` : { `benefitId` : `string` ; `metadata` : `Record` <`string` , `string` \| `number` \| `boolean` >; } ; }, `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts`	{ `create` : `FunctionReference` <`"mutation"` , `"internal"` , { `recipientEmail` : `string` ; `purchaserUserId` : `string` ; `purchaserEntityId?` : `string` ; `purchaserName?` : `string` ; `pack?` : `string` ; `productIds` : `string` ; `giftProductId?` : `string` ; `message?` : `string` ; }, `string` >; `markPaid` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `billingOrderId?` : `string` ; `amount?` : `number` ; `currency?` : `string` ; }, `null` >; `setDiscount` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `discountId` : `string` ; }, `boolean` >; `markNotified` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; }, `boolean` >; `startClaim` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `userId` : `string` ; `entityId` : `string` ; }, `boolean` >; `markClaimed` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `userId` : `string` ; `entityId` : `string` ; `claimOrderId?` : `string` ; }, `null` >; `markRefunded` : `FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; }, `boolean` >; `listByEmail` : `FunctionReference` <`"query"` , `"internal"` , { `email` : `string` ; `status?` : `"paid"` \| `"claimed"` ; }, `GiftRecord` >; `countBought` : `FunctionReference` <`"query"` , `"internal"` , { `purchaserUserId` : `string` ; `since` : `number` ; `pendingSince` : `number` ; `excludeGiftId?` : `string` ; }, { `count` : `number` ; `oldest` : `number` \| `null` ; }>; `get` : `FunctionReference` <`"query"` , `"internal"` , { `giftId` : `string` ; }, `GiftRecord` \| `null` >; `personalEntity` : `FunctionReference` <`"query"` , `"internal"` , { `userId` : `string` ; }, `string` \| `null` >; }	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.create`	`FunctionReference` <`"mutation"` , `"internal"` , { `recipientEmail` : `string` ; `purchaserUserId` : `string` ; `purchaserEntityId?` : `string` ; `purchaserName?` : `string` ; `pack?` : `string` ; `productIds` : `string` ; `giftProductId?` : `string` ; `message?` : `string` ; }, `string` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.markPaid`	`FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `billingOrderId?` : `string` ; `amount?` : `number` ; `currency?` : `string` ; }, `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.setDiscount`	`FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `discountId` : `string` ; }, `boolean` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.markNotified`	`FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; }, `boolean` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.startClaim`	`FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `userId` : `string` ; `entityId` : `string` ; }, `boolean` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.markClaimed`	`FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; `userId` : `string` ; `entityId` : `string` ; `claimOrderId?` : `string` ; }, `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.markRefunded`	`FunctionReference` <`"mutation"` , `"internal"` , { `giftId` : `string` ; }, `boolean` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.listByEmail`	`FunctionReference` <`"query"` , `"internal"` , { `email` : `string` ; `status?` : `"paid"` \| `"claimed"` ; }, `GiftRecord` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.countBought`	`FunctionReference` <`"query"` , `"internal"` , { `purchaserUserId` : `string` ; `since` : `number` ; `pendingSince` : `number` ; `excludeGiftId?` : `string` ; }, { `count` : `number` ; `oldest` : `number` \| `null` ; }>	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.get`	`FunctionReference` <`"query"` , `"internal"` , { `giftId` : `string` ; }, `GiftRecord` \| `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.gifts.personalEntity`	`FunctionReference` <`"query"` , `"internal"` , { `userId` : `string` ; }, `string` \| `null` >	-	src/convex/integrations/billing/types/setup.ts
`backend.webhooks`	`WebhookLogRefs`	-	src/convex/integrations/billing/types/setup.ts

--- ### EntityProfile Defined in: [src/convex/integrations/billing/types/setup.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/setup.ts) A workspace entity as its provider customer needs it: the team customer is named after the workspace and owned by its owner, a personal workspace may adopt its owner's earlier customer, and one trial counts across every workspace the owner owns. #### Properties

Property	Type	Defined in
`name`	`string`	src/convex/integrations/billing/types/setup.ts
`personal`	`boolean`	src/convex/integrations/billing/types/setup.ts
`owner`	\| { `userId` : `string` ; `email` : `string` ; `name` : `string` ; `emailVerified` : `boolean` ; } \| `null`	src/convex/integrations/billing/types/setup.ts
`ownedEntityIds`	`string`	src/convex/integrations/billing/types/setup.ts

--- ### BillingEntity Defined in: [src/convex/integrations/billing/types/setup.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/setup.ts) Who a billing operation runs for: the entity that owns the subscription and the credits — a workspace, or a user with `billTo: 'user'` — and the email the provider customer is created with. `userId` is the entity's id either way. #### Properties

Property	Type	Defined in
`userId`	`string`	src/convex/integrations/billing/types/setup.ts
`email`	`string`	src/convex/integrations/billing/types/setup.ts

--- ### BillingEntityCtx Defined in: [src/convex/integrations/billing/types/setup.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/setup.ts) The context [SetupBillingConfig.resolveEntity](#resolveentity) receives: the caller's auth, and `runQuery` to read the app's own tables. Queries, mutations and actions all provide both, so one resolver serves the reactive reads and the provider calls alike. `auth` is always there; an internal call with no caller has a `null` identity. #### Properties

Property	Type	Defined in
`auth`	`Auth`	src/convex/integrations/billing/types/setup.ts
`runQuery`	<`Query` >(`query` , ...`args` ) => `Promise` <`FunctionReturnType` <`Query` >>	src/convex/integrations/billing/types/setup.ts

--- ### SetupBillingConfig Defined in: [src/convex/integrations/billing/types/setup.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/setup.ts) Billing configuration: every option `setupBilling` reads, and nothing else. The access token, environment and webhook secret default to the required `BILLING_ACCESS_TOKEN` / `BILLING_ENVIRONMENT` / `BILLING_WEBHOOK_SECRET` env vars, so `setupBilling(components, { email })` needs no env plumbing. The billing entity resolves from identity claims out of the box — the active workspace (`billTo: 'organization'`, the default) or the signed-in user (`billTo: 'user'`) — so [SetupBillingConfig.resolveEntity](#resolveentity) is an override, not required wiring. #### Properties

Property	Type	Description	Defined in
`email`	`BillingEmail`	The app's `setupEmail` instance. A gift's recipient hears of it through its `gift` template once the purchase is paid; restyle it there, with `setupEmail(components, { templates: { gift } })` . Checked when `setupBilling` runs: an import cycle through `email.ts` can hand it over as `undefined` despite the type, and that fails the deploy instead of the first paid gift.	src/convex/integrations/billing/types/setup.ts
`accessToken?`	`string`	Provider access token. Defaults to the required `BILLING_ACCESS_TOKEN` env var.	src/convex/integrations/billing/types/setup.ts
`environment?`	`"sandbox"` \| `"production"`	Provider environment. Defaults to the required `BILLING_ENVIRONMENT` env var (`'sandbox'` otherwise).	src/convex/integrations/billing/types/setup.ts
`webhookSecret?`	`string`	Webhook signature secret. Defaults to the required `BILLING_WEBHOOK_SECRET` env var.	src/convex/integrations/billing/types/setup.ts
`products?`	`Record` <`string` , `string` >	Friendly product keys → provider product ids (`{ pro: '…' }` ), so a current subscription reads with its `productKey` . Usually supplied via `catalog` ; an explicit map wins.	src/convex/integrations/billing/types/setup.ts
`trustedOrigins?`	`string`	Origins, besides `SITE_URL` 's, a checkout, a gift checkout or the customer portal may send the buyer back to (`['https://app.example.com']` ) — a second domain the app is served from, say. Every other return or embed URL is refused as `invalid_input` . With `AUTH_TRUST_LOCAL_ORIGINS=1` (local development) loopback origins are trusted too.	src/convex/integrations/billing/types/setup.ts
`billTo?`	`"user"` \| `"organization"`	Who owns subscriptions and credits: the active workspace (`'organization'` , the default — members share the workspace's plan and credits) or the individual user (`'user'` , for B2C apps without shared billing).	src/convex/integrations/billing/types/setup.ts
`resolveEntity?`	(`ctx` ) => `Promise` < `BillingEntity` \| `null` >	Resolve the billing entity yourself, in place of the identity claims `billTo` reads. One resolver for every context: the reactive reads (`getCurrentSubscription` , `getFeatures` , `getCredits` ), checkout and the portal, spends and the subscription lifecycle. It is called with every context, signed in or not, so it must return `null` when `ctx.auth.getUserIdentity()` does: reads then answer `null` , and provider operations refuse.	src/convex/integrations/billing/types/setup.ts
`rateLimiter?`	`BillingRateLimiter`	Throttle every client-callable function that reaches the live provider — `syncEntitlements` , `syncProducts` , checkout, the subscription-lifecycle actions, order history and invoices. Pass your `setupRateLimiter(...)` limiter and each authenticated call is checked against the `billingSync` limit (10/min, keyed by the workspace/user), so a caller can't loop one to amplify the provider fan-out. `giftCheckout` burns the same limit keyed by the purchaser. Omit to leave them unthrottled.	src/convex/integrations/billing/types/setup.ts
`multipleSubscriptions?`	`boolean`	Let one billing entity hold several live subscriptions at once (a plan plus add-ons, say). The upstream single-subscription read throws the moment a second one exists, so this switches `getCurrentSubscription` to the subscriptions-array-first shape ( CurrentSubscriptions ) and makes `subscriptionId` the way lifecycle actions pick their target.	src/convex/integrations/billing/types/setup.ts
`requireAdmin?`	(`ctx` ) => `Promise` <`void` >	Gate the admin-tier billing actions (`refundOrder` — moving real money). Throw from here to refuse. The default requires an `admin` role claim on the caller's identity (the admin plugin's role, carried on the JWT); supply your own to check permissions, a workspace role, or an allowlist.	src/convex/integrations/billing/types/setup.ts
`events?`	`Partial` <`WebhookEventHandlers` >	React to billing webhook events, keyed by the provider's own event names (`'order.paid'` , `'subscription.active'` , …). Your handler runs after the built-in entitlement-cache refresh (and gift fulfilment), so features/credits read fresh inside it. Events outside the built-in refresh set are mounted too.	src/convex/integrations/billing/types/setup.ts
`canGift?`	(`ctx` , `input` ) => \| `true` \| `Promise` < \| `true` \| { `allowed` : `false` ; `message?` : `string` ; }> \| { `allowed` : `false` ; `message?` : `string` ; }	Decide who may receive a gift, before `giftCheckout` opens the purchaser's checkout — only addresses on your own domain, say, or only sandbox addresses on a public demo. It adds to the package's own rules, which always hold: no gift to the purchaser's own address, an earlier paid order of the purchaser's first, and SetupBillingConfig.giftLimit . Return `true` to allow, or a refusal whose `message` `giftCheckout` throws as a `ConvexError` , so it reaches the purchaser even where production redacts other errors (default: "This address can't receive gifts."). Called with the action ctx, so it can read your own tables; `recipientEmail` is lower-cased, and `purchaserEntityId` is the billing entity that pays.	src/convex/integrations/billing/types/setup.ts
`giftLimit?`	{ `max?` : `number` ; `days?` : `number` ; }	How many gifts one purchaser may buy in a window: `max` paid gifts in `days` days (default 10 in 30). A stolen card that can buy gifts for strangers is a way to cash it out, and a claimed gift can't be taken back, so the cap holds whatever rate limiter the app passes. A further purchase is `rate_limited` (`limit: 'gifts'` ).	src/convex/integrations/billing/types/setup.ts
`giftLimit.max?`	`number`	-	src/convex/integrations/billing/types/setup.ts
`giftLimit.days?`	`number`	-	src/convex/integrations/billing/types/setup.ts
`credits?`	`Record` <`string` , `CreditMeterConfig` >	Named credit meters: spend by friendly name (`spendCredits({ meter: 'credits' })` , `useCredits('credits')` ) instead of provider meter ids. Usually supplied via `catalog` ; explicit entries here win.	src/convex/integrations/billing/types/setup.ts
`catalog?`	`Partial` <`Record` <`"sandbox"` \| `"production"` , `BillingCatalogIds` \| `undefined` >>	The environment-keyed id map generated by `nuxt-backend billing sync` (`backend/billing.generated.ts` ): fills `products` and `credits` for the active `BILLING_ENVIRONMENT` , so provider UUIDs live in exactly one generated file. Explicit `products` /`credits` config wins.	src/convex/integrations/billing/types/setup.ts
`onUnknownEvent?`	(`ctx` , `event` ) => `Promise` <`void` >	Called for an authentic (signature-verified) webhook event whose type this package's provider SDK cannot parse — e.g. an event newer than the installed package. The delivery is acknowledged with 202 either way, so unknown types can never put the endpoint into a retry loop.	src/convex/integrations/billing/types/setup.ts

--- ### Billing Defined in: [src/convex/integrations/billing/types/surface.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/surface.ts) #### Properties

Property	Type	Description	Defined in
`api`	`Pick` <{ `changeCurrentSubscription` : `RegisteredAction` <`"public"` , { `productId` : `string` ; }, `Promise` <`void` >>; `cancelCurrentSubscription` : `RegisteredAction` <`"public"` , { `revokeImmediately?` : `boolean` ; }, `Promise` <`void` >>; `getConfiguredProducts` : `RegisteredQuery` <`"public"` , { }, `Promise` <{ [`key` : `string` ]: \| { `benefits?` : { `createdAt` : ...; `deletable` : ...; `description` : ...; `id` : ...; `metadata?` : ...; `modifiedAt` : ...; `organizationId` : ...; `properties?` : ...; `selectable` : ...; `type` : ...; } ; `createdAt` : `string` ; `description` : `string` \| `null` ; `id` : `string` ; `isArchived` : `boolean` ; `isRecurring` : `boolean` ; `medias` : { `checksumEtag` : ... \| ...; `checksumSha256Base64` : ... \| ...; `checksumSha256Hex` : ... \| ...; `createdAt` : `string` ; `id` : `string` ; `isUploaded` : `boolean` ; `lastModifiedAt` : ... \| ...; `mimeType` : `string` ; `name` : `string` ; `organizationId` : `string` ; `path` : `string` ; `publicUrl` : `string` ; `service?` : ... \| ...; `size` : `number` ; `sizeReadable` : `string` ; `storageVersion` : ... \| ...; `version` : ... \| ...; } ; `metadata?` : `Record` <`string` , `any` >; `modifiedAt` : `string` \| `null` ; `name` : `string` ; `organizationId` : `string` ; `priceAmount?` : `number` ; `prices` : { `amountType?` : ... \| ...; `capAmount?` : ... \| ... \| ...; `createdAt` : `string` ; `id` : `string` ; `isArchived` : `boolean` ; `maximumAmount?` : ... \| ... \| ...; `meter?` : ... \| ...; `meterId?` : ... \| ...; `minimumAmount?` : ... \| ... \| ...; `modifiedAt` : ... \| ...; `presetAmount?` : ... \| ... \| ...; `priceAmount?` : ... \| ...; `priceCurrency?` : ... \| ...; `productId` : `string` ; `recurringInterval?` : ... \| ... \| ...; `seatTiers?` : ... \| ...; `source?` : ... \| ...; `type?` : ... \| ...; `unitAmount?` : ... \| ...; } ; `recurringInterval?` : `string` \| `null` ; `recurringIntervalCount?` : `number` \| `null` ; `trialInterval?` : `string` \| `null` ; `trialIntervalCount?` : `number` \| `null` ; } \| `undefined` ; }>>; `listAllProducts` : `RegisteredQuery` <`"public"` , { }, `Promise` <{ `benefits?` : { `createdAt` : `string` ; `deletable` : `boolean` ; `description` : `string` ; `id` : `string` ; `metadata?` : ... \| ...; `modifiedAt` : ... \| ...; `organizationId` : `string` ; `properties?` : `any` ; `selectable` : `boolean` ; `type` : `string` ; } ; `createdAt` : `string` ; `description` : `string` \| `null` ; `id` : `string` ; `isArchived` : `boolean` ; `isRecurring` : `boolean` ; `medias` : { `checksumEtag` : `string` \| `null` ; `checksumSha256Base64` : `string` \| `null` ; `checksumSha256Hex` : `string` \| `null` ; `createdAt` : `string` ; `id` : `string` ; `isUploaded` : `boolean` ; `lastModifiedAt` : `string` \| `null` ; `mimeType` : `string` ; `name` : `string` ; `organizationId` : `string` ; `path` : `string` ; `publicUrl` : `string` ; `service?` : `string` ; `size` : `number` ; `sizeReadable` : `string` ; `storageVersion` : `string` \| `null` ; `version` : `string` \| `null` ; } ; `metadata?` : `Record` <`string` , `any` >; `modifiedAt` : `string` \| `null` ; `name` : `string` ; `organizationId` : `string` ; `priceAmount?` : `number` ; `prices` : { `amountType?` : `string` ; `capAmount?` : `number` \| `null` ; `createdAt` : `string` ; `id` : `string` ; `isArchived` : `boolean` ; `maximumAmount?` : `number` \| `null` ; `meter?` : { `id` : ...; `name` : ...; }; `meterId?` : `string` ; `minimumAmount?` : `number` \| `null` ; `modifiedAt` : `string` \| `null` ; `presetAmount?` : `number` \| `null` ; `priceAmount?` : `number` ; `priceCurrency?` : `string` ; `productId` : `string` ; `recurringInterval?` : `string` \| `null` ; `seatTiers?` : ... ; `source?` : `string` ; `type?` : `string` ; `unitAmount?` : `string` ; } ; `recurringInterval?` : `string` \| `null` ; `recurringIntervalCount?` : `number` \| `null` ; `trialInterval?` : `string` \| `null` ; `trialIntervalCount?` : `number` \| `null` ; } >>; `listAllSubscriptions` : `RegisteredQuery` <`"public"` , { }, `Promise` <{ `amount` : `number` \| `null` ; `cancelAtPeriodEnd` : `boolean` ; `canceledAt?` : `string` \| `null` ; `checkoutId` : `string` \| `null` ; `createdAt` : `string` ; `currency` : `string` \| `null` ; `currentPeriodEnd` : `string` \| `null` ; `currentPeriodStart` : `string` ; `customFieldData?` : `Record` <`string` , `any` >; `customerCancellationComment?` : `string` \| `null` ; `customerCancellationReason?` : `string` \| `null` ; `customerId` : `string` ; `discountId?` : `string` \| `null` ; `endedAt` : `string` \| `null` ; `endsAt?` : `string` \| `null` ; `id` : `string` ; `metadata` : `Record` <`string` , `any` >; `modifiedAt` : `string` \| `null` ; `priceId?` : `string` ; `product` : \| { `benefits?` : ... ; `createdAt` : `string` ; `description` : `string` \| `null` ; `id` : `string` ; `isArchived` : `boolean` ; `isRecurring` : `boolean` ; `medias` : { `checksumEtag` : ...; `checksumSha256Base64` : ...; `checksumSha256Hex` : ...; `createdAt` : ...; `id` : ...; `isUploaded` : ...; `lastModifiedAt` : ...; `mimeType` : ...; `name` : ...; `organizationId` : ...; `path` : ...; `publicUrl` : ...; `service?` : ...; `size` : ...; `sizeReadable` : ...; `storageVersion` : ...; `version` : ...; } ; `metadata?` : `Record` <..., ...>; `modifiedAt` : `string` \| `null` ; `name` : `string` ; `organizationId` : `string` ; `prices` : { `amountType?` : ...; `capAmount?` : ...; `createdAt` : ...; `id` : ...; `isArchived` : ...; `maximumAmount?` : ...; `meter?` : ...; `meterId?` : ...; `minimumAmount?` : ...; `modifiedAt` : ...; `presetAmount?` : ...; `priceAmount?` : ...; `priceCurrency?` : ...; `productId` : ...; `recurringInterval?` : ...; `seatTiers?` : ...; `source?` : ...; `type?` : ...; `unitAmount?` : ...; } ; `recurringInterval?` : `string` \| `null` ; `recurringIntervalCount?` : `number` \| `null` ; `trialInterval?` : `string` \| `null` ; `trialIntervalCount?` : `number` \| `null` ; } \| `null` ; `productId` : `string` ; `recurringInterval` : `string` \| `null` ; `recurringIntervalCount?` : `number` ; `seats?` : `number` \| `null` ; `startedAt` : `string` \| `null` ; `status` : `string` ; `trialEnd?` : `string` \| `null` ; `trialStart?` : `string` \| `null` ; } >>; `generateCheckoutLink` : `RegisteredAction` <`"public"` , { `metadata?` : `Record` <`string` , `string` >; `trialInterval?` : `string` \| `null` ; `trialIntervalCount?` : `number` \| `null` ; `subscriptionId?` : `string` ; `locale?` : `string` ; `productIds` : `string` ; `origin` : `string` ; `successUrl` : `string` ; }, `Promise` <{ `url` : `string` ; }>>; `generateCustomerPortalUrl` : `RegisteredAction` <`"public"` , { `returnUrl?` : `string` ; }, `Promise` <{ `url` : `string` ; }>>; }, `"getConfiguredProducts"` > & { `listAllSubscriptions` : `RegisteredQuery` <`"public"` >; `giftCheckout` : `RegisteredAction` <`"public"` >; `generateCheckoutLink` : `RegisteredAction` <`"public"` , `CheckoutOptions` , `Promise` <{ `url` : `string` ; }>>; `generateCustomerPortalUrl` : `RegisteredAction` <`"public"` , { `returnUrl?` : `string` ; }, `Promise` <{ `url` : `string` ; }>>; }	The ready-made checkout, portal, price-list and gift functions to re-export from your Convex module. Of the provider's own `api()` only `getConfiguredProducts` (the price list) is kept; the rest are this package's, and refuse with catalog codes (see `backendError` ): - `generateCheckoutLink` sells only the app's catalog, returns only to the site (`SITE_URL` or `trustedOrigins` ), refuses the metadata keys the package reads back, and takes a discount code and campaign attribution; the trial and a discount by id are Billing.checkout 's. - `generateCustomerPortalUrl` returns only to the site. - `giftCheckout` gifts a catalog credit pack, by its key. - `listAllSubscriptions` resolves the billing entity like the reactive reads do: `null` instead of a throw for claimless callers.	src/convex/integrations/billing/types/surface.ts
`functions`	{ `getCurrentSubscription` : `RegisteredQuery` <`"public"` >; `getFeatures` : `RegisteredQuery` <`"public"` >; `getCredits` : `RegisteredQuery` <`"public"` >; `syncEntitlements` : `RegisteredAction` <`"public"` >; `syncProducts` : `RegisteredAction` <`"internal"` >; `getReceivedGifts` : `RegisteredQuery` <`"public"` >; `claimGift` : `RegisteredAction` <`"public"` >; `getWebhookDeliveries` : `RegisteredQuery` <`"public"` >; `updateSubscription` : `RegisteredAction` <`"public"` >; `cancelSubscription` : `RegisteredAction` <`"public"` >; `uncancelSubscription` : `RegisteredAction` <`"public"` >; `pauseSubscription` : `RegisteredAction` <`"public"` >; `resumeSubscription` : `RegisteredAction` <`"public"` >; `getOrders` : `RegisteredAction` <`"public"` >; `getInvoiceUrl` : `RegisteredAction` <`"public"` >; `getUsageHistory` : `RegisteredAction` <`"public"` >; `refundOrder` : `RegisteredAction` <`"public"` >; }	Ready-made, client-callable functions to re-export from your `billing.ts` so `useBilling` / `useFeatures` / `useCredits` / `useGifts` work with zero hand-wiring: the reactive current-subscription, feature-gating and credit-balance queries, a `syncEntitlements` action to refresh the cache after checkout / top-up, an internal `syncProducts` action to pull the provider's product catalog into the reactive products table (fresh deployments render empty pricing until `npx convex run billing:syncProducts` runs once — webhooks keep it fresh afterwards), and the gift queries/claim action.	src/convex/integrations/billing/types/surface.ts
`functions.getCurrentSubscription`	`RegisteredQuery` <`"public"` >	-	src/convex/integrations/billing/types/surface.ts
`functions.getFeatures`	`RegisteredQuery` <`"public"` >	-	src/convex/integrations/billing/types/surface.ts
`functions.getCredits`	`RegisteredQuery` <`"public"` >	-	src/convex/integrations/billing/types/surface.ts
`functions.syncEntitlements`	`RegisteredAction` <`"public"` >	-	src/convex/integrations/billing/types/surface.ts
`functions.syncProducts`	`RegisteredAction` <`"internal"` >	Ops-only (internal): `npx convex run billing:syncProducts` .	src/convex/integrations/billing/types/surface.ts
`functions.getReceivedGifts`	`RegisteredQuery` <`"public"` >	-	src/convex/integrations/billing/types/surface.ts
`functions.claimGift`	`RegisteredAction` <`"public"` >	-	src/convex/integrations/billing/types/surface.ts
`functions.getWebhookDeliveries`	`RegisteredQuery` <`"public"` >	The webhook delivery log, newest first — admin-tier, like `refundOrder` (see `requireAdmin` on SetupBillingConfig ): `null` for anyone else, signed out included.	src/convex/integrations/billing/types/surface.ts
`functions.updateSubscription`	`RegisteredAction` <`"public"` >	Switch the caller's subscription to another product.	src/convex/integrations/billing/types/surface.ts
`functions.cancelSubscription`	`RegisteredAction` <`"public"` >	Cancel at period end (default) or revoke immediately.	src/convex/integrations/billing/types/surface.ts
`functions.uncancelSubscription`	`RegisteredAction` <`"public"` >	Undo a scheduled cancellation.	src/convex/integrations/billing/types/surface.ts
`functions.pauseSubscription`	`RegisteredAction` <`"public"` >	Pause at period end.	src/convex/integrations/billing/types/surface.ts
`functions.resumeSubscription`	`RegisteredAction` <`"public"` >	Resume a paused subscription immediately.	src/convex/integrations/billing/types/surface.ts
`functions.getOrders`	`RegisteredAction` <`"public"` >	The caller's order history, read live from the provider.	src/convex/integrations/billing/types/surface.ts
`functions.getInvoiceUrl`	`RegisteredAction` <`"public"` >	A signed invoice URL for one of the caller's orders.	src/convex/integrations/billing/types/surface.ts
`functions.getUsageHistory`	`RegisteredAction` <`"public"` >	The caller's metered consumption history, read live from the provider.	src/convex/integrations/billing/types/surface.ts
`functions.refundOrder`	`RegisteredAction` <`"public"` >	Refund an order — admin-tier (see `requireAdmin` on SetupBillingConfig ).	src/convex/integrations/billing/types/surface.ts
`webhookEvents`	`BillingWebhookEventHandlers`	Typed billing webhook handlers for `registerBackendRoutes` (mounted at `/billing/events` ) that keep the reactive cache fresh (subscriptions, benefit grants, credit balances) and fulfil paid gifts.	src/convex/integrations/billing/types/surface.ts
`webhookHandler`	(`ctx` , `request` ) => `Promise` <`Response` >	The guarded `/billing/events` endpoint `registerBackendRoutes` mounts: fail-closed (503 while the secret is unset, 413 over the size cap, 403 on bad signatures across the rotation list, 200 on redeliveries of processed ids, 202 for authentic-but-unknown types) with every delivery outcome recorded in the component's delivery log.	src/convex/integrations/billing/types/surface.ts
`getCustomerState`	(`ctx` , `args` ) => `Promise` < `CustomerEntitlements` >	Resolve a user's full billing entitlement state (active plans, benefits, and credit-meter balances) live from the provider. Call from an action ; the ready-made `syncEntitlements` already caches the result for you.	src/convex/integrations/billing/types/surface.ts
`checkout`	(`ctx` , `options` ) => `Promise` <{ `url` : `string` ; }>	A checkout for the caller's billing entity, from server code — the `generateCheckoutLink` checks, plus what only the server chooses: a `trial` of at most 30 days (or `false` to remove the product's own) and a `discountId` . Call it from your own action, after deciding the caller qualifies. Example // A 30-day trial for people who came through a partner. The product is // still checked against the catalog, and the URLs against the site. export const partnerCheckout = action({ args: { productId: v.string(), origin: v.string(), successUrl: v.string() }, handler: async (ctx, { productId, ...urls }) => { if (!(await cameThroughPartner(ctx))) throw backendError('forbidden', { reason: 'permission' }) return billing.checkout(ctx, { productIds: [productId], ...urls, trial: { interval: 'day', count: 30 } }) }, })	src/convex/integrations/billing/types/surface.ts
`portal`	(`ctx` , `options?` ) => `Promise` <{ `url` : `string` ; }>	A customer-portal session for the caller's billing entity, from server code — what `generateCustomerPortalUrl` returns. With workspaces the session is the caller's own member of the workspace's billing customer, and only its owner or a billing manager gets one: anyone else is `forbidden` (reason `not_billing_manager` ). An entity that never paid is `not_ready` (reason `no_customer` ). `returnUrl` must be on the site's own origin or a `trustedOrigins` entry. Example `export const openBilling = action({ args: {}, handler: ctx => billing.portal(ctx, { returnUrl:` ${process.env.SITE_URL}/app/billing`}), })`	src/convex/integrations/billing/types/surface.ts
`spendCredits`	(`ctx` , `event` ) => `Promise` <`void` >	Spend prepaid credits — call from your own server action when a metered feature is used. The billing entity (workspace or user, per `billTo` ) resolves from the caller's identity; pass `userId` to spend for a specific entity. With a configured `meter` (or raw `meterId` ), the spend reserves against the cached balance atomically (strictly prepaid — two concurrent spends can never both pass), ingests the provider event, then settles; a failed run releases the reservation and consumes nothing.	src/convex/integrations/billing/types/surface.ts
`refundCredits`	(`ctx` , `event` ) => `Promise` <`void` >	Give credits back on a sum meter (compensating negative-value event + optimistic cache re-credit). Count meters cannot be refunded.	src/convex/integrations/billing/types/surface.ts
`reserveCredits`	(`ctx` , `event` ) => `Promise` < `SpendReservation` >	The reserve step of a spend, alone — for flows that run work between the guard and the charge (`setupAi().meteredAction` / streaming). Atomically reserves against the cached balance (throws when insufficient) and returns serializable addressing data for Billing.settleSpend / Billing.releaseSpend . `allowRefresh: false` skips the cold-cache self-heal (required from mutation contexts — the refresh fetches).	src/convex/integrations/billing/types/surface.ts
`settleSpend`	(`ctx` , `reservation` , `options?` ) => `Promise` <`void` >	Ingest the provider event for a reservation and finalize the spend.	src/convex/integrations/billing/types/surface.ts
`releaseSpend`	(`ctx` , `reservation` ) => `Promise` <`void` >	Undo a reservation whose work failed — nothing is charged.	src/convex/integrations/billing/types/surface.ts
`resolveEntity`	(`ctx` ) => `Promise` < `BillingEntity` \| `null` >	Resolve the caller's billing entity the way every billing function does: `setupBilling` 's `resolveEntity` when given, else identity claims — the active workspace (`billTo: 'organization'` ) or the signed-in user. `null` when signed out. Any query, mutation or action context will do.	src/convex/integrations/billing/types/surface.ts
`forgetEntity`	(`ctx` , `userId` ) => `Promise` <`void` >	Forget a billing entity: drop its cached entitlements (plans, benefits, credit balances, in-flight reservations). The provider's customer record is untouched — this is the app-side erasure step, e.g. from the `onUserDeleted` auth hook with the deleted user's id (`billTo: 'user'` ) or a dissolved workspace's id. A no-op for an unknown entity.	src/convex/integrations/billing/types/surface.ts
`discounts`	`BillingDiscounts`	Discount (coupon) management: `create` , `list` , `remove` . Server-side by design — minting discounts is privileged, so wire it through an `internalAction` or your own admin-tier action.	src/convex/integrations/billing/types/surface.ts
`updateSubscription`	(`ctx` , `options?` ) => `Promise` <`Subscription` >	Switch a subscription to another product (upgrade / downgrade), optionally choosing how the mid-period difference is settled. Call from an action ; the ready-made `updateSubscription` function does it for the caller.	src/convex/integrations/billing/types/surface.ts
`cancelSubscription`	(`ctx` , `options?` ) => `Promise` <`Subscription` >	Cancel a subscription — at period end by default, immediately with `atPeriodEnd: false` . The reason and comment are the customer's own words and are visible to them.	src/convex/integrations/billing/types/surface.ts
`uncancelSubscription`	(`ctx` , `options?` ) => `Promise` <`Subscription` >	Undo a scheduled cancellation, putting the subscription back on renewal.	src/convex/integrations/billing/types/surface.ts
`pauseSubscription`	(`ctx` , `options?` ) => `Promise` <`Subscription` >	Pause a subscription at the end of the current period, optionally with an automatic resume date. Pause/resume are newer than the rest of the lifecycle: the provider's `subscription.paused` / `subscription.resumed` webhooks are known to the installed SDK but not confirmed live here, so entitlement reads treat a paused subscription as still live rather than assuming an event will arrive to say so.	src/convex/integrations/billing/types/surface.ts
`resumeSubscription`	(`ctx` , `options?` ) => `Promise` <`Subscription` >	Resume a paused subscription immediately, starting a new billing period.	src/convex/integrations/billing/types/surface.ts
`getOrders`	(`ctx` , `options?` ) => `Promise` < `BillingPage` < `BillingOrder` > \| `null` >	The billing entity's order history, read live from the provider — this package keeps no local order table (that would be a ledger, and the provider already is one). `null` when no access token is configured.	src/convex/integrations/billing/types/surface.ts
`getInvoiceUrl`	(`ctx` , `orderId` ) => `Promise` < \| { `url` : `string` ; } \| `null` >	A URL to one of the entity's own invoices. `null` when no access token is configured, and `null` while the provider is still generating the PDF (the call asks for generation, then the next call returns the URL). Throws if the order belongs to a different billing account.	src/convex/integrations/billing/types/surface.ts
`getUsageHistory`	(`ctx` , `options?` ) => `Promise` < `BillingPage` < `UsageEvent` > \| `null` >	The billing entity's metered consumption history, read live from the provider's events API. There is no local usage ledger by design: the events this package ingests when it spends credits are the record, and the provider bills from them. `null` when no access token is configured.	src/convex/integrations/billing/types/surface.ts
`refundOrder`	(`ctx` , `options` ) => `Promise` < `RefundRecord` >	Refund an order — admin-tier, gated by `requireAdmin` ( SetupBillingConfig ). Omit `amount` to refund whatever is still refundable. Credits are not reversed here: meter credits come from the provider's own benefit grants, so the refund's `order.refunded` webhook is what reverses them. This package only drops the entity's in-flight spend reservations and re-reads the provider's balance.	src/convex/integrations/billing/types/surface.ts

## Type Aliases ### DiscountInput ```ts type DiscountInput = Parameters[1]; ``` Defined in: [src/convex/integrations/billing/types/base.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/base.ts) Full discount-create payload (derived from the provider SDK) — fixed or percentage. --- ### ProrationBehavior ```ts type ProrationBehavior = "invoice" | "prorate" | "next_period" | "reset"; ``` Defined in: [src/convex/integrations/billing/types/base.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/base.ts) How the provider settles the money difference when a subscription switches product mid-period (`proration_behavior`). Omit to use the organization's configured default. --- ### ClientProrationBehavior ```ts type ClientProrationBehavior = "invoice" | "prorate"; ``` Defined in: [src/convex/integrations/billing/types/base.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/base.ts) The subset of [ProrationBehavior](#prorationbehavior) a **client** may choose. `invoice` and `prorate` both settle the difference now; `next_period` and `reset` hand over the new plan's credits and features immediately while deferring (or waiving) the charge, so letting a caller pick one is letting them upgrade themselves for free. Those two stay server-side: pass them from app code through `billing.updateSubscription(ctx, …)`, or make them the organization's configured default. --- ### CancellationReason ```ts type CancellationReason = | "customer_service" | "low_quality" | "missing_features" | "switched_service" | "too_complex" | "too_expensive" | "unused" | "other"; ``` Defined in: [src/convex/integrations/billing/types/base.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/base.ts) The provider's churn-reason enum, recorded with a cancellation. Only set it when the customer actually told you — it surfaces to them in their purchases library, so it is their words, not an internal note. --- ### RefundReason ```ts type RefundReason = | "duplicate" | "fraudulent" | "customer_request" | "service_disruption" | "satisfaction_guarantee" | "other"; ``` Defined in: [src/convex/integrations/billing/types/base.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/base.ts) Why an order was refunded (provider `refunds.create` reason). --- ### CurrentSubscriptions ```ts type CurrentSubscriptions = { subscriptions: Record[]; } & Record; ``` Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) What `getCurrentSubscription` returns once `multipleSubscriptions` ([SetupBillingConfig](#setupbillingconfig)) is on: the array leads, because with add-ons there is no single "the" subscription. The primary subscription's own fields are spread alongside it, so single-plan consumers (`subscription.productId`, `subscription.status`) keep reading exactly as before. Still `null` when the entity has no live subscription at all — the "null means free plan" contract never changes. #### Type Declaration

Name	Type	Description	Defined in
`subscriptions`	`Record` <`string` , `unknown` >	Every live subscription, in the provider's order.	src/convex/integrations/billing/types/options.ts

--- ### BillingOrder ```ts type BillingOrder = { id: string; createdAt: string; status: string; totalAmount: number; currency: string; paid: boolean; invoiceNumber: string | null; isInvoiceGenerated: boolean; } & Record; ``` Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) A past charge, normalized for a Convex action's return value: the provider's `Order` fields with every date rendered as an ISO string (Convex cannot serialize `Date`). The index signature keeps every other provider field reachable without a cast. #### Type Declaration

Name	Type	Description	Defined in
`id`	`string`	-	src/convex/integrations/billing/types/options.ts
`createdAt`	`string`	-	src/convex/integrations/billing/types/options.ts
`status`	`string`	-	src/convex/integrations/billing/types/options.ts
`totalAmount`	`number`	Amount in the currency's minor unit (cents), after discounts and taxes.	src/convex/integrations/billing/types/options.ts
`currency`	`string`	-	src/convex/integrations/billing/types/options.ts
`paid`	`boolean`	-	src/convex/integrations/billing/types/options.ts
`invoiceNumber`	`string` \| `null`	Assigned when the invoice is finalized; `null` on draft orders.	src/convex/integrations/billing/types/options.ts
`isInvoiceGenerated`	`boolean`	Whether an invoice PDF exists yet — Billing.getInvoiceUrl needs one.	src/convex/integrations/billing/types/options.ts

--- ### UsageEvent ```ts type UsageEvent = { id: string; timestamp: string; name: string; units?: number; metadata?: Record; } & Record; ``` Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) One ingested usage event as the provider's events API returns it, normalized for a Convex action's return value (dates as ISO strings). `units` is resolved from the meter's value property — the same property a spend ingests — and is absent when the meter is unknown or counts events rather than summing a property. #### Type Declaration

Name	Type	Defined in
`id`	`string`	src/convex/integrations/billing/types/options.ts
`timestamp`	`string`	src/convex/integrations/billing/types/options.ts
`name`	`string`	src/convex/integrations/billing/types/options.ts
`units?`	`number`	src/convex/integrations/billing/types/options.ts
`metadata?`	`Record` <`string` , `string` \| `number` \| `boolean` >	src/convex/integrations/billing/types/options.ts

--- ### CheckoutOptions ```ts type CheckoutOptions = { productIds: string[]; origin: string; successUrl: string; subscriptionId?: string; metadata?: Record; locale?: string; prefill?: CheckoutPrefill; customFields?: Record; requireBillingAddress?: boolean; allowDiscountCodes?: boolean; discountCode?: string; utm?: CampaignAttribution; }; ``` Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) Everything [Billing.api](#api)'s `generateCheckoutLink` accepts from a client. A type alias rather than an interface so it can type the registered action itself (Convex's `DefaultFunctionArgs` needs an implicit index signature, which only aliases get). What is bought and where the buyer lands are checked on the server: every product must be in the app's catalog, and `origin` and `successUrl` on the site's own origin (`SITE_URL`) or one of `trustedOrigins`. The trial is the product's own, and a discount is the code the customer types or `discountCode`: a different trial or a discount by id is the server's choice, through [Billing.checkout](#checkout). #### Properties

Property	Type	Description	Defined in
`productIds`	`string`	Provider product ids, each one from the app's catalog.	src/convex/integrations/billing/types/options.ts
`origin`	`string`	The origin of the page embedding the checkout (for the iframe handshake).	src/convex/integrations/billing/types/options.ts
`successUrl`	`string`	Where the buyer lands after paying.	src/convex/integrations/billing/types/options.ts
`subscriptionId?`	`string`	Upgrade one of the entity's own free subscriptions instead of starting a new one.	src/convex/integrations/billing/types/options.ts
`metadata?`	`Record` <`string` , `string` >	The app's own keys: none the package reads back (see `RESERVED_METADATA_KEYS` ).	src/convex/integrations/billing/types/options.ts
`locale?`	`string`	BCP-47 language tag for the checkout UI.	src/convex/integrations/billing/types/options.ts
`prefill?`	`CheckoutPrefill`	Pre-filled customer details.	src/convex/integrations/billing/types/options.ts
`customFields?`	`Record` <`string` , `string` \| `number` \| `boolean` >	Values for the organization's custom checkout fields, keyed by field slug.	src/convex/integrations/billing/types/options.ts
`requireBillingAddress?`	`boolean`	Require the full billing address, not just the country.	src/convex/integrations/billing/types/options.ts
`allowDiscountCodes?`	`boolean`	Let the customer type a discount code into the provider's own checkout (default `true` ). The provider validates it against the live catalog.	src/convex/integrations/billing/types/options.ts
`discountCode?`	`string`	A discount code to apply up front: a campaign link's code, say. The provider checks it like one the customer typed, and a code it does not know refuses the checkout as `invalid_input` (`discountCode` ).	src/convex/integrations/billing/types/options.ts
`utm?`	`CampaignAttribution`	Campaign attribution, stored as `utm_*` metadata.	src/convex/integrations/billing/types/options.ts

--- ### ServerCheckoutOptions ```ts type ServerCheckoutOptions = CheckoutOptions & { trial?: CheckoutTrial | false; discountId?: string; }; ``` Defined in: [src/convex/integrations/billing/types/options.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/options.ts) What [Billing.checkout](#checkout) takes from server code: everything a client may send, plus what only the server chooses. #### Type Declaration

Name	Type	Description	Defined in
`trial?`	`CheckoutTrial` \| `false`	The trial for this checkout: `false` removes the product's own, an override grants at most 30 days. Omit to keep the product's own trial.	src/convex/integrations/billing/types/options.ts
`discountId?`	`string`	Pre-apply a discount by id — the form the provider's checkout payload takes, and the server's to choose: a 100% discount minted for one claim must never be a client's to name.	src/convex/integrations/billing/types/options.ts

--- ### BillingWebhookEventHandlers ```ts type BillingWebhookEventHandlers = WebhookEventHandlers; ``` Defined in: [src/convex/integrations/billing/types/setup.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/setup.ts) Per-event billing webhook handlers, keyed by the provider's event names (`'order.paid'`, `'subscription.active'`, …). Service-neutral alias for the shape `registerBackendRoutes` mounts at `/billing/events`. --- ### BillingEmail ```ts type BillingEmail = Pick; ``` Defined in: [src/convex/integrations/billing/types/setup.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/types/setup.ts) What billing sends its email through: the app's `setupEmail` instance. ## Variables ### ALL_BILLING_EVENTS ```ts const ALL_BILLING_EVENTS: readonly ["checkout.created", "checkout.updated", "checkout.expired", "customer.created", "customer.updated", "customer.deleted", "customer.state_changed", "customer_seat.assigned", "customer_seat.claimed", "customer_seat.revoked", "member.created", "member.updated", "member.deleted", "order.created", "order.updated", "order.paid", "order.refunded", "subscription.created", "subscription.updated", "subscription.active", "subscription.canceled", "subscription.uncanceled", "subscription.revoked", "subscription.past_due", "refund.created", "refund.updated", "product.created", "product.updated", "benefit.created", "benefit.updated", "benefit_grant.created", "benefit_grant.cycled", "benefit_grant.updated", "benefit_grant.revoked", "organization.updated", "subscription.paused", "subscription.resumed"]; ``` Defined in: [src/convex/integrations/billing/events.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing/events.ts) The provider's full webhook catalog. The composed handler map covers every one of these, so any verified delivery gets logging, dedupe, and consumer dispatch — events outside it (a newer provider than this package) land in `onUnknownEvent` with a 202 instead of an error loop. ## Functions ### defineBillingCatalog() ```ts function defineBillingCatalog(catalog): BillingCatalog; ``` Defined in: [src/convex/catalog.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/catalog.ts) Declare the billing catalog (typed identity). Push it with `npx nuxt-backend billing sync`. #### Parameters

Parameter	Type
`catalog`	`BillingCatalog`

#### Returns [`BillingCatalog`](#billingcatalog) #### Example ```ts export default defineBillingCatalog({ meters: { credits: {} }, plans: { pro: { name: 'Pro', interval: 'month', price: 2900, credits: { meter: 'credits', units: 500 }, features: ['priority_support'], trial: { interval: 'day', count: 14 }, usage: [{ meter: 'credits', unitAmount: 5 }] }, }, packs: { credits500: { name: '500 credits', price: 2000, credits: { meter: 'credits', units: 500 } }, }, features: { priority_support: { description: 'Priority support' } }, }) ``` --- ### setupBilling() ```ts function setupBilling(components, config): Billing; ``` Defined in: [src/convex/integrations/billing.ts](https://github.com/qruto/nuxt-backend/blob/main/src/convex/integrations/billing.ts) Configure billing for subscriptions, discounts, prepaid credits, and gift purchases — linked to your auth users and cached reactively inside the `backend` component (so consumers add nothing to their own schema). Subscription / feature / credit reads return `null`/empty until the provider has synced, so a mid-configuration deployment degrades gracefully; checkout / portal / credit / discount operations need the required `BILLING_ACCESS_TOKEN` env var. Billing follows the tenant: with the default `billTo: 'organization'` the active workspace owns the subscription and credits (every member shares them); with `billTo: 'user'` each user is their own customer. Either way the entity resolves from identity claims — zero wiring — unless `resolveEntity` says otherwise. #### Parameters

Parameter	Type
`components`	`BillingComponents`
`config`	`SetupBillingConfig`

#### Returns [`Billing`](#billing) #### Example ```ts import { setupBilling } from 'nuxt-backend/billing' import { components } from './_generated/api' import { email } from './email' const billing = setupBilling(components, { email }) export const { generateCheckoutLink, generateCustomerPortalUrl, getConfiguredProducts, giftCheckout } = billing.api export const { getCurrentSubscription, getFeatures, getCredits, syncEntitlements, getReceivedGifts, claimGift, } = billing.functions ``` ## Sitemap See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.