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
Body
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"
Response
200
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"
The retry policy applied when a recurring charge is declined. See Retries.
The optional order enrichment sent at creation, echoed back. See The Subscription Object for its full shape.
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.
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.