Skip to main content

Tiers and pricing

Define your tiers in config/billing.php:

// your published config/billing.php
'tiers' => [
'free' => ['label' => 'Free'],
'pro' => [
'label' => 'Pro',
'provider_price' => env('BILLING_PRICE_PRO'), // the active provider's price reference
'price_display' => ['amount' => 1900, 'currency' => 'EUR'],
'interval' => 'month',
],
],

A tier may carry 'byok' => true — a "bring your own keys" tier, where the customer runs on their own provider credentials rather than being metered and billed the usual way. The package exposes it through Entitlements::isByok() / app(TierCatalog::class)->isByok($key); your app reads that flag to route a BYOK owner around its own metering/server-key path. The package itself holds no server-side execution key, so it never puts a BYOK owner on a metered server path — that boundary lives in your app, and isByok() is the seam it reads. BYOK is orthogonal to payment method: a BYOK tier can still be a paid subscription.

Each paid tier's provider_price is the active provider's price reference — provider-neutral, not hardcoded to one provider. It may be declared two ways:

  • a scalar string — one price for whichever driver is active (the single-provider common case). On Stripe that string is a Stripe price id (price_...); create the product and its recurring price in the Stripe dashboard or via the API, then put the id in .env.
  • a per-provider map — ['stripe' => 'price_...'], so one tier config carries the right id for each driver; the active driver is billing.default unless a provider is named.
BILLING_PRICE_PRO=price_...

A tier whose provider_price is empty (or a map with no entry for the active provider) cannot be checked out — it resolves to null and the tier is treated as not purchasable on that provider, never charged at a wrong price. That resolution is the anti-price-injection allowlist: the client submits a tier key, and the ProviderPriceResolver maps it to a price only config declares, so a price id can never be smuggled in from the request. Read a resolved id with app(ProviderPriceResolver::class)->forTier($key) / forAddon($key).

One tier, monthly and yearly​

A tier may be sold at more than one interval under its one key. Its own provider_price, price_display and legacy_prices sell it at its interval, and each entry under intervals, keyed by another interval, sells the same tier at that one with keys of the same names:

'pro' => [
'label' => 'Pro',
'provider_price' => env('BILLING_PRICE_PRO'),
'price_display' => ['amount' => 1900, 'currency' => 'EUR'],
'interval' => 'month',
'intervals' => [
'year' => [
'provider_price' => env('BILLING_PRICE_PRO_YEARLY'),
'price_display' => ['amount' => 19000, 'currency' => 'EUR'],
],
],
],

The tier is the same at either price. Its entitlements, label, rank and feature bullets don't depend on the interval, and a subscription at the yearly price resolves to pro like one at the monthly price. A checkout and a swap name the interval, and without one they sell the tier's own:

use Pushery\Billing\Contracts\Checkout;
use Pushery\Billing\Contracts\SubscriptionActions;
use Pushery\Billing\Enums\BillingInterval;

app(Checkout::class)->subscribe($user, 'pro', interval: BillingInterval::Year);

app(SubscriptionActions::class)->swap($user, 'pro', interval: BillingInterval::Year); // the same tier, yearly
app(SubscriptionActions::class)->swap($user, 'team'); // stays yearly where `team` is sold yearly

A swap that names no interval keeps the one the subscription is billed at where the new tier is sold at it, and takes the new tier's own interval otherwise. app(PlanCatalog::class)->intervalsFor($key) lists the intervals a tier is sold at, its own first, and planFor($key, $interval) and providerPriceFor($key, $interval) answer for each.

To show what a change costs before the customer makes it, ask PreviewsSwaps with the arguments you then pass to swap(). It prices the change the swap makes, the interval a swap keeps included, and answers the amount the invoice after the change asks the customer to pay, or null where the swap would be refused or the provider gives no answer. The Stripe driver binds it; the package's own engine and Shopify bind nothing, so ask the container first:

use Pushery\Billing\Contracts\PreviewsSwaps;

if (app()->bound(PreviewsSwaps::class)) {
$due = app(PreviewsSwaps::class)->previewSwap($user, 'team'); // a Money, or null
}

The subscription row keeps the interval Stripe's webhook reports, in billing_interval, and what describes the subscription reads the plan at it: the contract confirmation states the yearly price and period, the subscription overview names them, and the MRR counts a twelfth of the yearly price. The text beside the order button states the price of one billing period, so a tier sold at more than one interval gives it a text for each (see Subscriptions).

Stripe sells a tier at every interval it is configured at. Shopify and the package's own billing engine, which bills the Mollie subscriptions, bill a tier at its own interval and refuse another with an InvalidArgumentException. php artisan billing:doctor holds the Stripe price of every interval against its displayed amount and interval.

One pricing source​

For a pricing surface your application builds — a public /pricing page, or an upgrade grid of its own — PricingCatalog::cards() and upgradeCards($currentKey) are one config-authoritative source, so two such surfaces can never promise different things. The account hub's plan list reads each plan's label and price from the same tier catalog and shows no bullets, highlight or badge. A tier's feature bullets live in config as an ordered list of translation keys (your app owns the strings, in every locale); an optional highlight/badge emphasizes a card:

'pro' => [
'label' => 'Pro', /* … price as above … */
'features' => ['pricing.pro.projects', 'pricing.pro.priority_support'], // i18n KEYS, never raw text
'highlight' => true,
'badge' => 'pricing.badge.popular',
],

app(PricingCatalog::class)->bulletsFor($tierKey) resolves those keys to the current locale, in order. Because the bullets come only from config, two surfaces that render them cannot drift.

Resolving a billable to its tier​

TierResolver maps a billable to its tier. With Stripe the package binds ColumnTierResolver by default — it reads the denormalized plan column (billing.tier_column), which the Stripe webhooks keep current. With Mollie it binds SubscriptionTierResolver, which reads the tier off the subscription row, because nothing on the local engine writes that column. The account hub asks the same resolver. If your app runs Stripe and does not keep a tier column, rebind it to SubscriptionTierResolver in one line:

// A service provider
$this->app->bind(
Pushery\Billing\Contracts\TierResolver::class,
Pushery\Billing\Resolvers\SubscriptionTierResolver::class,
);

Grandfathering is handled through per-tier legacy_prices; a multi-item subscription is handled too (the tier item is resolved by price, foreign items untouched).

The catalog services​

The tier, add-on and pricing surfaces are read through config-authoritative catalog services — resolve them from the container and use them out of the box; the config is the single source they read, so nothing drifts.

  • PricingCatalog — the shared source for the pricing surfaces your application builds, a public /pricing page and an upgrade grid of its own. tiers() / purchasable() list the catalog; cards() and upgradeCards($currentKey) build the render-ready cards; bulletsFor($key) resolves a tier's feature bullets to the current locale. Surfaces that read the one source can never promise different things.
  • TierCatalog (contract; ConfigTierCatalog by default) — all(), find($key), label($key), priceDisplay($key), and the flags isByok($key) / isUntouchable($key).
  • ConfigAddonCatalog — all(), exists($key), label($key), priceFor($key), providerPriceFor($key), and grantsFor($key) for a prepaid-unit add-on (see Usage-based billing). Unlike the tier and plan catalogs it is a concrete class, not a contract, so extend it by binding your own subclass rather than rebinding an interface.

Use them as-is for the common case; extend by rebinding the contract when you need catalog data from somewhere other than config (a database of tiers, say). Rebind TierCatalog (or PlanCatalog) to your own implementation the same way TierResolver is rebound above — every package surface then reads your catalog, and your pricing surfaces stay in lockstep because they still go through PricingCatalog.

Feature bullets, without drift​

A tier's feature bullets are the features block of i18n keys shown above — never raw strings. The keys resolve through the translation namespace, so the same bullet renders in every locale, and every surface that shows them shows the same list, because each calls PricingCatalog::bulletsFor(). To change a bullet you edit the config key order or the translation, never two copies of the text. See i18n and translations for overriding those strings and the register they must keep.

A bullet whose number follows from your own limits, a count of translations a month worked out from a budget, belongs in code rather than in a translation. Bind Pushery\Billing\Contracts\FeatureBullets and answer each tier's bullets yourself; PricingCatalog then asks your implementation for every card, the full set and the upgrade grid alike, and a changed limit changes the bullet without anybody editing a translation:

use Pushery\Billing\Contracts\FeatureBullets;

final class LimitBullets implements FeatureBullets
{
public function forTier(string $tierKey): array
{
$budget = config("plans.{$tierKey}.monthly_budget", 0);

return [__('pricing.translations', ['count' => intdiv($budget, 150)])];
}
}

// in a service provider
$this->app->bind(FeatureBullets::class, LimitBullets::class);

Each bullet is a finished string in the current locale. Without a binding the configured keys answer as above.


← Back to the documentation index