Subscriptions and cron
Read this page even if you are not selling subscriptions. The shop hangs eight jobs on the site's cron, and three of them cost money when they go quiet.
A subscription is an order
There is no separate "subscription" entity, and that is deliberate — it means every subscription gets the order list, the order card, the invoice, the receipt and the history feed for free, instead of a parallel half-built world next to them.
A subscription is an order carrying four extra things:
| Column | What it holds |
|---|---|
period | the length of the paid stretch; 0 means a one-off purchase |
starts_at / expires_at | when access begins and when it runs out |
auto_renew | the buyer asked to be charged again |
recurrent_token | the card binding at the gateway. No card data is stored here |
Access is granted and revoked by the site, listening to the events below. The component tracks the dates and the money; what "access" means — a resource, a group, a file — only the site knows.
The component has no scheduler
This is the single most important sentence on the page. There is no cron entry point inside the component — no script, no processor, no route. pbShop exposes the methods; the site's cron calls them.
A shop whose owner never wrote that crontab line gets a shop that silently does not renew. Nothing in the component can fix that, which is exactly why the next section exists.
0 3 * * * /usr/bin/php /path/to/site/core/App/cron/subscriptions.php$pbs = modx()->services->get('pbshop');
$pbs->fiscal()->poll(); // every few minutes
$pbs->orders()->expire(); // daily
$pbs->orders()->dueForRenewal(); // daily, then renew() on each
$pbs->stock()->releaseStale(); // as suits the shop
$pbs->stockAlerts()->notifyRestocked(); // as suits the shop
$pbs->cart()->purge(); // monthly
$pbs->compare()->purge(); // monthly
// Waybills take their own class: a shop with no delivery has no carrier
// in the container.
(new \Boshnik\PbShop\Services\WaybillService())->dueForTracking();The eight jobs
| Job | Method | Why it runs | Critical |
|---|---|---|---|
fiscal.poll | fiscal()->poll() | picks up receipts the register never confirmed | ● |
orders.renew | orders()->dueForRenewal() | selects subscriptions due for a charge | ● |
orders.expire | orders()->expire() | marks the ones whose time ran out | ● |
stock_alerts.notify | stockAlerts()->notifyRestocked() | mails "back in stock" | |
stock.release_stale | stock()->releaseStale() | returns the reservation from abandoned orders | |
waybills.track | WaybillService::dueForTracking() | selects parcels to ask the carrier about | |
cart.purge | cart()->purge() | clears guest carts | |
compare.purge | compare()->purge() | clears guest comparisons |
"Critical" is about the price of silence, not importance. A quiet register and a quiet renewal mean money and a conversation with the tax office: orders keep coming, receipts are not issued, subscriptions are not renewed. Unrevoked access is the same revenue from the other side — a service delivered and not paid for. A quiet cart purge means rubbish in a table.
Checking that cron is called at all
Every job leaves its own mark: when it was called, how much it handled and how it ended. Settings → Cron runs in the manager.
The marks are written by the service methods themselves, so you do not edit the site's script to get them — it already calls those methods. That was the deciding constraint: anything requiring a change to the site's script would never appear on shops already installed, because that script is not updated with the package.
A job whose row says "Last run: never" has not run once — which means there is no line for it in the crontab. The mark is per job, not one per shop, and it has to be read that way: the schedules differ by three orders of magnitude, so "cron ran yesterday" (yesterday it purged carts) says nothing about the register.
"Selected" is not "done"
The mark for subscriptions and for carrier polling reads selected, not processed, and the difference is not cosmetic. Those two methods hand back rows; the charging and the asking are done by the loop in the site's script, and how each call ended is not visible to the component. "Selected 3" does not mean "renewed 3".
When silence touches money or the tax office, a banner appears on the shop's manager pages. It turns red only when work is genuinely waiting — there is no "quiet for six hours" threshold on purpose, because the schedule lives in a crontab the component cannot see. On a fresh install the banner is yellow: that is not a fault, it is a reminder that cron is not wired up yet.
Auto-renewal
dueForRenewal() returns the orders whose expires_at falls inside the renewal window; the default window is three days. Then you call renew() on each.
foreach ($pbs->orders()->dueForRenewal() as $order) {
$pbs->orders()->renew($order);
}renew() returns null and does nothing unless all three of these hold:
auto_renewis on — the buyer asked for it;recurrent_tokenis not empty — the gateway handed back a binding;- the order's payment driver answers
supportsRecurring().
Five of the ten drivers in the box do: maib, monobank, wayforpay, fondy and stripe. A subscription sold through LiqPay or PayPal will not auto-charge, and that is a property of the gateway, not a gap here — see What ships where.
A successful charge creates a new order continuing from the old expiry date, not from today, so a renewal two days early does not cost the buyer two days. A refused charge marks the payment failed and leaves the subscription alone; the order stays in the selection, so the next cron run tries again.
There is no dunning, and no mail about any of this
The component does not limit retries, does not downgrade, does not suspend, and sends no letter about an upcoming charge, a failed charge or a successful renewal. There is no "your card was declined" email unless you write it.
Hang your own listener on pbShopPaymentFail and decide the policy there. This is worth planning before launch rather than discovering from a buyer who quietly stopped paying three months ago.
A repeat callback does not add a second period: renewal is idempotent on the payment row.
Expiry
expire() finds paid orders whose expires_at has passed and which have not been marked yet, stamps expired_at, and fires pbShopOrderExpire once per order. It returns how many it marked.
It does not change the order's status and does not revoke anything by itself. Revoking is the site's job, in a listener:
// core/App/config/pbshop.php
return [
'listeners' => [
\Boshnik\PbShop\Events\Dispatcher::ORDER_EXPIRE => [
App\Listeners\RevokeAccess::class,
],
],
];The stamp is written before the event fires, so a listener that throws does not make the event repeat on every cron run from then on.
There is no grace period
Two settings ship, pbshop_renew_days_before and pbshop_grace_days, with labels and descriptions in four languages — and nothing reads either of them. Verified in the code on 2026-10-24.
So: the renewal window is three days and changing that setting does nothing; and access does not survive expiry by a single day, whatever you type into the grace field. If you need either, pass the window explicitly — dueForRenewal($days) takes an argument — and implement the grace period in your ORDER_EXPIRE listener by deferring the revocation yourself.
The two dead settings are recorded as a defect; they are documented here as dead rather than omitted, because a setting with a translated description looks like a working feature.
Cancelling
The buyer turns auto-renewal off themselves: POST /pay/orders/{id}/cancel, wired to a button in the account and on the order page. That fires pbShopOrderCancel. It stops the next charge; it does not end the current paid period, which runs to expires_at as paid for.
A manager can toggle auto_renew on the order form. The buyer is only shown the "Auto-renewal" line when a charge would actually happen.
Events
| Event | Fired when |
|---|---|
pbShopOrderPaid | money arrived for the order |
pbShopOrderExtend | an existing paid stretch was extended |
pbShopOrderExpire | the term ran out — revoke access here |
pbShopOrderCancel | auto-renewal switched off |
pbShopPaymentSuccess / pbShopPaymentFail | the charge itself |
A listener is a class with handle(array $params, string $event), or any callable. An exception in one does not bring the payment down: it is logged and the rest still run. Details in For developers.