Skip to content

Pause, skip, and resume subscriptions

A subscriber who wants a break is easier to keep than one who cancels. Flint gives you three ways to stop a charge without ending the subscription: pause billing for a while, skip one renewal, or offer a pause when the buyer starts to cancel. A pause keeps the time the subscriber already paid for and gives it back when billing resumes, so nobody pays twice or loses days.

This guide assumes you have subscriptions that renew, as in Subscription billing.

Pause or skip#

PauseSkip
RoutePOST /v1/subscriptions/{subscription_id}/pausePOST /v1/subscriptions/{subscription_id}/skip-cycle
How longOne or more billing cycles, or until resumedThe next renewal only
StatuspausedStays active
Paid timeSet aside at pause, restored on resumeKept; the current period grows by one interval
Billing anchorMoves with the resumed scheduleDoesn't change
Use it forA seasonal break, a hardship hold, a buyer's vacation"Not this month" on a box or a service visit

Both work only on an active subscription that isn't set to cancel. Neither uses up a cycle: a subscription with an end_after in the cycles form ends later by the length of the pause or skip. A date end doesn't move.

Pause#

cURL
curl -X POST https://api.withflintpay.com/v1/subscriptions/sub_1kmn0aExample/pause \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"pause_duration_cycles": 2}'

The pause starts immediately, and the subscription is paused with paused_at set.

  • pause_duration_cycles (1 or more) pauses for that many billing intervals. scheduled_resume_at says when it resumes on its own: paused_at plus that many intervals.
  • Omit it to pause until you resume. scheduled_resume_at is then null.
  • Pausing again with the same length, or again without one, returns the subscription unchanged. A different length returns 409 ACTION_NOT_ALLOWED, reason field_locked. Resume first, then pause with the new length.

pause_reason says why a subscription is paused:

pause_reasonWho paused it
merchantYou, with your API key or the dashboard.
buyerThe buyer, from their account.
payment_failedFlint, when renewal retries ran out and your dunning settings pause instead of cancel.
delivery_action_requiredAnyone who pauses during a delivery hold, or Flint when the hold runs out.

Pausing sends subscription.paused. Flint doesn't email the buyer about a pause or a resume that you or they start, so tell them from subscription.paused and subscription.resumed. Suspend access while paused if your product pauses with billing.

Pause refuses these states with 409 ACTION_NOT_ALLOWED:

reasonStateWhat to do
cancellation_scheduledactive, set to cancel at period endReactivate it, then pause.
unsupported_statetrialing, past_due, scheduled, or incompletePause once it's active.
terminal_statuscanceledCreate a new subscription.

Resume#

cURL
curl -X POST https://api.withflintpay.com/v1/subscriptions/sub_1kmn0aExample/resume \
  -H "Authorization: Bearer YOUR_API_KEY"

Resume finishes after the response. Flint accepts it with 202 Accepted and Retry-After: 2: the subscription is still paused, resume_requested_at is set, and Flint sends subscription.updated. Then one of two things happens, and resume_requested_at clears either way:

  • Resumed. The status becomes active, or past_due while an overdue period is collected, and Flint sends subscription.resumed.
  • Refused. Delivery still can't be quoted for a delivery_action_required pause. The subscription stays paused, nothing is charged, and Flint sends subscription.updated.

A pause with pause_duration_cycles resumes the same way at scheduled_resume_at. Grant paid access again only once the subscription is active.

Resume works only on a paused subscription. A past_due one returns 409 ACTION_NOT_ALLOWED, reason payment_required; recover it with a payment retry. A subscription set to cancel returns cancellation_scheduled; undo the cancellation with PATCH and cancel_at_period_end: false instead.

What resuming does to the billing date#

On a flint schedule, Flint gives back the paid time that was left when the subscription paused. The resumed period starts at the resume and ends that much later, next_billing_at moves to its end, and billing_anchor_day moves with it. Renewals after that are a full interval apart.

A monthly subscription paid for May 1 to June 1 pauses at midnight UTC on May 11, with 21 days of paid time left:

PauseResumesNext chargeNew anchor
Until resumed, resumed June 20June 20July 11, for a full month11
pause_duration_cycles: 2July 11, at scheduled_resume_atAugust 1, for a full month1

Nothing is charged at the resume in either case, because the subscriber already paid for those 21 days.

When no paid time is left, Flint collects a new period at the resume instead. That happens after a dunning pause, when the period was never paid, and after a delivery hold pause, when the held cycle was never charged. The subscription is past_due until the payment succeeds; a collection more than 24 hours after that period's billing date starts the new period on the payment day.

An external schedule keeps the dates your integration set.

Skip a renewal#

cURL
curl -X POST https://api.withflintpay.com/v1/subscriptions/sub_1kmn0aExample/skip-cycle \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: skip-sub-ada-001" \
  -d '{"initiated_by": "buyer"}'

Nothing is charged or shipped for the skipped renewal. next_billing_at moves one billing interval later, and the current period grows to cover the skipped one. The anchor stays, so a monthly subscription anchored on the 31st that skips January 31 bills next on February 28, then March 31.

  • It needs an active subscription that isn't set to cancel and has a next_billing_at. Otherwise it returns 409 ACTION_NOT_ALLOWED, reason unsupported_state, or terminal_status when canceled.
  • initiated_by is buyer, merchant (the default), or integration. It records who asked. Send buyer when you skip at the buyer's request. It doesn't apply the store's buyer limits; the buyer route below does.
  • It sends subscription.cycle_skipped. On a subscription that ships, Flint also emails the buyer the skipped date and the next one, worded for who asked.

To skip more than one renewal, call it once per renewal, or pause instead.

Let buyers pause, skip, and resume#

Buyers manage their own subscriptions in Flint's buyer account, or in yours with a customer session:

Build each control from the subscription's buyer_actions, and show it only when its entry has is_available: true:

  • pause. When pause.max_pause_duration_cycles is present, the buyer must send a pause_duration_cycles from 1 to that limit. When it's absent, they can omit the length and pause until they resume.
  • resume. Available on any paused subscription, including one you paused.
  • skip. Unavailable with reason limit_reached once the buyer has skipped the most renewals in a row you allow. The route then returns 409 LIMIT_REACHED, reason consecutive_skips, until the next charged renewal. On an external schedule, a buyer's skip returns reason external_billing_schedule; skip it for them with your API key.

You set the limits in customer_account.buyer_capabilities with PATCH /v1/settings:

cURL
curl -X PATCH https://api.withflintpay.com/v1/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "customer_account": {
      "buyer_capabilities": {
        "pause": {"enabled": true, "max_cycles": 3},
        "skip": {"enabled": true, "max_consecutive_skips": 2},
        "retention_offer": {"kind": "pause_instead", "pause_cycles": 1}
      }
    }
  }'
SettingDefaultControls
pause.enabledtrueWhether buyers can pause. When false, a buyer's pause returns 409 ACTION_NOT_ALLOWED, reason not_offered.
pause.max_cyclesNo limitThe longest pause a buyer can choose, 1 to 12 billing periods. When set, every buyer pause needs a length.
skip.enabledtrueWhether buyers can skip a renewal.
skip.max_consecutive_skipsNo limitHow many renewals in a row a buyer can skip, 1 to 12. Your skips count toward it but aren't bound by it.
retention_offerNo offerWith kind: "pause_instead", a buyer who starts to cancel is first offered a pause of pause_cycles billing periods. They can decline it and cancel. It needs pausing turned on.

buyer_capabilities is replaced as a whole: every field you leave out, such as cancellation_timing, goes back to its default. Read your settings first and send every field you want to keep. Your own API calls aren't bound by these settings. What buyers can do to their subscriptions lists the rest.

How pausing affects the rest of the subscription#

  • Trials. A trialing subscription can't pause or skip. To give a trial more time, move the trial's end with the billing schedule instead.
  • Cancellation. A paused subscription has no period end to cancel at, so cancel it with cancel_immediately: true.
  • Scheduled plan changes. A pending period_end plan change waits for the first charged renewal after the resume. A skip delays it the same way. While a subscription is paused without a resume time, the change's effective_at is null.
  • Prorated changes. A prorated plan or seat change after a resume still prices time at the rate the subscriber paid, so the pause doesn't make the remaining days cheaper or dearer.
  • end_after. While paused without a resume time, a cycles end with cycles left has no expires_at yet, because no charge is scheduled. remaining_cycles still counts them.

Subscriptions that ship#

  • Renewals. A paused subscription creates no renewal orders, so nothing ships. Pausing clears an upcoming_delivery_hold or an inventory_wait on the next renewal.
  • Delivery holds. Pausing a subscription during a delivery hold ends the hold without a charge and pauses with pause_reason: "delivery_action_required". A hold that runs out also pauses the subscription that way, with no end date. Resuming it needs a delivery Flint can quote, then charges and ships right away.
  • Prepaid deliveries. On a plan that bills for several deliveries at once, pause_duration_cycles and a skip count delivery intervals. A skip defers one delivery and the next charge by one delivery interval, and consumes no paid delivery. Resuming while paid deliveries remain charges nothing, and shifts the remaining deliveries and the next charge by the length of the pause. See Prepaid deliveries.

Events#

Test it#

In a sandbox, put the subscription's customer on a test clock. Pause with pause_duration_cycles: 1, advance the clock past scheduled_resume_at, and check that next_billing_at gives back the paid time left at the pause. Test subscriptions and renewals has the clock setup. No account yet? Sign up and try it in your sandbox.

Coming from Stripe Billing#

<!-- Stripe facts from https://docs.stripe.com/billing/subscriptions/pause-payment and https://docs.stripe.com/billing/subscriptions/pause, checked 2026-11-21. -->

Stripe has two features. Pausing payment collection keeps the subscription active and keeps generating invoices, which Stripe keeps as drafts, marks uncollectible, or voids. Pausing the subscription stops invoices, needs flexible billing mode, credits unused time at the pause by default, and on resume can reset the billing cycle anchor and invoice the new period.

A Flint pause is one call that stops billing, sets paused, and on resume restores the paid time left at the pause, with no credit or invoice to reconcile. Buyers can pause, skip, and resume through the API within limits you set. Migrating from Stripe maps the rest of Stripe Billing.

Ready to keep subscribers who need a break? Create a Flint account and pause your first test subscription.

Was this helpful?