Meteric facade

Meteric\Facades\Meteric is the entry point. It resolves Meteric\Meteric from the container. Every method below is a static call on the facade.

use Meteric\Facades\Meteric;

Subscriptions

subscribe(?Model $customer = null): SubscriptionBuilder

Start building a subscription. Pass the billable customer model, or omit it and set the account on the builder. See Subscriptions.

checkout(?Model $customer = null): SubscriptionBuilder

Same as subscribe(). End the chain with ->checkout() to create the subscription and immediately invoice the first cycle.

renew(Subscription $sub, ?CarbonImmutable $at = null): array

Accrue the next cycle for every due item, rolling forward through elapsed periods. Idempotent. Returns the created charges.

changePlan(SubscriptionItem $item, Price $newPrice, ?DowngradePolicy $downgrade = null, ?UpgradePolicy $upgrade = null, ?CarbonImmutable $at = null): SubscriptionItem

Switch an item's plan. Direction is detected from the price. $upgrade picks the upgrade policy, $downgrade the downgrade policy. See Plan changes.

cancel(Subscription $sub, string|CarbonImmutable $at = 'period_end', ?CarbonImmutable $when = null, array $meta = []): Subscription

Cancel at 'period_end' (default), 'now', or a future term boundary. No automatic refund. $meta stores cancellation data (a reason, a survey answer) on the subscription metadata under cancellation. See Subscriptions.

cancellationOptions(Subscription $sub, int $count = 3): array

The next $count term boundaries that still satisfy the product's notice window, as a list<CarbonImmutable>. Render these as a "cancel at end of period N" choice.

processDueCancellations(?CarbonImmutable $at = null): int

Enact scheduled cancellations whose boundary has passed: cancel the subscription and fire SubscriptionCanceled. Returns the count. meteric:run calls this, so you rarely call it directly.

Items: addons, options, quantity

addAddon(SubscriptionItem $item, Price $price, ?string $group = null, float $qty = 1, ?CarbonImmutable $at = null): Addon

Book a prorated addon. Members of the same group are swapped (the old one is credited out).

removeAddon(Addon $addon, ?CarbonImmutable $at = null): void

Remove an addon mid-cycle with a prorated credit for the unused portion.

setOption(SubscriptionItem $item, string $key, string $value, string $type, ?Price $price = null, float $qty = 1, ?CarbonImmutable $at = null, ?float $min = null, ?float $max = null, ?string $label = null): ItemOption

Set a configurable option (slots, OS, toggle). Prorates the price delta when a price is given; the option then recurs every renewal. $min/$max bound a quantity and throw InvalidArgumentException when violated. $value is the raw value the provisioning system reads (e.g. 1024); $label is the display value (e.g. 1 GB RAM). Both snapshot onto the item, so deleting the catalog option later does not change the selection.

chooseOption(SubscriptionItem $item, ProductOptionValue $value, float $qty = 1, ?CarbonImmutable $at = null): ItemOption

Apply a declared catalog option value. Reads the key, type, bounds, price, raw value, and display label off the ProductOptionValue, then calls setOption.

setQuantity(SubscriptionItem $item, float $qty, ?CarbonImmutable $at = null): SubscriptionItem

Change an item's base quantity, prorating the difference.

Usage

recordUsage(SubscriptionItem $item, string $dimension, float $quantity, ?CarbonImmutable $occurredAt = null, ?string $key = null): UsageRecord

Report metered usage for a dimension. Idempotent on key.

rollupUsage(SubscriptionItem $item, Period $period): array

Roll up an item's usage window into in-arrears charges. Returns the created charges. See Usage billing.

Quoting

quote(): QuoteBuilder

Start a read-only quote for checkout rendering. Nothing is persisted. See Quotes and checkout.

Invoicing and payments

invoicePending(BillingAccount $account, ?string $currency = null): ?Invoice

Collect an account's pending charges in one currency and issue them via the bound driver. Returns the invoice, or null when nothing is pending. Currency defaults to the account's.

invoiceConsolidated(BillingAccount $payer, ?string $currency = null): ?Invoice

Bill the payer's own and all child accounts' pending charges onto a single invoice, itemized per account.

recordPayment(Invoice $invoice, Money $amount, ?string $reference = null): Payment

Record an inbound payment against an invoice and advance its state.

creditNote(Invoice $invoice, Money $amount, ?string $reason = null): CreditNote

Issue a credit note reversing $amount (net) of an invoice. The driver mirrors the invoice's tax on top and fires CreditNoteIssued. Meteric does not refund; your gateway does. See Credit notes and refunds.

voidInvoice(Invoice $invoice): Invoice

Void an unpaid invoice. Refuses once any payment exists; correct a paid or finalized invoice with a credit note instead.

driver(): InvoiceDriver

The bound invoice driver instance.