Skip to content

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:

ColumnWhat it holds
periodthe length of the paid stretch; 0 means a one-off purchase
starts_at / expires_atwhen access begins and when it runs out
auto_renewthe buyer asked to be charged again
recurrent_tokenthe 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.

bash
0 3 * * * /usr/bin/php /path/to/site/core/App/cron/subscriptions.php
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 ​

JobMethodWhy it runsCritical
fiscal.pollfiscal()->poll()picks up receipts the register never confirmed●
orders.reneworders()->dueForRenewal()selects subscriptions due for a charge●
orders.expireorders()->expire()marks the ones whose time ran out●
stock_alerts.notifystockAlerts()->notifyRestocked()mails "back in stock"
stock.release_stalestock()->releaseStale()returns the reservation from abandoned orders
waybills.trackWaybillService::dueForTracking()selects parcels to ask the carrier about
cart.purgecart()->purge()clears guest carts
compare.purgecompare()->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.

php
foreach ($pbs->orders()->dueForRenewal() as $order) {
    $pbs->orders()->renew($order);
}

renew() returns null and does nothing unless all three of these hold:

  1. auto_renew is on — the buyer asked for it;
  2. recurrent_token is not empty — the gateway handed back a binding;
  3. 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:

php
// 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 ​

EventFired when
pbShopOrderPaidmoney arrived for the order
pbShopOrderExtendan existing paid stretch was extended
pbShopOrderExpirethe term ran out — revoke access here
pbShopOrderCancelauto-renewal switched off
pbShopPaymentSuccess / pbShopPaymentFailthe 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.

Next ​

  • Payments — which drivers can take a recurring charge
  • Receipts — fiscal()->poll() and why it is on the same cron

pbShop — a shop component for PageBlocks