nuxt-x-billing

useBilling

Billing state, actions, and entitlement helpers for nuxt-x-billing — subscription/plans/invoices/payment methods, checkout/portal/cancel/resume, hasFeature/hasPlan/canInviteMember.

useBilling

The billing composable for nuxt-x-billing. Fetches the four billing resources against your backend contract, exposes normalized subscription state and entitlement helpers, and performs the checkout/portal/cancel/resume actions. All endpoints, the envelope shape, and the entitlement semantics are defined by Backend requirements.

Usage

const {
  subscription, plans, invoices, paymentMethods, loading, error,
  status, isSubscribed, currentPlan,
  checkout, openPortal, cancel, resume,
  hasFeature, hasPlan, canInviteMember,
  refresh,
} = useBilling()

await refresh()                                  // fetch all four resources
await checkout('price_pro_monthly')              // → redirect to Stripe Checkout
await openPortal()                               // → redirect to Stripe Portal
await cancel({ immediate: false })               // cancel at period end
await resume()

hasFeature('analytics')                          // plan entitlement keys
hasPlan('pro')                                   // tier check (case-insensitive)
canInviteMember()                                // seat-enforcement hook

Returns

State

Key	Type	Description
`subscription`	`Ref<BillingSubscription \| null>`	Current subscription (`null` = free tier / never subscribed — not an error).
`plans`	`Ref<BillingPlan[]>`	Plan catalog (drives pricing UI + entitlement mapping).
`invoices`	`Ref<BillingInvoice[]>`	Invoice history, newest first.
`paymentMethods`	`Ref<BillingPaymentMethod[]>`	Saved payment methods (brand + last4 only).
`loading`	`Ref<boolean>`	`true` while any request is in flight.
`error`	`Ref<string \| null>`	Envelope failure `message` from the last failed call.
`status`	`ComputedRef<string \| null>`	Normalized subscription status (`active`, `trialing`, `past_due`, `canceled`, …).
`isSubscribed`	`ComputedRef<boolean>`	`true` when `status` ∈ `xBilling.entitledStatuses` (default `['active','trialing']`).
`currentPlan`	`ComputedRef<BillingPlan \| null>`	The subscription's plan, matched by `planId` (fallback `priceId`).

Actions

Key	Signature	Description
`refresh`	`() => Promise<void>`	Fetch all four resources.
`checkout`	`(priceId: string) => Promise<void>`	Create a checkout session and redirect to its Stripe-hosted URL. Sends `xBilling.checkout` URLs (and `tenantId` when tenancy composes).
`openPortal`	`() => Promise<void>`	Create a portal session and redirect. Sends `xBilling.portal.returnUrl`.
`cancel`	`(opts?: { immediate?: boolean }) => Promise<void>`	`immediate: false` (default) cancels at period end; `true` cancels now.
`resume`	`() => Promise<void>`	Clear a pending cancellation.

Entitlements

Key	Signature	Description
`hasFeature`	`(key: string) => boolean`	Subscription in an entitled status and its plan lists the feature key.
`hasPlan`	`(tier: string) => boolean`	Case-insensitive tier match against the current plan.
`canInviteMember`	`() => boolean`	`seats.used < seats.limit` (null limit = unlimited, no subscription = `false`).

Notes

Entitlements are client-mirrored, server-enforced. The helpers above drive UI gating only; always enforce entitlements server-side on your own API routes against the synced subscription table.
Auth-agnostic token pipeline: requests inject Authorization: Bearer from nuxtApp.$getAuthToken when an auth layer provides it; absence is fine.
Endpoint overrides merge per key (xBilling.endpoints.subscription, …) — you never replace the whole endpoint map.
Tenancy composition: when xBilling.tenancy.enabled and nuxtApp.$xTenantId exists, every request carries X-Tenant-ID, checkout/portal payloads carry tenantId, and a watcher clears + refetches state on tenant switch.

AI Context

composable: useBilling
package: "@xenterprises/nuxt-x-billing"
use-when: >
  Any page needing billing state or actions: refresh() loads all four
  resources; checkout/openPortal redirect to Stripe-hosted sessions;
  cancel/resume manage the subscription; hasFeature/hasPlan/
  canInviteMember gate UI (server still enforces). Wire endpoints via
  xBilling.endpoints; base URL via NUXT_PUBLIC_X_BILLING_BASE_URL.

Edit this pageorReport an issue

nuxt-x-billing

Stripe billing layer for Nuxt 4 — useBilling() composable, plan/feature gating (XBBillingGate), and billing container components wired against a consumer-owned backend contract. The layer never talks to Stripe directly.

Components

XBBillingGate plus the XB* container components (SubscriptionCard, PricingGrid, InvoiceHistory) of nuxt-x-billing — all driven by useBilling() state.