Billing System

Inertia Start includes a provider-agnostic billing system based on Laravel Cashier. Choose between our two built-in providers (Stripe or Paddle) to receive payments from your customers. You can also switch providers later without breaking billing management for existing paying customers.

You can sell one-time products and subscriptions, accept payments from signed-in customers and guests, and use ready-made billing Vue components. Customers get a self-service account billing page (payment methods, billing details, downloadable invoices and receipts), and admins can configure the whole catalog from a no-code editor — without touching a config file by hand.

Supported Providers

Stripe

Inertia Start supports Stripe via Laravel Cashier Stripe.

Stripe supports one-time payments, subscriptions, billing portal access, and an optional Managed Payments mode (its new Merchant of Record service that handles global tax registration and remittance for you).

See their full list of supported payment methods.

Paddle

Inertia Start supports Paddle via Laravel Cashier Paddle.

Paddle is a Merchant of Record (MoR) by default, and offers an all-inclusive fee including payment processing and global sales tax handling.

See their full list of supported payment methods.

Features

• Easily switch payment provider: choose between Stripe and Paddle with I_S_DEFAULT_PAYMENT_PROVIDER environment variable.
• One-time payments and subscriptions: supported for both providers.
• Subscriptions: define your plans in config and get a ready-made account billing page where customers subscribe, switch plans, cancel, and resume.
• One-time products: define products in config and sell them through a single shareable checkout link.
• Hosted Buy & Subscribe pages: shareable /buy/{product} and /subscribe/{group}/{plan} links render a ready-made checkout page (plan details, features, price, trial) — no frontend code required.
• Self-service account billing: signed-in customers get an account billing page with their subscriptions, saved payment methods, billing information, and a paginated billing history with downloadable invoices and receipts.
• No-code catalog editors: admins can configure products and subscription plans from the admin UI. Inertia Start writes the config files for you and pulls live prices from your provider catalog.
• Guest checkout: customers can buy without creating an account first. They enter an email at checkout, and Inertia Start creates their account and emails a sign-in link.
• Stripe embedded checkout: optionally embed Stripe Checkout inside the Buy/Subscribe pages instead of redirecting to Stripe.
• Shared billing routes and API: use one set of routes while provider resolution is handled for you.
• Per-customer provider pinning: existing customers stay on their original provider after you switch the active provider (to avoid breaking existing subscriptions and customer portal).
• Provider-agnostic UI components: use PricingCards, CheckoutButton, and CheckoutSection without changing your page code when you switch providers.
• Catalog allowlists: restrict checkout to approved prices and discounts with allowlist variables.
• Component Builder: preview and generate code for CheckoutButton, CheckoutSection, and PricingCards against live provider catalog data from /admin/billing/component-builder.
• Shared Inertia props: every page receives billingEnabled, accountBillingEnabled, billingSubscriptionsEnabled, and paymentProvider (effective provider for the current user/session).

Setup

1. Enable billing and choose a provider

You can use the interactive setup command:

php artisan inertia-start:billing:setup

This command updates I_S_ENABLE_BILLING, I_S_DEFAULT_PAYMENT_PROVIDER, and I_S_ENABLED_PAYMENT_PROVIDERS in your environment file (it keeps previously enabled providers so existing customers are not left behind). You still need to add provider credentials and any optional billing settings manually.

Or configure manually in .env:

# Billing
I_S_ENABLE_BILLING=true
I_S_ENABLE_SUBSCRIPTIONS=false # set to true to enable the subscriptions and manage them in account billing page
I_S_DEFAULT_PAYMENT_PROVIDER=stripe # stripe or paddle
I_S_ENABLED_PAYMENT_PROVIDERS=stripe # default + previously used providers (keep previous providers enabled for existing customers)
I_S_PURCHASE_LINK_DAYS=15 # days a guest-checkout sign-in link stays valid
CASHIER_CURRENCY=usd

# Stripe
STRIPE_KEY=
STRIPE_SECRET=
STRIPE_WEBHOOK_SECRET=
# Optional: allow `*` for all active Stripe prices/discounts, or a comma-separated allowlist
I_S_STRIPE_ALLOWED_PRICES=*
I_S_STRIPE_ALLOWED_DISCOUNTS=*
# Optional: Stripe Managed Payments (https://docs.stripe.com/payments/managed-payments)
#I_S_STRIPE_MANAGED_PAYMENTS_ENABLED=false
# Optional: embed Stripe Checkout on the Buy/Subscribe pages instead of redirecting
#I_S_STRIPE_EMBEDDED_CHECKOUT_ENABLED=false
# Find your Stripe customer portal URL here: https://dashboard.stripe.com/settings/billing/portal
I_S_STRIPE_CUSTOMER_PORTAL_URL=

# Paddle
PADDLE_CLIENT_SIDE_TOKEN=
PADDLE_API_KEY=
PADDLE_WEBHOOK_SECRET=
PADDLE_SANDBOX=true
# Optional: allow `*` for all active Paddle prices/discounts, or a comma-separated allowlist
I_S_PADDLE_ALLOWED_PRICES=*
I_S_PADDLE_ALLOWED_DISCOUNTS=*
# Find your Paddle customer portal URL here: https://vendors.paddle.com/customer-portal-settings
#I_S_PADDLE_CUSTOMER_PORTAL_URL=

2. Create products and prices in your provider dashboard

• Stripe: Create products and prices
• Paddle: Create products and prices

If you plan to use discounts in checkout, create those in your provider dashboard too.

3. Configure webhooks

Provider-specific webhook endpoints used by Inertia Start:

• Stripe: /stripe/webhook
• Paddle: /paddle/webhook

4. Run migrations

php artisan migrate

Switching providers with existing customers

Changing I_S_DEFAULT_PAYMENT_PROVIDER sets the default provider for new purchases and subscriptions.

Enabled providers are controlled by I_S_ENABLED_PAYMENT_PROVIDERS. This list determines which provider-specific webhook routes are available (alongside the current default provider).

When a user already has billing history and that provider remains enabled, Inertia Start keeps that user on the original provider for:

• checkout creation
• customer payload lookup
• customer portal redirection

This means you can safely start with one provider and later move new sales to the other provider without breaking existing subscriptions, as long as the previous provider is still enabled.

Stripe Managed Payments

When using Stripe, you can enable Managed Payments. This mode uses Stripe as a Merchant of Record (global tax compliance is handled by Stripe).

I_S_DEFAULT_PAYMENT_PROVIDER=stripe
I_S_STRIPE_MANAGED_PAYMENTS_ENABLED=true

When enabled, Inertia Start creates Stripe Checkout Sessions with:

• managed_payments.enabled = true
• ; managed_payments_preview=v1 appended to stripe_version

Stripe Embedded Checkout

By default, Stripe checkout sends the customer to Stripe's own hosted page. With embedded checkout, the Stripe Checkout form is rendered inside your own Buy / Subscribe pages instead, so the customer never leaves your domain.

I_S_DEFAULT_PAYMENT_PROVIDER=stripe
I_S_STRIPE_EMBEDDED_CHECKOUT_ENABLED=true

When enabled (Stripe only):

• The hosted /buy/{product} and /subscribe/{group}/{plan} pages mount Stripe's embedded checkout instead of redirecting to Stripe.
• The page receives your Stripe publishable key (config('cashier.key')) so the embedded form can load. Stripe.js is downloaded on demand the first time the form mounts — you never add a script tag yourself.
• The CheckoutButton component exposes stripe-embedded and stripe-key props, and the POST /api/billing/checkout/init endpoint accepts an embedded flag that returns a client_secret instead of a redirect url.

Catalog Allowlists

Use the provider-specific allowlist variables to restrict which catalog items can be used in checkout:

• I_S_STRIPE_ALLOWED_PRICES
• I_S_STRIPE_ALLOWED_DISCOUNTS
• I_S_PADDLE_ALLOWED_PRICES
• I_S_PADDLE_ALLOWED_DISCOUNTS

Use * to allow every active provider item, or provide a comma-separated list of price/discounts IDs. When a disallowed price or discount is submitted to checkout, the billing endpoints return a 404.

The admin catalog endpoints include an allowed_for_checkout flag so you can see what is currently selectable.

Customer Portal

Use route('billing.portal') to redirect users to your payment provider’s customer portal.

BillingService::getBillingPortalUrl() returns a customer-authenticated billing portal URL when possible, and falls back to the configured portal URL when necessary.

Stripe

When using Stripe, Inertia Start will:

• create a Stripe customer automatically if the authenticated user does not have one yet
• reuse, reactivate, or create a Stripe billing portal configuration as needed
• redirect to a customer-specific portal session

If a customer-specific session cannot be generated, it falls back to I_S_STRIPE_CUSTOMER_PORTAL_URL.

Paddle

When using Paddle, you can configure your default customer portal URL (it will be used when no authenticated customer is available), using the I_S_PADDLE_CUSTOMER_PORTAL_URL environment variable. Find your dedicated portal URL in your Paddle dashboard under Business Account > Customer Portal.

If this variable is not set, Inertia Start falls back to https://paddle.net/verify-email.

Subscriptions

You describe your plans once in a config file, and Inertia Start gives you a ready-to-use subscriptions management system and a billing page where your customers can:

• see the pricing with the available plans and billing cycles
• subscribe, switch, cancel, and resume their plans
• go to their customer portal (in Stripe or Paddle) to manage their billing information, payment methods and invoices

Laravel Cashier relies on webhooks to keep subscription and billing data synchronized, and our implementation continues to use them as the primary mechanism for processing billing events. However, we added an extra layer of reliability: whenever a user accesses the billing page, we perform a fresh synchronization with Stripe or Paddle. This complements the webhook-based workflow and ensures the billing page always reflects the current state from the payment provider, even if a webhook is delayed, missed, or temporarily unavailable.

Enable subscriptions

Subscriptions are a separate feature flag layered on top of billing. Enable both:

I_S_ENABLE_BILLING=true
I_S_ENABLE_SUBSCRIPTIONS=true

The subscriptions section of the account billing page only appears when subscriptions are enabled and you have at least one subscription configured.

Define your plans

Create config/env/subscriptions.php, returning an array of subscription groups. Each group has a slug and a list of plans. A plan holds the display info (name, features, ...) and the provider price IDs.

<?php

return [
    [
        'name' => 'Pro membership',
        'slug' => 'pro',                  // used internally as the subscription "type"
        'description' => 'Everything you need to grow.',
        'selected_billing_cycle' => 'monthly',
        'billing_cycle_badges' => [
            'annually' => 'Save 17%',     // badge shown on the annual tab
        ],
        'plans' => [
            [
                'name' => 'Starter',
                'slug' => 'starter-monthly',
                'features' => [
                    'Unlimited projects',
                    'Email support',
                ],
                'stripe' => [
                    'price_id' => 'price_123',
                    'amount' => 1500,         // $15.00, in minor units
                    'currency_code' => 'USD',
                    'billing_cycle' => 'monthly',
                ],
                'paddle' => [
                    'price_id' => 'pri_123',
                    'amount' => 1500,
                    'currency_code' => 'USD',
                    'billing_cycle' => 'monthly',
                ],
            ],
            [
                'name' => 'Starter',
                'slug' => 'starter-annually',
                'accented' => true,           // highlight this card
                'stripe' => [
                    'price_id' => 'price_456',
                    'amount' => 15000,        // $150.00 / year
                    'currency_code' => 'USD',
                    'billing_cycle' => 'annually',
                ],
                'paddle' => [
                    'price_id' => 'pri_456',
                    'amount' => 15000,
                    'currency_code' => 'USD',
                    'billing_cycle' => 'annually',
                ],
            ],
        ],
    ],
];

How it works:

• The group slug is the subscription type Cashier stores. Keep it stable — switching plans happens within a group.
• Each plan must resolve a price ID for the active provider, otherwise it is skipped. Provide both stripe and paddle blocks if you support both providers.
• Shared display values (name, features, ...) go at the plan's top level; provider-specific values (price_id, amount, billing_cycle, ...) go inside the stripe / paddle block. A provider block overrides the matching top-level value.
• name, description, and features may be plain strings or Laravel translation keys, so plans can be localized.
• Put several plans (for example monthly + annually) in the same group to get an automatic billing-cycle switcher.

The account billing page

Signed-in customers get a billing page at /account/billing (route account.billing.index), linked from the user menu and the account sidebar. It's the customer's billing hub and is made of up to four sections, each loaded independently with its own skeleton while data is fetched from the provider:

• Subscriptions — subscribe, switch, cancel, resume (only when subscriptions are configured).
• Payment methods — the cards on file.
• Billing information — the name, address, and tax ID shown on invoices.
• Billing history — past invoices and payments, with downloadable documents.

The page appears as soon as you have configured subscriptions or products (see when it appears). The four sections render based on what's available, so a products-only store still gets payment methods, billing information, and history — just without the subscriptions section.

Subscriptions

When subscriptions are configured, the top of the page lets customers:

• Subscribe to a plan if they don't have one yet.
• Switch to another plan in the same group (upgrade or downgrade).
• Cancel — they keep access until the end of the current period, then it stops renewing.
• Resume a canceled subscription before it ends.
• Resolve payment when a charge fails, via the provider's hosted invoice or payment page.
• Open the provider portal to manage payment methods and invoices.

Each subscription shows a clear status: Active, Trial, Scheduled to cancel, Paused, Payment due, Payment pending, or Inactive.

Switching plans

Plan changes are invoiced immediately, so a paid upgrade is collected before the higher tier is granted.

• Stripe uses a pending update: the current plan stays active until the new invoice is paid. If the payment needs confirmation, the customer is redirected to confirm it. If they change their mind, Keep current plan voids the pending change.
• Paddle swaps and invoices right away. If the payment becomes past due, the customer is sent to update their payment method.

Payment methods

This section lists the cards (and other payment methods) the customer has on file — showing the brand, last four digits, expiry, and a Default badge — fetched from GET /api/billing/payment-methods (api.billing.payment-methods.index). For Stripe it reads the customer's payment methods and default; for Paddle it reads the customer's saved payment methods. A Manage payment methods button sends the customer to the provider portal, where adding, removing, and changing the default actually happens. If the customer has no provider record yet, the list is simply empty.

Billing information

The name, address, and tax ID that appear on the customer's invoices, fetched from GET /api/billing/information (api.billing.information.show). For Stripe it reads the Stripe customer and first tax ID; for Paddle it reads the customer, their most recent address, and business tax identifier. The Edit billing information button opens the provider portal (in a new tab), where the customer updates these details directly with the provider.

Billing history

A paginated table of the customer's past billing activity, fetched from GET /api/billing/history (api.billing.history.index). It uses cursor pagination (cursor + per_page, 1–25, default 10) so customers can load more without loading everything at once. Each row shows a date, reference, total, and status, plus an actions menu to view or download the relevant document:

• Stripe merges two sources into one chronological list: finalized invoices (open, paid, uncollectible, void) and successful one-time payments (Checkout Sessions in payment mode that have no invoice). Invoices link to Stripe's hosted invoice page, the invoice PDF, and — when paid — the receipt. One-time payments link to the Stripe receipt.
• Paddle lists the customer's transactions, linking to the Paddle-hosted invoice/receipt.

Document links never expose provider URLs directly. Instead they point at signed-in redirect endpoints that re-check ownership before sending the customer to the provider:

• GET /api/billing/invoices/{invoice}/open (api.billing.invoices.open) — redirects to the hosted invoice, the PDF (disposition=attachment), or the receipt (document=receipt).
• GET /api/billing/payments/{session}/receipt (api.billing.payments.receipt) — redirects to the Stripe receipt for a one-time payment session.

Let customers start a subscription

On the account billing page customers subscribe automatically. To offer a subscription elsewhere, you have two options: a ready-made hosted page, or your own pricing UI.

Hosted subscribe page

The fastest way to sell a plan is to link customers to its built-in subscribe page — the subscription equivalent of the product buy page:

GET /subscribe/{subscription}/{plan}   (route: billing.subscriptions.subscribe)

<template>
  <a :href="route('billing.subscriptions.subscribe', { subscription: 'pro', plan: 'starter-monthly' })">
    Subscribe to Starter
  </a>
</template>

subscription is the group slug and plan is the plan slug from your subscriptions config. The page renders the plan's name, description, price, billing cycle, free-trial badge, and feature list, then starts a recurring subscription of that type when the customer continues. It needs both the billing and subscriptions features enabled, and returns 404 for an unknown group/plan or a plan marked disabled.

When embedded checkout is off, Stripe customers are redirected straight to Stripe Checkout; otherwise the checkout is mounted on the page. Paddle always opens its overlay on the page.

Your own pricing UI

To build your own pricing page, render a PricingCards grid or a CheckoutButton and pass the group slug as subscription-type. That tells checkout to start a recurring subscription of that type instead of a one-off charge.

<template>
  <!-- starts a subscription of type "pro" -->
  <CheckoutButton
    prices="price_123"
    subscription-type="pro"
    return-to="/account/billing"
  >
    Subscribe
  </CheckoutButton>
</template>

With PricingCards, use the #cta slot to render a CheckoutButton that carries subscription-type (this is exactly what the account billing page does internally).

One-time products

Products are for single, non-recurring purchases (a template pack, a lifetime deal, credits, ...). Like subscriptions, you describe them in a config file and get a shareable checkout link.

Define your products

Create config/env/products.php, returning an array of products keyed by slug:

<?php

return [
    'starter-pack' => [
        'name' => 'Starter pack',
        'description' => 'A one-time bundle to get going.',
        'stripe' => [
            'price_id' => 'price_123',
        ],
        'paddle' => [
            'price_id' => 'pri_123',
        ],
    ],
];

A product can bundle several prices and apply a discount:

'pro-bundle' => [
    'name' => 'Pro bundle',
    'stripe' => [
        'price_ids' => ['price_123', 'price_456'],
        'discount_id' => 'di_123',
    ],
    'paddle' => [
        'price_ids' => ['pri_123', 'pri_456'],
        'discount_id' => 'dsc_123',
    ],
],

Supported keys per product: name, description, price_id / price_ids, and discount_id (set per provider inside the stripe / paddle blocks). Stripe products also accept create_invoice to generate an invoice after payment. name and description may be Laravel translation keys.

The provider block can also hold a read-only amount, currency_code, and discount snapshot (same shape as the subscription plan discount snapshot), written automatically by the config editor so checkout pages can render price/discount details without an extra API call:

'starter-pack' => [
    'name' => 'Starter pack',
    'stripe' => [
        'price_ids' => ['price_123'],
        'discount_id' => 'disc_123',
        // Written automatically by the config editor — no need to set these by hand.
        'amount' => 1500,
        'currency_code' => 'USD',
        'discount' => [
            'id' => 'disc_123',
            'amount_off' => 500,
            'currency_code' => 'USD',
            'duration' => 'once',
        ],
    ],
],

Sell a product

Link customers to the product buy page:

GET /buy/{product}   (route: billing.products.buy)

<template>
  <a :href="route('billing.products.buy', { product: 'starter-pack' })">
    Buy the starter pack
  </a>
</template>

This renders a ready-made buy page showing the product name, description, and a secure checkout button. When the customer continues:

• Stripe redirects them straight to Stripe Checkout (or mounts the form on the page when embedded checkout is on).
• Paddle launches the Paddle overlay on top of the page (Paddle has no full-page redirect checkout).

After payment, the customer lands on the thank-you page and the purchase is recorded in the product_purchases table, linked to their user (or to a guest account created for them).

Stripe invoices after payment

By default a one-time Stripe payment produces a receipt but not a formal invoice. If a product needs a proper invoice (for customers who expect one for accounting), opt in per product with stripe.create_invoice:

'pro-bundle' => [
    'name' => 'Pro bundle',
    'stripe' => [
        'price_ids' => ['price_123'],
        'create_invoice' => true,
    ],
],

When enabled, Inertia Start asks Stripe to create an invoice for the purchase, which then shows up (with a downloadable PDF) in the customer's billing history.

Guest checkout

Customers don't need an account before paying. When a guest completes a product or subscription checkout, Inertia Start:

1. Creates a user account from their checkout email (no password, email pre-verified), or reuses a matching one.
2. Records the purchase or subscription against that account.
3. Emails them a magic sign-in link so they can reach their account and manage billing.

The sign-in link stays valid for I_S_PURCHASE_LINK_DAYS days (default 15):

I_S_PURCHASE_LINK_DAYS=15

Collecting the guest's email

On the hosted buy / subscribe pages, guests are asked for an email before checkout starts (the CheckoutButton shows this automatically via its show-guest-email-input prop). The email is used to send the receipt and to link the purchase to an account.

When a guest enters an email that already belongs to an existing user, Inertia Start reuses that account instead of creating a duplicate. To protect customers who are pinned to the other provider, checkout is blocked with a clear message asking them to sign in first — this avoids accidentally creating a second billing identity for the same person on a different provider.

Thank-you page

After any checkout, customers return to a built-in confirmation page at /billing/thank-you (route billing.thank-you). It:

• verifies the checkout with the provider (Stripe session_id, Paddle _ptxn) and records the purchase,
• adapts its wording to the purchase type — "Thank you for your purchase" for a product, "Thank you for subscribing" for a subscription — and labels the summary line accordingly,
• shows a summary (item/plan, amount, email),
• for signed-in customers, links to their account billing page ("Manage my subscription" for a subscription, "Go to my account" otherwise); for guests, tells them a sign-in link was emailed.

The billing components and the buy/subscribe routes set the correct return URL automatically, so you usually don't build this yourself. If a checkout can't be resolved, the page redirects to the account billing page (signed in) or the home page (guest). The route is localized.

Component Builder

Inertia Start comes with a component builder to quickly create checkout buttons and pricing cards.

The Component Builder is available in your admin area, in Billing > Component Builder (route admin.billing.component-builder, path /admin/billing/component-builder).

• Access is restricted to authenticated, verified admins.
• It loads live provider catalog data through the Stripe/Paddle API.
• It previews CheckoutButton, CheckoutSection, and PricingCards UI components.
• It shows which prices and discounts are currently allowed for checkout (based on your configuration) .

No-code config editors

Defining products and subscriptions by hand in config/env/*.php works well, but Inertia Start also ships visual editors in the admin area so you (or a non-developer teammate) can manage the catalog without touching code. They are next to the Component Builder, under Billing:

Both editors are admin-only and work the same way:

• They load your live provider catalog (products and prices) from the active provider, so you pick a real product/price from a dropdown instead of pasting IDs.
• When you save, Inertia Start rewrites the matching config/env file for you (PUT to admin.billing.products.update / admin.billing.subscriptions.update).
• They edit only the active provider's block (stripe or paddle). The other provider's block for each item is preserved untouched, so editing while Stripe is active never erases your Paddle IDs (and vice-versa) — important when you support both providers.
• Provider-derived values you shouldn't set by hand — product ID, amount, currency, billing cycle, and the selected discount's details (percent/amount off, duration, ...) — are snapshotted from the catalog automatically when you pick a price or discount. You pick both from dropdowns backed by your live provider catalog: there's no free-text discount code field. You only edit display fields (name, slug, description, features, trial days, badges, ...).

Usage

For most apps you only ever need three components:

• CheckoutButton — a single Buy / Subscribe button.
• CheckoutSection — a full checkout card (name, price, features, button, reassurance) for a single product or plan.
• PricingCards — a full pricing table with one or more plans.

All three are provider-agnostic: you write your page once, and Inertia Start renders the correct Stripe or Paddle checkout automatically based on the active provider (shared with every page as page.props.paymentProvider). Switching providers later only means changing your billing environment variables — your page code stays the same.

The only thing that differs between Stripe and Paddle is the price IDs you pass:

• Stripe price IDs look like price_123
• Paddle price IDs look like pri_123

Before you start

Make sure you have:

1. Enabled billing and chosen a provider (see Setup).
2. Created your products and prices in the provider dashboard, and copied their price IDs.

There is nothing else to wire up on the frontend. When Paddle is the active provider, Paddle.js is loaded for you automatically — you never add a script tag yourself.

Show a checkout button

The fastest way to charge a customer: drop a CheckoutButton anywhere and pass the ID of the price they are buying.

<script setup lang="ts">
import CheckoutButton from '@/components/billing/CheckoutButton.vue';
</script>

<template>
  <CheckoutButton prices="price_123" return-to="/billing/success">
    Subscribe
  </CheckoutButton>
</template>

<script setup lang="ts">
import CheckoutButton from '@/components/billing/CheckoutButton.vue';
</script>

<template>
  <CheckoutButton prices="pri_123" return-to="/billing/success">
    Subscribe
  </CheckoutButton>
</template>

Buying several items or quantities

prices accepts more than a single string. Use whichever shape fits your case:

<template>
  <!-- A single price -->
  <CheckoutButton prices="price_123" return-to="/billing/success">Buy</CheckoutButton>

  <!-- A single price, quantity 3 -->
  <CheckoutButton prices="price_123" :quantity="3" return-to="/billing/success">
    Buy 3 seats
  </CheckoutButton>

  <!-- Several prices at once -->
  <CheckoutButton :prices="['price_123', 'price_456']" return-to="/billing/success">
    Checkout
  </CheckoutButton>

  <!-- Several prices with explicit quantities -->
  <CheckoutButton :prices="{ price_123: 2, price_456: 1 }" return-to="/billing/success">
    Checkout
  </CheckoutButton>
</template>

Props

CheckoutButton also forwards any shadcn-vue Button props (variant, size, disabled, loading, ...) to the underlying button.

Show a full checkout section

CheckoutSection renders a complete "buy" section: product name, description and badge, a price block (with discount strikethrough, trial badge, and a loading skeleton), a feature checklist, guest-checkout copy, a CheckoutButton, and reassurance / secure-checkout notes. It's what renders the built-in product buy page and subscribe page — reach for it directly when you want that same ready-made card on your own page instead of assembling PricingCards / CheckoutButton and the surrounding copy yourself.

<script setup lang="ts">
import CheckoutSection from '@/components/billing/CheckoutSection.vue';
</script>

<template>
  <CheckoutSection
    product-name="Starter pack"
    product-description="A one-time bundle to get going."
    :price="{ amount: 1500, currencyCode: 'USD' }"
    :features="[{ name: 'Unlimited projects', included: true }]"
    :price-ids="['price_123']"
    success-url="/billing/success"
  />
</template>

If price.amount / price.currencyCode are omitted, CheckoutSection fetches them itself from priceIds (the same way PricingCards does), and if price.discountedAmount isn't provided it resolves the discount from discountId automatically.

Props

Show a pricing table

PricingCards renders a full pricing table from an array of plans. Each card shows the plan name, price, features and its own checkout button, and a billing-cycle switcher appears automatically when your plans use different cycles (for example monthly vs annually).

When you pass real provider price IDs (price_… for Stripe, pri_… for Paddle), the component fetches the live amount and currency from the provider and merges them with the metadata you define locally (name, description, features, highlight). Your local data is mostly there to describe and present each plan.

<script setup lang="ts">
import PricingCards from '@/components/billing/PricingCards.vue';
import type { Price } from '@/components/billing/PricingCards.vue';

const prices: Price[] = [
  {
    id: 'price_monthly',
    productId: 'prod_basic',
    name: 'Basic',
    amount: 1500, // $15.00, in cents
    currencyCode: 'USD',
    billingCycle: 'monthly',
    features: [
      { name: 'Unlimited projects', included: true },
      { name: 'Priority support', included: false },
    ],
  },
  {
    id: 'price_yearly',
    productId: 'prod_basic',
    name: 'Basic',
    amount: 15000, // $150.00 / year
    currencyCode: 'USD',
    billingCycle: 'annually',
    accented: true, // highlight this card
  },
];
</script>

<template>
  <PricingCards :prices="prices" success-url="/billing/success" />
</template>

<script setup lang="ts">
import PricingCards from '@/components/billing/PricingCards.vue';
import type { Price } from '@/components/billing/PricingCards.vue';

const prices: Price[] = [
  {
    id: 'pri_monthly',
    productId: 'pro_basic',
    name: 'Basic',
    amount: 1500, // 15.00, in minor units
    currencyCode: 'USD',
    billingCycle: 'monthly',
    features: [
      { name: 'Unlimited projects', included: true },
      { name: 'Priority support', included: false },
    ],
  },
  {
    id: 'pri_yearly',
    productId: 'pro_basic',
    name: 'Basic',
    amount: 15000, // 150.00 / year
    currencyCode: 'USD',
    billingCycle: 'annually',
    accented: true, // highlight this card
  },
];
</script>

<template>
  <PricingCards :prices="prices" success-url="/billing/success" />
</template>

Props

Events

Apply a discount or coupon

All three components accept a discount. Pass either a discount code (the code a customer would type) or a discount ID from your provider dashboard. If you pass both, discountId wins.

<template>
  <!-- Apply by code -->
  <CheckoutButton prices="price_123" discount-code="LAUNCH20" return-to="/billing/success">
    Subscribe
  </CheckoutButton>

  <!-- Apply by ID -->
  <CheckoutButton prices="price_123" discount-id="promo_123" return-to="/billing/success">
    Subscribe
  </CheckoutButton>
</template>

On PricingCards, discount-code / discount-id apply to every plan, and any individual Price can override them with its own discountCode / discountId.

Require consent before checkout

Sometimes you need the customer to tick a box (terms of service, immediate digital access, ...) before they can pay.

CheckoutButton, PricingCards, and the provider-specific checkout components support an optional checkout-consent slot. When the slot is present, clicking the button first opens a confirmation dialog, and every enabled checkbox inside the slot must be checked before checkout continues.

This feature is entirely slot-driven:

• If you don't pass the slot, checkout starts immediately, as usual.
• The slot accepts any content you need, including several required acknowledgements.
• It detects native checkboxes and the built-in shadcn-vue Checkbox component.

The slot receives these props:

CheckoutButton example

<script setup lang="ts">
import CheckoutButton from '@/components/billing/CheckoutButton.vue';
import { Checkbox } from '@/components/ui/checkbox';
</script>

<template>
  <CheckoutButton prices="price_123" return-to="/billing/success">
    Subscribe

    <template #checkout-consent="{ invalid, clearError }">
      <div class="flex items-start gap-3 text-sm">
        <Checkbox
          id="checkout-terms"
          :invalid="invalid"
          @update:model-value="clearError"
        />
        <label for="checkout-terms">
          I accept the terms of service and privacy policy.
        </label>
      </div>

      <div class="flex items-start gap-3 text-sm">
        <Checkbox
          id="checkout-digital-access"
          :invalid="invalid"
          @update:model-value="clearError"
        />
        <label for="checkout-digital-access">
          I acknowledge that digital access starts immediately.
        </label>
      </div>
    </template>
  </CheckoutButton>
</template>

PricingCards example

<script setup lang="ts">
import PricingCards from '@/components/billing/PricingCards.vue';
import { Checkbox } from '@/components/ui/checkbox';

const prices = [
  {
    id: 'price_123',
    productId: 'prod_basic',
    name: 'Basic',
    amount: 1500,
    currencyCode: 'USD',
    billingCycle: 'monthly',
  },
];
</script>

<template>
  <PricingCards :prices="prices" success-url="/billing/success">
    <template #checkout-consent="{ price, invalid, clearError }">
      <div class="flex items-start gap-3 text-sm">
        <Checkbox
          :id="`checkout-terms-${price.id}`"
          :invalid="invalid"
          @update:model-value="clearError"
        />
        <label :for="`checkout-terms-${price.id}`">
          I accept the purchase terms for {{ price.name }}.
        </label>
      </div>
    </template>
  </PricingCards>
</template>

With PricingCards, the checkout-consent slot is applied to the default checkout CTA of each price. If you replace the CTA with a custom #cta slot, render your own CheckoutButton there and pass the same checkout-consent slot to it.

Customize the validation message

When the customer tries to continue with a required checkbox left unchecked, the dialog shows a validation message. By default, this is the billing.checkout_legal.acceptance_error translation ("Check all boxes before continuing.").

Pass checkout-consent-error-text to CheckoutButton or PricingCards to override it with your own message:

<template>
  <CheckoutButton
    prices="price_123"
    return-to="/billing/success"
    checkout-consent-error-text="Please accept all terms before subscribing."
  >
    Subscribe

    <template #checkout-consent="{ invalid, clearError }">
      <!-- consent checkboxes -->
    </template>
  </CheckoutButton>
</template>

The same prop works on PricingCards, where it applies to every plan's consent dialog. Leave it unset (or pass an empty string) to keep the default localized message.

Going further

Provider-specific components

The provider-agnostic components above cover almost every case. For advanced integrations you can use the provider-specific components directly:

• StripePricingCards.vue
• PaddlePricingCards.vue
• StripeCheckoutButton.vue
• PaddleCheckoutButton.vue

BasePricingCards

BasePricingCards.vue (in resources/js/components/billing) is the shared visual pricing-card UI. It does not perform any provider API request or checkout action on its own. Prefer PricingCards in your pages unless you are building a custom provider-specific component.

Create a checkout session from your backend

The billing components already use the built-in routes and API endpoints to create checkout sessions, so you rarely need to do this yourself. But if you want custom behavior (per-campaign provider forcing, A/B experiments, dedicated private endpoints, ...), call BillingService::createCheckoutSession() directly.

Using the resolved payment provider (user-pinned when authenticated, otherwise the default):

<?php

use App\Services\BillingService;

$checkout = BillingService::createCheckoutSession(
    $request->user(),
    $prices,
    $quantity,
    route('checkout.complete')
);

Overriding the provider and applying a discount:

<?php

use App\Services\BillingService;

$checkout = BillingService::createCheckoutSession(
    $request->user(),
    $prices,
    $quantity,
    route('checkout.complete'),
    [
        'provider' => $provider,                  // force a specific enabled provider
        'discount_code' => $discountCode,
        'discount_id' => $discountId,             // takes precedence over discount_code
        'subscription_type' => $subscriptionType, // start a recurring subscription of this type
        'customer_email' => $email,               // pre-fill / match a guest by email
        'embedded' => true,                       // Stripe embedded checkout (returns a client_secret)
    ]
);

Pass subscription_type (a configured subscription slug) to start a recurring subscription instead of a one-time charge. The price must belong to that subscription group, or the call returns 404.

The returned payload shape is provider-specific:

• Stripe returns a redirect url (send the customer there) — or, when embedded is true, a client_secret to mount embedded checkout.
• Paddle returns transaction, items, and customer data for Paddle.js to open the overlay.

Routes and API endpoints

You normally interact with billing through the components above, but the underlying routes are available if you need them.

Web routes

• GET /billing/checkout (billing.checkout): redirect to checkout for the resolved provider (user-pinned provider when authenticated, otherwise the active/default provider).
• GET /billing/portal (billing.portal): redirect to the resolved Stripe/Paddle customer portal.
• GET /buy/{product} (billing.products.buy): the product buy page / checkout for a configured product.
• GET /subscribe/{subscription}/{plan} (billing.subscriptions.subscribe): the subscribe page / checkout for a configured plan.
• GET /billing/thank-you (billing.thank-you): the thank-you page customers return to after checkout.

The account billing page lives under /account/billing (authenticated users):

• GET /account/billing (account.billing.index): the account billing page.
• POST /account/billing/subscription (account.billing.subscription.update): switch to another plan in a group.
• POST /account/billing/subscription/cancel (account.billing.subscription.cancel): cancel a subscription.
• POST /account/billing/subscription/cancel-pending-change (account.billing.subscription.cancel-pending-change): void a pending Stripe plan change.
• POST /account/billing/subscription/resume (account.billing.subscription.resume): resume a subscription scheduled to cancel.

API routes

Billing API routes live under /api/billing:

• Public:
  • POST /api/billing/checkout/init (api.billing.checkout.init) — create a checkout session. Accepts an optional email (used to match/create a guest account) and an embedded flag for Stripe embedded checkout.
  • GET /api/billing/prices (api.billing.prices.index) — list prices for the resolved provider.
  • GET /api/billing/discounts (api.billing.discounts.index) — look up a single discount by discount_id or discount_code.
• Authenticated users:
  • POST /api/billing/portal (api.billing.portal) — get the customer portal URL.
  • GET /api/billing/customer (api.billing.customer) — get the current customer payload.
  • POST /api/billing/subscriptions/sync (api.billing.subscriptions.sync) — refresh the user's subscriptions from the provider and return the account billing data.
  • GET /api/billing/history (api.billing.history.index) — cursor-paginated billing history (cursor, per_page 1–25).
  • GET /api/billing/invoices/{invoice}/open (api.billing.invoices.open) — redirect to a hosted invoice, PDF, or receipt (document, disposition), after checking ownership.
  • GET /api/billing/payments/{session}/receipt (api.billing.payments.receipt) — redirect to a Stripe one-time payment receipt, after checking ownership.
  • GET /api/billing/information (api.billing.information.show) — the customer's billing information.
  • GET /api/billing/payment-methods (api.billing.payment-methods.index) — the customer's saved payment methods.
• Authenticated admins only:
  • GET /api/billing/products/all (api.billing.products.all)
  • GET /api/billing/discounts/all (api.billing.discounts.all)
  • GET /api/billing/prices/all (api.billing.prices.all)

The no-code config editors add admin-only web routes too: GET/PUT /admin/billing/products (admin.billing.products / .update) and GET/PUT /admin/billing/subscriptions (admin.billing.subscriptions / .update).

Provider resolution rules:

• Built-in checkout, customer, portal, history, information, and payment-methods endpoints resolve by user billing history when authenticated, otherwise they use the configured default provider.
• Public/admin catalog endpoints (prices, discounts, products/all, discounts/all, prices/all) use the active/default provider from I_S_DEFAULT_PAYMENT_PROVIDER.
• Provider-specific webhook routes are registered only for providers enabled through I_S_ENABLED_PAYMENT_PROVIDERS (plus the default provider).

Types and interfaces