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 isbilling.defaultunless 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/pricingpage and an upgrade grid of its own.tiers()/purchasable()list the catalog;cards()andupgradeCards($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;ConfigTierCatalogby default) —all(),find($key),label($key),priceDisplay($key), and the flagsisByok($key)/isUntouchable($key).ConfigAddonCatalog—all(),exists($key),label($key),priceFor($key),providerPriceFor($key), andgrantsFor($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.