Pause Subscription
Pauses an active subscription, allowing it to later resume or be canceled.
status to PAUSED. This status can be changed to ACTIVE or CANCELED.
Pause for a set time
A pause is open-ended by default: the subscription staysPAUSED until you resume it. Sending a body with a duration schedules the resume in advance, and the subscription returns on its own when that moment arrives.
Give the duration one of two ways, never both:
pause_cycles— an integer from 1 to 3, counted from the pause in the subscription’s own frequency.pause_until— an RFC 3339 instant. It must be in the future and fall beforeavailability.finish_atwhen the subscription has one.
billing_cycle_behavior is optional and decides the billing date when the subscription resumes, with the same KEEP/RESTART meanings as on Resume Subscription: KEEP (the default) holds the original billing date, RESTART re-anchors from the resume. Sending it without pause_cycles or pause_until is accepted — an open-ended pause that just records the behaviour for whenever the subscription is later resumed.
reason is an optional free-form string, at most 255 characters, stored on the subscription’s reason field. A later GET on the subscription echoes it back, and it stays until something else overwrites it — a resume that sends its own reason, for example.
pause_cycles is resolved once, at the moment of the pause: the resolved instant is the pause instant plus pause_cycles × the subscription’s frequency. The subscription then carries that instant as pause_until on every later read while it stays paused — a pause given in cycles and one given as a date are indistinguishable afterwards. For example, { "pause_cycles": 1 } on a monthly subscription paused at 2026-09-15T15:54:18Z resolves to pause_until: "2026-10-15T15:54:22.780166Z".
What happens while it is paused, and when it returns
No cycle is charged during the pause. While a duration is running, the subscription carriespause_until on every read; it returns to the status it was billing under on its own, within about a minute of that instant, and a subscription.resume webhook arrives carrying resume_reason: SCHEDULED. A manual resume before that instant cancels the schedule — call Resume Subscription yourself at any time to end the pause early. If the automatic resume cannot be completed after its retries, the subscription stays PAUSED and a subscription.auto_resume_failed event is sent instead.
reason field, are available to organizations enabled for it; contact Yuno.Errors
Authorizations
Path Parameters
The unique identifier of a subscription.
Body
Pause for this many of the subscription's own billing cycles, starting from the pause. Resolved once, at the pause, into a stored pause_until. Cannot be combined with pause_until.
1 <= x <= 31
Pause until this RFC 3339 instant. Must be in the future and before availability.finish_at. Cannot be combined with pause_cycles.
"2026-09-22T15:47:04.964Z"
What happens to the billing anchor when the subscription resumes (manually or automatically). KEEP (default): the original anchor is walked forward by whole periods it missed. RESTART: the anchor re-anchors to the moment of the resume. Sending it without pause_cycles or pause_until is accepted — an open-ended pause that just records the behaviour for whenever the subscription is later resumed.
KEEP, RESTART "RESTART"
Free-form reason for the pause, stored on the subscription's reason field. At most 255 characters; blank is treated as absent.
255"customer requested a break"
Response
200
"7304911d-5df9-429e-8488-ad41abea1a4c"
"sub_001"
"streaming service"
"2404911d-5df9-429e-8488-ad41abea1a4b"
"001_marzo_23"
"PAUSED"
"1904911d-5df9-429e-8488-ad41abea1a4d"
The payment method the subscription charges. A single object, not a list.
List of payment IDs created by the subscription. Omitted from the response when the subscription has no payments.
"2023-12-16T20:46:54.786342Z"
"2023-12-16T21:00:54.786342Z"
The subscription's country (ISO 3166-1 alpha-2).
"US"
Soft descriptor.
"ACME SUBSCRIPTION"
Start of the billing period the subscription is currently in, one cadence before current_period_end. Inside a trial or any other plan phase it follows that phase's cadence. A terminal subscription (CANCELED or COMPLETED) keeps its final window rather than going null. Null only for a subscription with no recurring cadence. Always returned together with current_period_end.
"2023-01-16T20:00:00.912480Z"
End of the billing period the subscription is currently in. Equal to billing_cycles.next_at. Always returned together with current_period_start.
"2023-02-16T20:00:00.786342Z"
Only present on subscriptions billed on a fixed date instead of a frequency; mutually exclusive with frequency.
Trial period.
The optional order enrichment sent at creation, echoed back. See The Subscription Object for its full shape.
Whether the subscription waited for its first payment to succeed before activating. false by default.
false
Free-form reason for the subscription's current status, when one was recorded; null otherwise.
"merchant request"
How many days before the next billing date the subscription.close_to_renewal webhook is sent. null means no renewal notification is sent.
3
Subscription agreement id.
"sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa"
When the subscription was canceled. Only set once it reaches CANCELED; null otherwise.
"2023-12-16T20:46:54.786342Z"
What triggered the cancellation: MERCHANT, SYSTEM, PLAN_CHANGE or RETRIES_EXHAUSTED. Only set once the subscription reaches CANCELED; null otherwise. Treat as open-ended — handle unrecognized values gracefully.
"MERCHANT"
When the subscription completed or expired. Only set once it reaches COMPLETED; null otherwise.
"2024-12-16T20:46:54.786342Z"
Only present when the subscription is linked to a plan.
"00000000-0000-4000-8000-000000000001"
Only present on plan-linked subscriptions. The moment the plan was attached — at creation from a plan, migration onto a plan, or a plan change.
"2023-12-16T20:46:54.786342Z"
Only present when this subscription was created by a plan change (switching an existing subscription to a different plan).
The linked plan's phase definitions, as the plan declares them — including the terminal REGULAR phase. Only present on plan-linked subscriptions whose plan has phases. This is the plan's own ladder, not this subscriber's snapshot: for what was pinned for this subscription at creation, use billing_phases.
Only present on plan-linked subscriptions.
"REGULAR"
When the phase named by current_phase hands over to the next one — for a subscription in its trial, when it switches to the regular price. End of the last billing period the phase covers, so on the final period of a trial it equals current_period_end. Null for a subscription with no plan and for one that already left the phase ladder.
"2023-03-16T20:00:00.786342Z"
Only present on plan-linked subscriptions whose plan has phases. Contains the leading TRIAL phases only, snapshotted at creation — the terminal REGULAR phase is never included, since its price isn't pinned and instead resolves from the plan at every billing. current_phase: "REGULAR" is how you know the ladder is exhausted.
The plan change scheduled for the next billing cycle, or null when none is pending. Schedule one with the plan_change block on Update Subscription.
The stored refund rule used to resolve a CUSTOM cancel refund when the cancel request sends no refund_amount of its own. Present only when one is configured; omitted, not null, otherwise. Available to organizations enabled for it; contact Yuno.
When the subscription is scheduled to resume automatically. Present only on a subscription currently paused with a duration (pause_cycles or pause_until sent at pause); absent, not null, on every other read.
"2026-10-15T15:54:22.780166Z"
null when no cancellation is pending.
null when refund was NONE or omitted. Present on the cancel response and on every later read once computed.
Present only when the current billing cycle is PAST_DUE and has not settled.