Skip to main content

Recurring subscriptions

JoltzuSubscriptions combines billing plans with keeper callbacks. Merchants fund automation; subscribers separately authorize a maximum charge per period. It supports prepaid native currency and ERC-20 transferFrom payments. It is distinct from the node's native recurring mandates.

Merchant plans​

createPlan(
    payee, token, price, period, gracePeriod,
    maxIncreaseBps, increaseInterval, noticePeriod
)

Use the zero token address for native payments. The payee, periods and price-increase terms are part of the plan; changed terms require a new plan that subscribers opt into. maxIncreaseBps = 0 fixes the price. For example, 500 basis points permits at most 5% per increase, with the required advance notice and minimum interval. That interval must be at least a billing period. Price decreases apply immediately and cancel pending increases. Closing a plan to new sign-ups leaves existing subscriptions running.

Subscriber authorization​

subscribe(planId, maxAmount) pays the first period immediately. maxAmount limits each subsequent charge. Set it to the current price to approve no increase, or choose an explicit higher cap if you accept future increases. A later price above the cap fails until the subscriber increases approval.

Native funds come from a prepaid balance funded by deposit or the subscription call; the subscriber may withdraw it. ERC-20 payments go directly from the subscriber to the payee using allowance, with no token custody by this manager. Fee-on-transfer assets can deliver less than the plan price. Asset support and chain restrictions must be checked separately.

Billing and cancellation​

Billing stays anchored to paidThrough, rather than shifting after a late callback. A due charge collects at most one period and only to the plan's payee. Failed keeper collections retry daily within the grace window. After grace, the subscription lapses; resuming requires subscribing again. Either party can cancel future charges, without refunding already paid time.

status(id) returns 1 Active, 2 PastDue, 3 Lapsed or 4 Cancelled. Follow Subscribed, Charged, ChargeFailed, PriceIncreaseScheduled and SubscriptionCancelled events when providing access to a service.

Pay for automation​

Each callback costs automationCost(), debited from the plan's automation budget. Fund it on plan creation or with fundAutomation. Include retries; periods longer than about 29 days require an extra early wake-up because the keeper horizon is 30 days.

An exhausted budget emits AutomationUnfunded and stops scheduling. Due charges remain manually callable. Fund the budget and call restartAutomation(id) to resume; it also handles expired undelivered callbacks and returns their refundable request payment to the budget. Native payees withdraw revenue through withdrawCredits.

The HTTP keeper API does not serve subscription plan state. Use the subscription contract's EVM-compatible views or index its events. The native keeper storage reader currently covers coordinator/SigNet storage, not general subscription queries.