User Subscription API

Fetch a single plan plus its entitlements.

List subscription families for the calling tenant. Returned ordered by sort_order so the admin tab bar is stable across reloads.

Every invoice for the calling tenant.

List all plans for the calling tenant. Optionally filter by status.

Catalog of entitlement primitives shipped by the platform. Tenants pick from these when authoring plans. Catalog is code-defined, so this is a pure read.

All refunds for the calling tenant. Optional status filter. Returns empty when refund use cases aren't wired (test setups).

All subscriptions for the calling tenant. Optional status filter.

Plans the authenticated end user is eligible to subscribe to within the given vertical. Filters by (role, vertical) against each plan's allowed_roles and allowed_verticals. Only Active plans are returned.

Active subscriptions held by the calling end user. Excludes terminal states (Canceled / Expired); includes Trialing / Active / PastDue / Grace.

Boot-time configuration for end-user apps. Apps call this once on load and adapt their UI to the result — hiding subscription entries entirely when no plans are enabled, or surfacing "My subscription" when the user has an existing one. app identifies the calling app (e.g. TaxiPassenger) so the resolver can derive Stripe redirect URLs from the tenant's verified domain for that app. Without it, redirect URLs are None and the client must fall back to per-environment defaults.

All invoices for the calling end user across all their subscriptions in this tenant. Paginated.

Move a plan from draft to active. End users see active plans in availableUserSubscriptionPlans. Stripe Product/Price sync attaches here in Phase 2.

Move a plan to archived. Existing subscribers keep their entitlements until period end; new subscribers can no longer choose this plan. Phase 2 also archives the Stripe Product.

Create a new draft plan with its entitlement set. Stripe sync happens when adminActivateUserSubscriptionPlan is called (Phase 2).

Record a refund issued against a user-subscription invoice. v1 model: the actual Stripe refund is created via the tenant's Dashboard or operator tooling; this mutation persists the audit row and links the Stripe refund id once supplied. Webhook charge.refunded flips status to Succeeded when Stripe confirms.

Update a plan's body and replace its entitlement set in one shot.

Cancel the calling end user's subscription. Defaults to at_period_end=true so entitlements stay live until the period closes; pass false to cancel immediately.

Mid-cycle plan change with Stripe proration. Both old and new plans must be Active (Stripe-synced) and in the same family. Stripe issues a prorated invoice immediately.

Open a Stripe Customer Billing Portal so the end user can update their payment method or view invoices.

Reverse a "cancel at period end" scheduling on the calling end user's subscription.

Open a Stripe Checkout Session so the calling end user can subscribe to one of the tenant's published plans. Direct charges on the tenant's Stripe account; the platform never touches funds.