Billing cycles
Pull each cycle manually, from your backend, or from a keeper.
A billing cycle is one successful pull_funds. Only the merchant can sign it, but you choose who submits it.
Options
Subscribers → select → Pull now.
Dashboard pulls are in preview and simulated. For real pulls, use the Merchant API or the CLI.
Timing
- The first pull on a new vault is allowed right away.
- After that, pull when
ledger_time >= last_pull_timestamp + interval_seconds. The ledger clock can differ slightly from your server's clock, so simulate first. - A pull that fails does not update
last_pull_timestamp, so you can simply retry it.
How next_billing_date is calculated
When a pull through POST /trigger-pull is confirmed on-chain, the API sets:
next_billing_date = pull time + plan.interval_seconds- Pull time is the API server's clock at the moment it sees the confirmation, not the previous
next_billing_dateand not the ledger timestamp. - The interval is a fixed number of seconds, not a calendar month. See the "Intervals are fixed durations" note in Plans.
- A late pull pushes every later cycle back by the same delay. The schedule does not catch up.
- A pull that fails or is not confirmed in time leaves
next_billing_datewhere it was.
Example. A plan with interval_seconds: 604800 (7 days) pulled at 2026-10-01T10:00:00Z gets next_billing_date 2026-10-08T10:00:00Z.
Failure handling
| Failure | Meaning | Action |
|---|---|---|
Too early to pull funds | Interval not elapsed | Retry after last_pull + interval |
| SAC allowance error | Allowance spent, expired or revoked | Mark past due and ask the subscriber to re-approve |
| SAC balance error | Subscriber lacks funds | Retry later and notify the subscriber |
Vault does not exist | No vault for this pair | Subscriber never completed create_vault |