Managing subscriptions
After a subscription is created, you control renewals from Dashboard → Subscriptions: cancel, undo a pending cancel, pause collection, resume, and extend the current period with free days. Your app stays in sync via webhooks and optional GET lookups. If the subscription was created with an API merchant_fee, renewals keep that fee name and percent/fixed — see Subscriptions and Payments & fees.
/v1/subscriptions/... write endpoints. Use webhooks (and GET /v1/subscriptions/:id) to reflect those changes in your product.Cancel
At period end (default) keeps access until current_period_end, then moves the subscription to canceled. The customer is not charged again.
Immediate cancels now and revokes ongoing billing. Use this when access should stop right away.
If the customer changes their mind before the period ends, use Undo cancel to clear the pending cancellation flag.
What your app receives after cancel
Example request
# Dashboard: Subscriptions → Cancel (at period end) # Then when the period ends (or on immediate cancel):
Example response
{
"id": "evt_...",
"type": "subscription.canceled",
"created": 1726000000,
"data": {
"id": "sub_01HXYZ...",
"status": "canceled",
"cancel_at_period_end": false,
"payment_collection_paused": false,
"merchant_id": "acct_...",
"livemode": true
}
}How to handle it
Revoke access for data.id. While cancel-at-period-end is pending you may also get subscription.updated with cancel_at_period_end: true— keep access until the canceled event.
Pause and resume
Pausing stops future renewal charges while you can choose to keep the customer's access. Optionally void outstanding past-due invoices. Resume restores billing on the normal schedule. You may schedule an automatic resume time when pausing.
Pause / resume webhooks
Example request
# Dashboard: Pause collection → later Resume
Example response
{
"id": "evt_...",
"type": "subscription.paused",
"created": 1724100000,
"data": {
"id": "sub_01HXYZ...",
"status": "active",
"cancel_at_period_end": false,
"payment_collection_paused": true,
"merchant_id": "acct_...",
"livemode": true
}
}
# Later:
{
"id": "evt_...",
"type": "subscription.resumed",
"created": 1724700000,
"data": {
"id": "sub_01HXYZ...",
"status": "active",
"payment_collection_paused": false,
"merchant_id": "acct_...",
"livemode": true
}
}How to handle it
On pause, either freeze features or keep access per your product policy. On resume, restore normal entitlements. Confirm with GET /v1/subscriptions/:id if you need payment_collection_paused.
Add free days
Comp the customer by extending the current billing period (1–1095 days) from the dashboard. The next renewal date moves forward. You will receive subscription.updated with a later current_period_end when you fetch the subscription.
Confirm period after a dashboard change
Example request
GET /v1/subscriptions/sub_01HXYZ... Authorization: Bearer rk_live_...
Example response
{
"id": "sub_01HXYZ...",
"object": "subscription",
"status": "active",
"amount": 2900,
"currency": "usd",
"interval": "month",
"cancel_at_period_end": false,
"payment_collection_paused": false,
"trial_ends_at": null,
"current_period_end": 1726800000000,
"customer": "cus_01H...",
"customer_email": "ada@example.com",
"created": 1723000100000,
"livemode": true
}How to handle it
Update your local renewal date from current_period_end (milliseconds). Prefer reacting to webhooks first; use GET to reconcile if a delivery was missed.
Billing sync
Live subscriptions show a linked badge once Rollo has attached the underlying membership from payment webhooks. Pause, cancel, resume, and free-day actions then sync to recurring billing. Sandbox subscriptions are always linked locally.
Creating subscriptions: Subscriptions & free trials. Webhook payloads: Webhooks.