Skip to main content

Subscriptions

A visitor becomes a subscriber from the /plan screen. The client submits the tier key only — the price is resolved server-side (anti-price-injection) — and the package opens a hosted Checkout Session in subscription mode. The trial, provider tax and VAT-id collection, promotion codes and the billing address all ride on that session, and the card is captured (with SCA / 3-D Secure) on the provider's own page. On return, /checkout/return reconciles the subscription onto the local row immediately, so a paying customer is never shown "Free" while the webhook is still in flight. An owner who already subscribes swaps in-app instead of opening a second subscription.

The return URLs default to the hub's own routes; set billing.checkout.success_url / cancel_url only to override them. Set billing.customer.model to your billable model — without it, no subscription webhook can find its owner.

The submit button of that session says "Subscribe", Stripe's choice for a subscription. Where consumers in Germany subscribe, set billing.checkout.submit_type to pay, and it says "Buy": § 312j Abs. 3 BGB asks for an order button that names the obligation to pay, and "Subscribe" names none. An add-on purchase needs nothing, its button says "Buy" already.

Beside that button the session can show a text of yours. billing.checkout.submit_message.tiers maps a tier key to it, as a translation key read in the locale of the request that opens the checkout or as the text itself, and billing.checkout.submit_message.addons does the same for the purchase of an add-on. Where consumers in Germany buy, the text names the essential features, the price per billing period, the term and how to cancel: § 312j Abs. 2 BGB asks for them immediately before the order, and on a hosted checkout that moment is on Stripe's page. Stripe shows up to 1200 characters. To word the text in code, for example in a language the billable carries, bind Pushery\Billing\Contracts\OrderButtonText.

A tier sold at more than one interval (One tier, monthly and yearly) costs a different total per billing period at each, so its entry is a list keyed by interval, one text for each:

'submit_message' => ['tiers' => ['pro' => [
'month' => 'checkout.pro_monthly',
'year' => 'checkout.pro_yearly',
]]],

A single text is the tier's at its own interval, and a checkout at another interval shows no text rather than the price of a different billing period.

When the first real charge lands​

On a driver the package bills itself, each subscription records when its periods are collected, and billing.collection_timing decides it for every new one. The default is in_advance: a period is paid when it begins. The payment taken at checkout is not a plan payment under either timing. It exists to establish the mandate, and billing.mandate_verification_minor sets it, defaulting to one minor unit (0.01 in the account currency).

PlanFirst real charge, in_advanceFirst real charge, in_arrears
Monthly, no trialat the next billing:run, within the hourafter 30 days
Monthly, 14-day trialwhen the trial endsafter 44 days
Yearly, no trialat the next billing:run, within the hourafter 365 days

In advance, the first period is charged right after the mandate exists, or when the trial ends, and each later period at the moment the one before it ends. The invoice is raised when the payment arrives and names the period it pays for.

In arrears, an order closes the period it is for, so the charge happens at the end of a cycle rather than at its start. A year of service is delivered before anything beyond that one minor unit has been collected, and the trial adds its own length on top rather than overlapping. If you choose it, the lever that keeps the wait short is the period length: a yearly price billed monthly carries the same annual sum with thirty days of exposure instead of three hundred and sixty-five.

Each subscription keeps the timing it started with. One started before the setting existed is collected in arrears, and changing the setting reaches new subscriptions only: switching a running one would collect the period in progress twice, once as the bill that closes it and once as the payment for the next.

Swaps, cancel, resume, trials​

  • In-app upgrade/downgrade swap with a proration preview; an upgrade takes effect immediately, a downgrade is scheduled to the current period end so the customer is never charged twice or refunded for time they already paid. On a driver the package bills itself, what a swap moves depends on when the subscription is collected. Collected in advance, the period was paid at the old tier, so a swap that takes effect at once squares the time left: a dearer tier is charged for it right away, as an order of its own with its own invoice, and a cheaper one leaves the difference as credit that the next payments spend first. Nothing is paid out. Each tier is valued over its own interval, so a monthly tier changed for a yearly one costs a twelfth of the yearly price for a month, and from the period end the new tier is billed over its own interval. Where a step of billing.order_item_preprocessors or a line's own resolver sets the amount of a tier, the time left is valued at those amounts, not at the catalog price: the tier in force at what the period's payment charged for its subscription and usage lines, the new one at what its next cycle charges for them. A cheaper tier gives back no more than the period's payments hold for the time left, the period's own and every charge a dearer tier made for the rest of it, less what an earlier change gave back already, and each payment's share names its own invoice as the source of the credit. A charge the provider refuses does not undo the change: it stays open and is collected after the next paid cycle. Collected in arrears, nothing is paid for the period in progress, so a swap moves no balance: the cycle that closes the period charges each tier for the days it held, each at its own rate where the two are sold at different intervals, and the preview shows what the swap adds to that bill or takes off it. Under both timings, a downgrade scheduled to the period end is charged at the new tier from the first day of the next period, even when the run that applies it comes later. A seat change with proration follows the same rule as a swap. On Stripe, a swap that changes the billing interval is charged at once, and where Stripe charges a card or Link for the subscription the change waits for that payment: a declined card, or a payment the bank still has to confirm, leaves the subscription on its tier, and Stripe drops the change within a day if the invoice stays unpaid. A SEPA Direct Debit, or a subscription whose invoices are sent to be paid, takes the change at once, as Stripe does by default.

    billing:run applies a downgrade scheduled to the period end without asking CanTransactMoney again. The account screen asked it when the customer made the change, and at the due date nobody is acting, so a gate that needs an acting person would refuse every scheduled change. A subscription that ends or is terminated before the date drops its change, and so does a deleted owner. If your application blocks an account in a way of its own, drop the pending change with $subscription->cancelScheduledSwap().

    Stripe renews a subscription at the moment its period ends, so a change applied after that moment would come after an invoice for another period of the old tier. Under Stripe, billing:run therefore arranges a change scheduled to the period end three days before it comes due, as a phase of a subscription schedule, and Stripe makes the change at the boundary. When it comes due, billing:run only clears it from the row. A consumer who moves to a yearly price goes on at the tier's monthly price after that year, as an annual subscription after its first year describes. Changing or dropping the scheduled change takes the arrangement off again. A change Stripe refuses is tried again the next day, and one it never takes, one on an ending subscription and one made too close to the boundary for a run to arrange it first are applied when they come due, as before.

    Where a tier is sold at more than one interval (One tier, monthly and yearly), the plan screen offers the billing period above the plans and prices each plan at the one chosen; a tier not sold at it is shown at its own. Until the customer chooses, the screen preselects the period the subscription is billed at where the driver keeps it on a swap, as Stripe does, so a yearly subscriber sees, previews and swaps to the yearly prices. The tier the customer holds appears at the chosen period too, as a change of the billing period alone. A longer period is paid in advance at once, as an upgrade is, and a shorter one waits for the period already paid for, as a downgrade does: a yearly subscriber who chooses the monthly price keeps the year, and the scheduled change carries the interval, which billing:run applies with the tier. A change of tier goes by the tier's rank whatever the period does. Shopify and the package's own billing engine sell a tier at its own interval and refuse another.

    A driver whose capabilities report supportsInPlaceSubscriptionChanges as false changes no subscription itself, and Shopify's is one: there the plan screen opens the checkout for every change, schedules none, and the grace period offers the plans instead of a resume. Billing through Shopify has the details.

  • Cancel-into-grace (paid through the period end), resume, and immediate cancel from the danger zone. On a driver the package bills itself and a subscription collected in advance, the period is paid already, so a cancellation lets it run out and the subscription ends at the period end, and the immediate cancel ends it at the next billing:run. Collected in arrears, a period is collected at its end, so a cancellation keeps that last cycle: it bills the period and then ends the subscription. The immediate cancel keeps it too, brought forward to the moment the customer asked: the next billing:run bills the days of the period they already had, and until then the subscription cannot be replaced by a new one. The danger zone asks for that through EndsNowOnTheOwnersRequest::endNow(). SubscriptionActions::cancelNow() bills nothing more, and it is what account deletion, a withdrawal and a reversed sale use. A screen of your own that lets customers end their subscription at once calls endNow() where the bound actions implement EndsNowOnTheOwnersRequest, as the danger zone does.

  • Pause and resume. Where the bound actions implement PausesSubscriptions, as both shipped drivers do, pause() lets an active subscription that is not ending rest: nothing is collected, and it grants no access until unpause() takes it up again. On a driver the package bills itself, the time the pause took is added to the period the subscription is in, so the days that were paid, or would have been billed, are still there afterwards, and a cancellation while it rests ends it at once. A plan change waits there until the subscription goes on: swap() refuses one with SwapRefusedWhilePaused, and a change scheduled before the pause moves with the period. On Stripe the pause is pause_collection with void, and Stripe keeps its own periods. On either driver the subscription screen offers no plan change while a subscription rests and says why. SubscriptionPaused and SubscriptionUnpaused are dispatched for a lock or a notice of your own.

  • Cancel to a date, with the rest of the period paid back. ProratedCancellation ends a subscription at a moment inside the period it is in and refunds what was paid for the time after it, through the same refund path as every other refund, recorded as RefundKind::UnusedPrepaidPeriod. It answers a renewed consumer contract that may be canceled at a month's notice: on a yearly plan that end falls inside a paid year, and canceling at the period end would hold the customer up to eleven months too long. GermanNoticePeriod::earliestEnd() says when such a contract ends under § 309 Nr. 9 BGB, from when the cancellation arrived and when the initial term ends:

    use Pushery\Billing\Consumer\GermanNoticePeriod;
    use Pushery\Billing\Consumer\ProratedCancellation;

    $endsAt = GermanNoticePeriod::earliestEnd(now('Europe/Berlin'), $initialTermEndsAt);

    $quote = app(ProratedCancellation::class)->quote($user, $endsAt); // the end and the refund, to confirm
    $settlement = app(ProratedCancellation::class)->cancel($user, $endsAt); // ends it there and refunds the rest

    The initial term comes from you, because the package does not store what a subscription was sold as. GermanNoticePeriod counts the month the way the law does: the day the cancellation arrives does not count, and one arriving on 31 January ends with the last day of February. It answers for terms that ask for the full month the law allows; a shorter notice ends earlier.

    A date at or after the period end ends the subscription at the period end, with nothing refunded, and $settlement->endsAt names the end that applies, in UTC whatever zone the date came in, so format it in the zone you show it in. A cancellation to a date inside the period is final: resume() refuses it and the account screen offers no resume button, because the rest of the period may have been refunded. On a driver the package bills itself, a subscription collected in advance is refunded from the order that paid the period, as on Stripe. One collected in arrears has nothing paid for the period in progress, so nothing goes back: the last cycle runs at the date instead and bills the days up to it, the same amount a prepaid customer keeps paying after the refund. A provider that refuses the refund leaves the end in place; the settlement then says refundRefused and names the payment, which is what a second attempt through BillingAdmin::refund() needs.

  • Trials — none / subscription / generic, global or per-tier, card required or if_required; a trial-ending reminder goes out before the trial lapses, and it reaches every trial whatever drives it. Which path delivers it depends on whether the provider announces trial ends at all: a driver that does sends its own event, and billing:trials:warn covers the rest — a generic trial, which has no provider behind it, and a subscription trial under a driver whose cycle this package runs itself. Nothing at such a provider knows a trial is running, so nothing there can say it is ending. Both paths record the same notice, so a customer is told once. Where the bound UpcomingInvoice previews the charge that follows, the reminder names its amount and the day it is collected, and that the customer can cancel before then: the next invoice the driver previews, coupon included, less the credit the cycle spends on it first. On the package's own engine that is the first charge after the trial: collected in advance it falls on the day the trial ends, collected in arrears at the end of the first paid period. Without a preview, or where the credit covers the whole invoice, it names no figure.

    The mode without a card is the one where that matters most: there is no failed charge and no receipt to notice, so the reminder is the only signal before the first debit.

  • A canceled subscription is announced again before it ends. The cancellation notice goes out when the owner cancels; billing:subscriptions:warn reminds them once more within billing.subscriptions.warn_ending_within_days (3 by default) of the end, while resuming still keeps the plan without a gap. Once per subscription and end: resuming and canceling again ends on another day and is reminded again. The reminder of the platform's own subscription names the tier the account moves to otherwise, the one billing.zero_tier names. A subscription held with a merchant is reminded under the merchant's name and without a button, since the hub's subscription screen shows the platform's own.

    The reminder, the trial-ending reminder and the cancellation notice name the day in UTC, the zone the package stores every moment in. Bind OwnerTimezone to an answer with the owner's zone, and they name the owner's day (Contracts).

  • A subscription trial is granted once per customer. Not once per subscription — the eligibility is read from their own billing history, so somebody who cancels and comes back subscribes at the full price. The plan screen offers the trial only to a customer who would actually be granted one, so the page and the checkout never disagree. A generic trial follows the same rule through the customer's own trial date.

  • The days a trial covers carry no plan charge, and the document says so at zero. Under a driver whose cycle this package runs itself and a subscription collected in advance, the trial is never charged at all: the run at its end charges the first paid period. Collected in arrears, an order names the period it closes — the cycle that ends a trial therefore names the trial's own days. That period is billed with the recurring plan line priced at zero, so the invoice states which days were free and what they were free of, rather than leaving no record of them. The first plan charge is the cycle after it.

    Metered usage and add-ons are not part of the waiver. A free trial is an offer about the recurring charge; consumption an application priced for those days is still billed on the same document. The distinction is the line type, so a CycleItemPricer that expresses a plan as several fixed lines is covered, and a metered line beside them is not.

    The waiver runs after the order-item preprocessor chain: a step may reprice the plan for an ordinary cycle, and may not reprice a period the plan screen promised for free. It runs before the coupon, so a customer does not spend one of their discounted cycles on a cycle nobody charged them for.

    One consequence to know if you listen for payments. In arrears the cycle still closes, so it still dispatches PaymentSucceeded — with an amount of zero and no provider reference, because nothing was collected. A listener that mails a receipt on that event will mail a zero receipt at every trial end unless it checks the amount. The event is not suppressed on purpose: a cycle that a customer's credit balance covers in full behaves the same way, and a listener that has to handle one already handles the other.

Moving the end of a trial​

Where your application lets an operator change the end of a customer's trial, move the subscription's trial with it, so the first charge follows:

use Pushery\Billing\Contracts\MovesTheTrialEnd;

app(MovesTheTrialEnd::class)->moveTheTrialEnd($owner, now()->addDays(30));

The end of the trial, the end of its period and the first run move together, so the run that charges the first paid period, or closes the free one in arrears, comes at the new end, and the reminder before the end of a trial names the new day. A subscription that is not in its trial, one whose first run is already due, and a moment that is not ahead of now are refused with a TrialEndNotMovable, whose reason is no_trial or not_ahead, and nothing moves. The optional merchant scope and contract type address the subscription as they do on SubscriptionActions. A direct debit announced for the old day is drawn no earlier than its notice allows. On Stripe the trial runs at Stripe and the contract is not bound, so ask the container with app()->bound(MovesTheTrialEnd::class) before you offer it.

Who you sell to​

Set billing.audience once, through BILLING_AUDIENCE. It decides whether any consumer rule applies.

  • business_and_consumer, the default: each customer declares at checkout whether they buy as a consumer or as a business, and one who declares nothing is a consumer.
  • business_only: every customer is treated as a business. The checkout asks no customer type, the consumer-rights regime stays off whatever consumer_rights.profile names, and an annual subscription renews for another year. A consumer who signs up anyway is treated as a business too. That holds where your application states the restriction clearly and has it confirmed at the order button, so record that confirmation as the declaration below.

Record what the customer confirmed before you send them to the provider, in your own wording:

use Pushery\Billing\Consumer\CustomerDeclarations;
use Pushery\Billing\ValueObjects\CustomerStatement;

app(CustomerDeclarations::class)->declare($user, CustomerStatement::business(
statement: 'I order as a business and not as a consumer.',
businessName: 'Acme GmbH',
businessAddress: 'Hauptstraße 1, 10115 Berlin',
vatId: 'DE123456789',
));

CustomerStatement::consumer() takes the wording a consumer confirmed. A business gives its name and address, and its VAT number where it has one, which the bound VatIdValidator checks on the spot; an unavailable register is kept as unavailable and does not stop the declaration. Each declaration is a row of its own, and the latest is the one in force: CustomerDeclarations::current() reads it and history() reads all of them. Under business_only a consumer declaration is refused.

app(CustomerTypes::class)->of($user) answers which the customer is: a business under business_only, otherwise what they declared last, then what an IdentifiesBusinessBuyers of your own says, and a consumer where nothing answers. The package binds IdentifiesBusinessBuyers to DeclaredBusinessBuyers, so an offer only businesses may buy is shown to the customers who declared themselves one. A subscription freezes the answer as customer_type when its first event arrives, so a declaration made later does not change how a year that is already running goes on.

An annual subscription after its first year​

A consumer may not be held to a further year by staying silent, so their annual subscription goes on month by month once the year they bought ends, at the tier's monthly price. A business's renews for another year. Sell the tier monthly and yearly under one key, as tiers describes, so the monthly price is there to go on at; a tier sold to a consumer only yearly has none, billing:doctor names it, and the log says so when such a year renews as a year. A trial is not the year: the year begins where the trial ends, and until then nothing is arranged, the plan screen names no term and no reminder goes out.

Under Stripe the package arranges this as soon as the subscription begins, with a subscription schedule: the year as it stands, then the monthly price, after which the schedule lets go. Stripe moves the subscription at the moment the year ends, so it never raises an invoice for a second year. A discount on the annual price does not carry into the monthly continuation. Canceling, resuming, pausing and changing the plan take the schedule off first, and the next event arranges the year again where it still applies. A subscription a buyer holds at a merchant goes on at the monthly price of the merchant's tier, and every phase keeps its tax and where its money goes. One an application starts on a merchant's own account, with direct charges of its own, is not arranged. A subscription that carries a second item, such as a metered component, is not arranged, and the log names it; billing:doctor names a tier sold yearly to consumers with a metered component, since none of its years would go on monthly. The package's own billing engine, which bills under Mollie, needs no schedule: the run that closes a consumer's year opens a month at the tier's monthly price instead of another year, and the row keeps billing_interval at month for every period after. A trial before the year does not end it, nor does a year the customer booked a further year for. A subscription the engine bills from lines of its own renews as a year, and the log names it. A change of tier while the year goes on month by month keeps the month: the new tier goes on at its monthly price, the days of the month are squared at the two tiers' monthly prices, and the plan screen names each tier at that monthly price. Shopify sells to businesses.

A subscription that began before your terms named a monthly price goes on at a twelfth of the price of its year, rounded down, rather than at the tier's monthly price: a higher price the customer agreed to only by staying silent would not bind them. The package tells the two apart by monthly_terms_at on the subscription row, which every subscription that begins from this version on carries.

billing:annual-terms:arrange asks the driver once more about every consumer's running annual term and arranges each one that nothing going on past its period holds: a term whose arrangement never finished, and one a schedule holds with its year alone. Under Stripe that is every consumer's annual subscription the package arranged under 0.53.0 to 0.56.x, because Stripe refused the later phases of those schedules, so run it once after updating from one of them. A term arranged already stays as it is, a second run changes nothing, and --dry-run names the subscriptions a run would ask about without asking. A subscription an application started on a merchant's own account is not on the platform's account, and the run names it as one it could not arrange.

For one subscription, app(AnnualTerms::class)->arrangeAgain($user, $subscription) does the same and answers the reference of the arrangement that holds the term now. canArrangeAgain() says beforehand whether it asks the driver at all, which it does for a consumer's running annual term at a provider whose driver arranges annual terms, unless the customer booked a further year after it; where it does not ask, the answer is null. A tier without a monthly price to go on at, and a term the driver could not arrange, end in a RuntimeException.

billing:annual-terms:remind, scheduled daily, dispatches the reminders an annual term is owed, once each, and your application sends the mails: AnnualTermEndingSoon 38 days before a term ends, to a consumer and to a business; MonthlyContinuationBeginsSoon 14 days before a consumer's first monthly charge; and MonthlyContinuationReminder every six months of the monthly contract after. Each carries the tier, the day, the monthly price and the plan screen's URL from BillingActionUrls, and lastCancellationDay names the last calendar day a cancellation can be declared, in the owner's time zone where OwnerTimezone names one. The lead times are not settings: they are what the reminders are owed at. Where the driver arranges no annual terms, a consumer's year renews as a year, and its reminder is the one a business gets: no monthly price, and nothing to book again.

In the last 60 days of a consumer's annual term, AnnualTerms offers a further year, once, as the customer's express order. Show the offer where offersFurtherYear() answers true, and book it with the wording the customer confirmed:

use Pushery\Billing\Consumer\AnnualTerms;

$terms = app(AnnualTerms::class);

if ($terms->offersFurtherYear($user, $subscription)) {
$terms->bookFurtherYear($user, $subscription, 'I book a further year of Pro at €190.00.');
}

The year is arranged between the year that is running and the month that follows it, and the order is written to the audit log with its wording and the term it extends; the reminders pass over that term. A subscription that began before your terms named a monthly price can also choose the tier's monthly price instead of the twelfth, until its year ends, through offersMonthlyPrice() and chooseMonthlyPrice(), which take the customer's wording the same way. Both refuse with an InvalidArgumentException where they are not offered, and neither is offered on a driver that arranges no annual terms.

The plan screen shows the same to a consumer whose year the driver arranges: the day the term ends and the price it goes on at, or a twelfth of the year for a subscription that began before your terms named a monthly price. In the last 60 days it offers the further year as a box the customer ticks before pressing the button. The screen writes that wording in the customer's language, with the tier, the price of its year and the year it runs, and the audit log records it as the order. It states only prices the tiers show, so a tier sold yearly to consumers needs a display price for its month and its year to appear there.

The cancellation button​

Where consumers in Germany conclude a subscription on your website, § 312k BGB asks for a cancellation button: a declaration anybody can make from your pages, signed in or not, kept with the moment it arrived and confirmed in text form. Your application draws the two buttons, the confirmation page and the receipt. CancellationButton takes the declaration in, and the order it works in is the point: the declaration is written first, because the row is the receipt; the contract is ended second, and nothing that happens there takes the receipt back; the confirmation goes last, so it can say when the contract ends.

use Pushery\Billing\Consumer\CancellationButton;
use Pushery\Billing\Contracts\ListsContracts;
use Pushery\Billing\Enums\CancellationKind;
use Pushery\Billing\ValueObjects\DeclaredCancellation;

// The contracts the page offers a signed-in person: a key for the option value and a name for the label.
$contracts = app(ListsContracts::class)->contractsOf($user);

$declaration = app(CancellationButton::class)->declare(new DeclaredCancellation(
kind: CancellationKind::Ordinary,
name: $name,
email: $email,
contract: $contractAsChosen,
confirmationEmail: $confirmationEmail,
contractKey: $chosenKey,
), owner: $user);

ListsContracts is the one thing your application supplies. The package binds RunningSubscriptions, which offers every running subscription of the person that is not already ending, named after its tier, and reads the initial term as one period of the tier from the day the subscription started. Bind your own to name your contracts, to leave some out, or to state an initial term you sold differently. A declaration made without signing in passes no owner and names its contract in free text.

What is carried out at once. A signed-in person naming one of their own running contracts and declaring an ordinary cancellation at the earliest possible date: the package works out the earliest end with GermanNoticePeriod, ends the contract there through ProratedCancellation where that falls inside the paid period and pays back the rest, and otherwise cancels at the period end. Every other declaration waits for a person, with the reason on the row in failure where something failed: a chosen date, an extraordinary cancellation, a declaration without an owner, a provider that refused. CancellationDeclaration::query()->awaitingReview() lists them, the oldest first, and CancellationButton::resolve() records that somebody dealt with one, with the end it came to. The moment it arrived never moves.

Somebody hears of it. Set billing.consumer_rights.declaration_review_address to an address of yours, and each declaration that waits for a person, through this button or the withdrawal function below, is mailed there as soon as it is clear that it waits: why it waits, the declaration line by line, and a reply goes to the person who made it. Where carrying it out failed, the reason is a sentence in the language of the mail, never the key or the exception class the row holds in failure. DeclarationFailure::sentence($declaration->failure) gives the same sentence for a page of your own, and a value the package does not know gets a general one. The admin console lists the declarations that wait and resolves them, and a back office of your own mounts that list on its own page; see Admin and support.

The wording. The confirmation mail and your receipt page say the same thing when both come from DeclarationStatement: cancellationLines() gives label and value per line, and cancellationDeclaredThrough() the sentence that quotes the button that was pressed. Write your confirmation button from the translation key billing::declarations.cancellation.button, so that sentence quotes your button. Every moment is stated in billing.consumer_rights.declaration_timezone, with the zone named. Values the person typed reach the mail as they were typed and cannot turn into a link. A DeclarationRefused names the field a declaration came without.

The confirmation of a cancellation as the person gets it: from Linen & Co, billing@shop.example, with the subject "We received your cancellation". Under the heading "Your cancellation" it confirms the cancellation with its full content and the moment it arrived, says it was declared by pressing the button "Cancel now" on Linen & Co, and lists in one block, each label in bold, the moment it was received, the kind (an ordinary cancellation), the name, the email address, the contract (Pro subscription), the requested end of the contract (at the earliest possible date) and where the confirmation went, and asks the person to keep the email as the record.

The receipt. A declaration is bound by its random token, never by its id, so a route such as /cancellation/{declaration} resolves it, and billing.consumer_rights.declaration_receipt_route makes the confirmation mail link to it. The rows are kept as business letters: an erasure unlinks them and keeps them, and billing:prune removes them with the records of an erased owner, counted from the year a declaration arrived.

The withdrawal function​

Where consumers conclude a contract on your website, § 356a BGB asks for a withdrawal function: the person gives their name, the contract and an address, presses a confirmation button, and receives a confirmation of receipt with that content and the moment it arrived. WithdrawalFunction takes the withdrawal in, and its order is the point: the declaration is kept and confirmed before anything is carried out, because neither may depend on a payment provider being reachable. A withdrawal counts from the moment it was sent, so declared_at never moves.

use Pushery\Billing\Consumer\WithdrawalFunction;
use Pushery\Billing\ValueObjects\DeclaredWithdrawal;

$declaration = app(WithdrawalFunction::class)->declare(new DeclaredWithdrawal(
name: $name,
contract: $contractAsChosen,
confirmationEmail: $confirmationEmail,
contractKey: $chosenKey,
), owner: $user);

The contracts come from the same ListsContracts as the cancellation button. A signed-in person withdrawing from one of their own contracts has it carried out at once through ConsumerWithdrawal::withdrawSubscription(), which ends the contract and refunds the period less the value of what was already provided, for the contract the person chose. A closed withdrawal window, a contract that is gone, an unreachable provider and a refund the provider refused leave the declaration for a person, with the reason in failure and the payment in charge_reference where a refund was refused. WithdrawalDeclaration::query()->awaitingReview() lists them, and WithdrawalFunction::resolve() records that somebody dealt with one.

What was already provided is kept only on the person's request. Under the de profile a withdrawal keeps the part of the period already used only where the person asked for the service to begin before the withdrawal period ran out (§ 357a Abs. 2 BGB). Without that request the whole payment of the period goes back. Take the request at your checkout as a declaration with consentedToImmediateProvision set, through PurchaseDeclarations::declare(), and pass the key it returns to subscribe() as declarationReference: the subscription carries it home, and withdrawSubscription() reads it there. The wording of the request, and of the notice that this part is owed, is yours.

The confirmation is written from DeclarationStatement::withdrawalLines() and withdrawalDeclaredThrough(), which a receipt page uses as well. Write the confirmation button from billing::declarations.withdrawal.button, so the sentence that quotes it quotes your button. The receipt, the time zone and the retention work as for the cancellation button above.

The contract confirmation​

Where consumers in Germany conclude a subscription, § 312f Abs. 2 BGB asks for a confirmation of the contract on a durable medium, at the latest before the service begins, carrying the information Art. 246a EGBGB names: your identity and address, the price and the terms, and the withdrawal notice with the model withdrawal form. Most of that is yours to word, so the package sends the confirmation with a view of yours in it:

// config/billing.php
'consumer_rights' => [
'profile' => 'de',
'contract_confirmation_view' => 'legal.contract-confirmation',
],

With a consumer profile and the view, a subscription with the platform is confirmed as it begins: on its first trialing or active state, once per subscription, since a trial is the service as much as a paid period is. The mail names the tier and the day the subscription began, repeats each declaration the buyer made before the checkout in the words they were shown, and renders your view below its button. The view gets the owner as $owner and a ContractConfirmation as $contract, with the tier, the catalog price and the interval it is charged in ($contract->interval, a BillingInterval), the start, the end of the first period, the end of a trial and the declarations, so it can state the price per billing period and the terms of the plan. The mail is Markdown, and so is the view.

The purchase of an add-on is confirmed the same way, once per purchase, with the amount paid as the price and a button to the receipts. $contract->kind says which of the two a confirmation is.

A document that belongs beside the text rather than in it, your terms in the version the buyer accepted for instance, is attached to the same mail. Bind AttachesToContractConfirmation and return the documents for a confirmation; the mail then carries them as files, for a subscription and a purchase alike, and without a binding it carries none:

use Pushery\Billing\Contracts\AttachesToContractConfirmation;
use Pushery\Billing\ValueObjects\ConfirmationDocument;
use Pushery\Billing\ValueObjects\ContractConfirmation;

final class AttachTerms implements AttachesToContractConfirmation
{
public function documentsFor(ContractConfirmation $contract, object $owner): iterable
{
yield new ConfirmationDocument('terms-of-service-2.1.html', view('legal.terms')->render(), 'text/html');
}
}

// in a service provider's register()
$this->app->bind(AttachesToContractConfirmation::class, AttachTerms::class);

The documents are asked for as the mail is built, so a queued confirmation attaches the version that is current when it goes out.

Without the view no confirmation goes out, and billing:doctor warns while a consumer profile is active. A buyer your binding of IdentifiesBusinessBuyers names a business gets none either: the rule covers consumer contracts, and a withdrawal notice sent to a business could read as an offer of a right the law does not give it.

Coupons, and what "applied" means​

The account hub has a coupon field, and the status under it answers one question: would the driver you configured actually apply this code? Not "does the code exist" — that is a different question, and answering it there would tell a customer their code took and then charge them in full.

Which catalog answers depends on who applies the discount:

Your driverWhere the code has to beWhat applies it
A hosted checkout (Stripe)billing.coupons with a stripe_coupon mapping, or a billing_coupons row with a provider_coupon_idThe provider, on its own checkout session
A driver the package bills itselfThe billing_coupons tableThe package, as a discount line on each cycle it covers

A billing.coupons entry with no stripe_coupon reaches the checkout session as nothing at all, so the hub calls it invalid. That is not a new limitation — it is the existing one, said out loud.

A live billing_coupons row resolves its code on its own, with no config entry. Where a live row and a billing.coupons entry share a code, the row answers, and its provider_coupon_id, when set, is the coupon the checkout session gets.

Under a driver the package bills itself the coupon is carried, not spent, across the redirect. The customer goes to the provider to establish a mandate; the code travels with the rest of the request and is redeemed when the mandate settles and the subscription becomes real. A customer who closes the tab has spent nothing: a coupon allows one redemption per owner, and burning it on a checkout that never finished would take it away for good.

A coupon never blocks a subscription. If it has run out, expired, or was already used by this customer in the time between the screen and the settlement, they are subscribed at full price rather than not subscribed.

A coupon for some plans only​

On a driver the package bills itself, a coupon can name the plans it discounts in plan_keys:

use Pushery\Billing\Models\Coupon;

Coupon::query()->create([
'code' => 'BASE20', 'type' => 'percent', 'value' => 20, 'duration' => 'repeating', 'duration_in_cycles' => 3,
'plan_keys' => ['base'],
]);

The discount line then takes its share only from the lines of those plans: a percentage of their gross, and a fixed amount up to it. A line priced from a subscription item belongs to the item's plan_key, and the plan line of a subscription billed by its tier belongs to the tier key. The discount line names the plans in its metadata under plan_keys, so an invoice can tell which lines it reduced. A cycle without a line of those plans gets no discount line and uses none of the coupon's cycles. Without plan_keys, or with an empty list, the coupon discounts every line, as before. A hosted checkout does not read the column: there the provider's coupon decides which prices it applies to.

A reward for bringing in a customer​

An application that rewards a customer for bringing in another one grants the reward as credit, once per referral:

use Pushery\Billing\Support\ReferralRewards;
use Pushery\Billing\ValueObjects\CreditSource;
use Pushery\Billing\ValueObjects\Money;

app(ReferralRewards::class)->grant(
$referrer, // the customer who brought the other one in
Money::of(950, 'EUR'), // the reward
CreditSource::for($subscription), // the subscription of the customer who was brought in
);

The referral is named by a record of this package, because the ledger keeps the cause of every movement as one: the subscription of the customer who was brought in is the record every paying referral has. A record of your application, whose key may be a UUID, is refused. A second grant for the same record returns null and credits nothing. The next cycles spend the reward like any other credit, after the invoice, which keeps its full price and tax. It is never paid out.

The reward is credit and not a coupon on purpose. It pays for the referral, a service the referrer renders you, and reduces the price of nothing you supply (Abschn. 10.3 Abs. 2 UStAE). A discount on a customer's own purchases, such as a welcome offer for the customer who was brought in, is a discount allowance or a coupon. How the reward is booked is in Accounting and DATEV.

A discount the next cycles use up​

A coupon takes the same share or amount off every cycle it runs for. A discount allowance is an amount instead: granted once, it is taken off the owner's next cycles before tax until nothing of it is left. The welcome discount of a customer who was brought in is the case it is built for.

use Pushery\Billing\Discounts\DiscountAllowances;
use Pushery\Billing\ValueObjects\Money;

app(DiscountAllowances::class)->grant(
$customer, // the customer who was brought in
Money::of(2500, 'EUR'), // what the next cycles may take off together
'referral:'.$referral->id, // why it was granted, once per customer
'Welcome discount', // the line the invoice shows
);

Each cycle the package bills itself takes off at most what it comes to after its coupon, and the rest waits for the next cycle. A cycle of 19.00 under an allowance of 25.00 costs nothing, and the next one costs 13.00. The invoice shows the reduction as a discount line, and the tax is computed from the reduced price, because a discount on the customer's own purchases lowers the price of the supply (Abschn. 10.3 Abs. 2 UStAE). Nothing of an allowance is ever paid out.

A second grant with the same cause returns the first and grants nothing, so an event that arrives twice grants once. remainingFor($customer, 'EUR') says what is left. Two allowances in one currency are used one after the other, the older first, each with its own line, and an allowance in another currency is not touched. A preview of the next invoice takes the allowance off as the cycle will and uses nothing. A cycle whose collection fails gives back what it took: the dunning retry prices it again, and a cycle that is never collected stops counting. A cycle that is refunded keeps what it took, because a refund returns money, and an allowance was never money.

An allowance applies to the cycles the package bills itself, which is the Mollie driver. Stripe prices its own invoices, and there an allowance is not taken off anything.

Price changes​

A tier's price can change while subscriptions to it run. Declare the change, and the package announces it to every running subscription, once, and bills each one the new price only from the day its announcement named:

// config/billing.php
'price_changes' => [
'changes' => [
'pro-2027' => [
'kind' => 'plan', // the base price of a tier
'announce_on' => '2026-12-01',
'effective_on' => '2027-02-01',
'prices' => ['pro' => 2400], // minor units, in the tier's currency
'text' => [
'en' => 'Pro costs 24.00 a month.',
'de' => 'Pro kostet 24,00 im Monat.',
],
],
],
'notice_months' => ['plan' => 1], // full calendar months
],

The notice is counted in full calendar months, and the month the announcement falls into does not count: a change announced on 22 October with one month of notice takes effect on 1 December at the earliest. A change that breaks a rule, a notice shorter than its kind needs, a tier the catalog gives no price, an amount that is not positive, a day that is not a day or a text with no English, is announced to nobody, and billing:doctor names every rule it breaks.

billing:price-changes:announce runs every day and tells each running subscription of a tier the change names, in the owner's language: from which day the new price applies, what changes in the words of text, and that the customer can cancel to that day. The day is the change's own, or later for a subscription the announcement reaches late, which gets the full notice from the moment it was told. A subscription billed yearly keeps its price to its first renewal on or after that day. Nobody is told whose subscription began on or after the change's day, which ordered at the new price, or whose subscription ends before the day.

Each cycle that begins on or after the day of a subscription's announcement is billed at the new price, and every cycle before it at the old one. A subscription that was never told keeps the old price. Where two changes have come for the same tier, the one with the later day holds. The preview of the next invoice and the notice before a direct debit read the same price.

A meter's price changes the same way, with the kind metered. Its prices name the new price per package of each meter, by tier, in minor units of the meter's currency, and its notice is set apart from the base price's:

'emails-2027' => [
'kind' => 'metered',
'announce_on' => '2026-12-01',
'effective_on' => '2027-02-01',
'prices' => ['pro' => ['emails' => 80]], // 0.80 per package of emails
'text' => ['en' => 'A package of 1,000 emails costs 0.80.'],
],

MeteredCycleAmountResolver rates a cycle that begins on or after the day of the subscription's announcement at the new price per package, and every cycle before it at the old one. A meter the tier does not have refuses the change.

A price change applies to the cycles the package bills itself, which is the Mollie driver. Stripe prices its own invoices, so a change declared there is announced to nobody, and billing:doctor reports it.

Trial codes​

A coupon can give a subscription days of trial, instead of a discount or as well as one. Its trial_days name them by plan, with * for every plan they do not name:

use Pushery\Billing\Models\Coupon;

Coupon::query()->create([
'code' => 'PARTNER30', 'type' => 'percent', 'value' => 0, 'duration' => 'once',
'max_redemptions' => 500, 'expires_at' => '2026-12-31 23:59:59',
'trial_days' => ['pro' => 30, '*' => 14],
]);

The code travels like any coupon code: the customer enters it, and it goes to the subscription start. The days count only where the code is redeemed, under the coupon's row lock, so of two customers racing for its last redemption one gets the trial and the other none:

  • A subscription whose trial needs no payment method starts at once, and the code is redeemed in the same transaction that writes it.
  • A subscription that needs a mandate carries the code across the redirect, and the code is redeemed when the mandate settles. A customer who never comes back has spent nothing.

A code is spent only when it lengthens the trial. One that gives fewer days than your trial policy is left alone, so the customer keeps it. A code is honored for a customer who had a trial before, because winning someone back is what such a code is for. The end of the trial is announced like that of any subscription trial, by billing:warn-ending-trials.

To check a code on your own form before the start, TrialCodes::assertGives() answers the days the code gives the plan. It throws TrialCodeRefused with one message for every code that gives nothing, whether it is unknown, withdrawn, past its last day, used up, issued by a seller or without days for the plan, so the answer never tells a stranger which codes exist:

use Pushery\Billing\Discounts\TrialCodes;
use Pushery\Billing\Exceptions\TrialCodeRefused;

try {
$days = app(TrialCodes::class)->assertGives($request->string('code')->value(), 'pro');
} catch (TrialCodeRefused $refused) {
return back()->withErrors(['code' => $refused->getMessage()]);
}

Localized hub and emails​

The hub and its emails ship translated in English, German, Spanish, French, Italian, Dutch and Portuguese, with an informal register throughout. Publish the views or the translations to customize them:

php artisan vendor:publish --tag=billing-views
php artisan vendor:publish --tag=billing-lang

Every publishable asset also sits under a shared billing umbrella tag, so php artisan vendor:publish --tag=billing publishes the config, migrations, views and translations in one go.


← Back to the documentation index

SEPA direct debit on your own form​

With the Mollie driver, an account holder can give a SEPA direct debit mandate on a form of your application, with their name and IBAN and no payment. Pushery\Billing\DirectDebit\DirectDebitMandates has one call per screen:

use Pushery\Billing\DirectDebit\DirectDebitMandates;
use Pushery\Billing\ValueObjects\DirectDebitConsent;

$mandates = app(DirectDebitMandates::class);

// The form: the mandate text for the payer's country, under a new reference. Null means no
// mandate is taken there, and the form offers another way to pay.
$text = $mandates->text('DE');

// The confirmation: what the account holder entered, and the text the form showed.
$mandate = $mandates->give($owner, new DirectDebitConsent(
accountHolder: $request->string('account_holder')->value(),
iban: $request->string('iban')->value(),
country: 'DE',
reference: $text->reference,
statement: $text->statement(),
notifyEmail: $request->string('email')->value(),
ip: $request->ip(),
userAgent: $request->userAgent(),
));

text() answers the parts a form shows: heading, the particulars the rulebook asks the payee to state, the paragraphs with the authorization and the refund notice, and the agreement of the notice period beside the mandate. statement() joins them into one text.

give() checks the IBAN (its country, its length and its check digits), checks that the text is still the one the form showed, and registers the mandate at Mollie. The payee is Stichting Mollie Payments with its creditor identifier, on behalf of billing.company.name. The mandate becomes the one the local engine charges, because the form is where the account holder chose it. A refusal throws DirectDebitMandateRefused with a reason and stores nothing.

The consent is kept in billing_mandate_consents, written once: the text, the reference, the account holder, the country and last four characters of the account, the agreed notice period, the address the notices go to, and when and from where the account holder confirmed. An erasure unlinks it from its owner and keeps it, because the payee has to be able to show the mandate while a debit drawn under it can still be disputed.

The rulebook asks for the mandate in a language of the payer's country. The package ships the German wording, for AT, DE, LI and LU. Another country gets a mandate once billing.direct_debit.mandate_wordings names a class of your own implementing Pushery\Billing\Contracts\SepaMandateWording for it.

The notice before each debit​

The local engine announces every SEPA direct debit before it draws it, by DirectDebitAnnouncedNotification, billing.direct_debit.notice_days ahead, or by the period a mandate's consent records. That covers mandates given on your form and mandates a first payment established, since Mollie collects iDEAL, Bancontact and the other bank methods as direct debits afterwards. A notice goes to the address the account holder gave with the mandate, and to the owner otherwise.

  • A subscription is announced once for its amount, which then covers each later due date. The engine announces a due cycle the agreed number of days ahead, priced the way the cycle prices it, so the debit is drawn on its day. When the amount changes, the new amount is announced before it is drawn.
  • The rest of a period after a change, a late fee, and the retry of a cycle the bank returned are each announced on their own and collected on the first day their notice allows.
  • A debit that comes due without a notice that names it is announced then and waits for its notice period. The subscription's next run moves to that day, and nothing is claimed in between.

Each notice is recorded in billing_direct_debit_notices, which goes with the owner on an erasure.

Handing a mandate to another owner​

A payment method can be given before the owner it is meant for exists: a customer gives it with an order, and the account that carries the subscription is created from that order later. handOver() gives the mandate to the account:

use Pushery\Billing\DirectDebit\DirectDebitMandates;
use Pushery\Billing\Models\PaymentMandate;

$mandate = PaymentMandate::defaultFor($order->getMorphClass(), $order->getKey(), 'mollie')
?? throw new RuntimeException('The order has no payment method to hand over.');

app(DirectDebitMandates::class)->handOver($mandate, $account);

The mandate becomes the account's default at its provider, and the account takes the provider's customer the mandate belongs to into billing.customer.column, where a webhook finds its owner. The order gives that customer up once none of its mandates belongs to it any more. The consent and the notices stay as they are, because both are found by the mandate's reference, so the account's subscription is announced with the notice period the account holder agreed to. Any mandate the package stores can be handed over, a card or PayPal mandate as well as one given on the form, and handing one to the owner it already has changes nothing.

A MandateHandOverRefused names its reason: holds_a_default where the account already has a default payment method at that provider, and another_customer where it already belongs to another customer there. Nothing moves in either case.

A card or PayPal mandate without a charge​

The subscriptions the package starts establish a mandate through a first payment of the tier's verification amount, on a checkout that offers every method of your Mollie profile. An application that runs its own checkout can name the methods instead, and Mollie then offers them alone:

use Pushery\Billing\Contracts\EnsuresProviderCustomer;
use Pushery\Billing\Contracts\EstablishesMandateWithMethods;
use Pushery\Billing\ValueObjects\Money;

$handshake = app(EstablishesMandateWithMethods::class)->beginMandateWith(
app(EnsuresProviderCustomer::class)->customerFor($owner),
Money::of(0, 'EUR'),
url('/billing/mandate/return'),
['creditcard', 'paypal'],
);

return redirect()->away($handshake->checkoutUrl);

A first payment of 0.00 is taken where every method named takes one without a charge, which Mollie documents for credit card and PayPal and requires for Bacs; the customer then sees nothing on a statement. Zero with any other method is refused with an InvalidArgumentException before anything is sent. The mandate exists once the customer completes the checkout; the handshake's paymentReference names the first payment that establishes it.

A subscription on a mandate the owner has given​

start() sends a customer who needs a payment method to Mollie, even one whose mandate your application already holds: a direct debit given on your own form, or a card or PayPal mandate taken on your own checkout. Where the customer chose that mandate, start the subscription on it instead, without a redirect:

use Pushery\Billing\Contracts\StartsOverAMandate;

$start = app(StartsOverAMandate::class)->startOverTheMandate($owner, 'pro', $couponCode);

The subscription is written at once and charged to the owner's default mandate. Where the tier gives a subscription trial the owner has not had, it is in that trial, and the first run comes at the trial's end. Otherwise it is active from now, and its first period is charged by the next billing:run where it is collected in advance, or at the period's end where it is collected in arrears. $start->state says which, and $start->needsRedirect() is false. A coupon code is honored as start() honors it. A generic trial stands on the owner rather than on a subscription, so this call grants none.

An owner with no valid mandate at Mollie is refused with a SubscriptionNotPermitted before anything is written, and so are a tier the catalog does not sell and an owner who already subscribes. Nothing draws on a stored mandate on its own: a customer who presses Subscribe on the plan screen is still sent to Mollie, because they may mean to give a new payment method. On a Stripe install the contract is not bound, so ask the container with app()->bound(StartsOverAMandate::class) before you offer it.

A charge on the mandate, without a checkout​

Some amounts are no cycle: usage counted over a month and billed on an invoice of its own, or a service whose price is known once it is delivered. On the package's own engine, which bills the cycles of the Mollie driver, ChargesOnTheMandate charges such an amount against the owner's default mandate, as an order of its own with the lines you give it:

use Illuminate\Support\Carbon;
use Pushery\Billing\Contracts\ChargesOnTheMandate;
use Pushery\Billing\Enums\OrderItemType;
use Pushery\Billing\Enums\TaxArchetype;
use Pushery\Billing\ValueObjects\OrderItemDraft;

$charge = app(ChargesOnTheMandate::class)->chargeOnTheMandate(
$owner,
[
new OrderItemDraft('Storage above 10 GB, November 2026', 250, 3, 'EUR', OrderItemType::Usage),
new OrderItemDraft('Receipts above the quota, November 2026', 2, 1200, 'EUR', OrderItemType::Usage),
],
'usage:2026-11',
TaxArchetype::Subscription,
Carbon::parse('2026-11-01'),
Carbon::parse('2026-12-01'),
);

The reference is yours, unique for the owner: the same reference again returns the order the first call wrote and charges nothing, so a job that runs twice for the same month charges it once. Lines that come to nothing or less write no order and no invoice, and $charge->order is then null. Lines in more than one currency, a credit line, or a period with one end are refused with an InvalidArgumentException before anything is written.

The owner's credit is spent first, and the rest is charged against the default mandate once the transaction around the call has committed, after a notice where that mandate draws a direct debit. The statement the customer reads names the first line. $charge->order->status then says where the charge stands: Paid, Processing while a bank debit settles, or Open. An open order with a $charge->failure was not collected: no_usable_mandate where the owner has no mandate that can be charged off-session, otherwise the reason the provider gave. It is collected after the owner's next paid cycle, as a late fee is, and nobody is dunned for it.

Once paid, the invoice is raised by the issuer that documents a cycle. It is taxed as the archetype you name, at the place recorded for the owner's subscription, and states the period you name. A period is a span of days, read as the dates you pass, and ends where the next one begins, as a subscription's does: November runs from 2026-11-01 to 2026-12-01. Without a period, the supply is the day the payment was confirmed, as for a purchase. An owner with no place recorded gets an invoice that states no tax.

On a Stripe install the contract is not bound, so ask the container with app()->bound(ChargesOnTheMandate::class) before you offer it.