Update Subscription
Updates a subscription’s fields, including retroactively adding stored credential usage data.
PATCH endpoint to set payment_method.card.usage retroactively to fix the issue.plan_change block to move a subscription to another plan effective at its next billing cycle — no proration, no mid-cycle charge. The subscription must be ACTIVE or TRIALING and already on a plan; the target plan must be active and only one change can be pending at a time. Send "plan_change": null to undo a pending change; omitting the field never touches it. The pending change is returned as pending_plan_change on this endpoint and on the subscription object, and the subscription.plan_change_scheduled, subscription.plan_change_canceled and subscription.plan_changed webhooks track its lifecycle.amount, frequency, billing_date and country are managed by the plan and cannot be sent for a plan-linked subscription — combining any of them with plan_change returns 400."effective": "IMMEDIATE" inside plan_change to apply the move in this call instead of scheduling it: the subscription keeps its id, the new plan’s price bills from the next charge, and — unlike a scheduled change — this works even in the final billing cycle. An immediate change while another change is pending returns 409 PLAN_CHANGE_ALREADY_SCHEDULED; undo the pending one first with "plan_change": null.billing_cycle_behavior decides what happens to the billing anchor when the plan changes in place:KEEP(default — omitting the field behaves identically) — the next charge date is untouched; only the price changes.RESTART— the next charge re-anchors to the moment of the change plus the new plan’s frequency. Only the anchor resets: billing cycle counters, the retry configuration and the subscription’s status all survive.RESTARTrequireseffective: IMMEDIATEand returns400with a scheduled change;KEEPalongside a scheduled change is accepted and simply schedules the change as usual — a scheduled change never moves the anchor anyway.
subscription.plan_changed webhook at the moment of the call — subscription.plan_change_scheduled never fires for it, and pending_plan_change stays null throughout.billing_cycle_behavior is write-only — it is accepted on the request and never echoed in any response.On a monthly subscription created without an explicit frequency.monthly_billing_day, RESTART sets that field to the day of the restart, and every future renewal reads it — restarting on the 15th bills on the 15th from then on, not only for the next cycle. A subscription that already declares a billing day keeps it: the date does not move to the restart day, only the time of day is re-anchored. The value is returned on the subscription object, so it can be read back after the change. The same rule applies to RESTART on Resume Subscription — it is one rule, on both endpoints.billing_cycle_behavior is available as a top-level field on this endpoint, typically combined with a frequency change in the same call — for example, moving a subscriber from monthly to yearly and restarting the cycle from today. The same KEEP/RESTART semantics apply, and on a subscription that has not started yet the re-anchored date clamps to its availability.start_at.Placement rules: on a plan-linked subscription the top-level field returns 400 (the anchor is managed through plan_change), and combining the top-level field with a plan_change block returns 400 — use plan_change.billing_cycle_behavior instead. A PAUSED subscription returns 409 INVALID_SUBSCRIPTION_STATUS: a restart is accepted while the subscription is ACTIVE, TRIALING or PAST_DUE — or while it is still CREATED, where (unlike plan_change) the request is allowed and the re-anchored date clamps to availability.start_at. A top-level restart emits no webhook — read the new anchor from the subscription object.promotion with an id or a code to apply a promotion that is attached to the subscription’s plan. The subscription must be ACTIVE or TRIALING. The discount takes effect from the next charge. The response includes the promotion object. Applying a promotion while another one is active replaces it: the current one ends with end_reason REPLACED, and the new one starts at 0 cycles used.promotion must send nothing else. Combined with plan_change, it answers 400 INVALID_PARAMETERS with the message A promotion and a plan change cannot be sent in the same update, so send them in two requests. Combined with any other field, such as name or metadata, it answers 400 BAD_REQUEST with the message a promotion must be sent alone; send the other changes in a separate request. Nothing is changed in either case. Send the fields in separate requests.plan_change decide what happens to an active promotion:promotion_behavior:KEEP(default) keeps the promotion, with its remaining cycles, on the new plan.ENDends it withend_reasonPLAN_CHANGE. It is ignored when there is no active promotion.apply_new_plan_promotion:true(default) applies the new plan’sAUTOMATICpromotion, if it has one, and ends the current promotion withPLAN_CHANGE.falseleaves the new plan’s promotion unapplied, andpromotion_behaviordecides what happens to the current one.
Plan change errors
Each of the409 and 422 errors below carries a current_status field alongside code and messages, holding the subscription’s status at the moment the request was rejected. The rejected request makes no change.
CANCELED or COMPLETED subscription is rejected earlier with 400 INVALID_STATE, which does not carry current_status.
Validation problems in the block itself — a missing plan_id, an unsupported effective, a target plan in another currency, or a HONOR_PHASES ladder longer than the remaining billing cycles — return 400 BAD_REQUEST without current_status. The same applies to billing_cycle_behavior placement mistakes: RESTART without effective: IMMEDIATE, the top-level field combined with plan_change, or the top-level field on a plan-linked subscription each return 400 BAD_REQUEST with a message naming the fix. Where an invalid billing_cycle_behavior value is caught depends on its position: the top-level field is rejected at the API edge as 400 INVALID_PARAMETERS ("The field 'billing_cycle_behavior' has an invalid value."), while a bad value nested inside plan_change reaches the engine and returns 400 BAD_REQUEST (e.g. "RESET is invalid for plan_change.billing_cycle_behavior field") — treat both codes as validation failures.
One exception to the plan-change error table above: PLAN_CHANGE_NOT_AVAILABLE applies to scheduled changes only. An IMMEDIATE change does not need an upcoming cycle, so it is accepted in the final billing cycle.
Setting a refund rule
refund_rule configures how a CUSTOM refund is sized when a later cancel request carries no refund_amount of its own. It is set here or on create, and sending "refund_rule": null clears it.
PERCENT and FIXED are exclusive — a rule carrying both percent and amount is rejected, and so is one carrying neither for its own type. A FIXED rule’s amount.currency must equal the subscription’s own currency; sending a mismatched one returns 400 REFUND_RULE_CURRENCY_MISMATCH — "refund_rule.amount.currency USD must match the subscription currency COP." (currencies vary with the request).
The same check applies when the update changes the subscription’s own amount.currency while a FIXED rule in the old currency is still stored, without touching refund_rule in the same request — 400 REFUND_RULE_CURRENCY_MISMATCH — "stored refund rule is FIXED in COP; send refund_rule in USD or refund_rule: null in the same request." (naming the currencies involved). Resend the rule in the new currency, or clear it, in the same request that changes amount.currency.
After a clear, refund_rule is omitted from the subscription object on the response — never sent back as null.
See Cancel Subscription for how the rule is used, and the Subscription object for the field reference. Available to organizations enabled for it; contact Yuno — for an organization that is not enabled, sending refund_rule (including null) is silently ignored, and nothing changes.Authorizations
Body
Statement descriptor shown on the cardholder's bank statement. Updating it changes the descriptor applied to subsequent rebills generated by the subscription engine. Length and formatting limits vary by provider (for example, Unlimit truncates to 22 characters and Airwallex to 30). Worldpay does not read this field; it builds the statement narrative from payment_description instead.
255Specifies the availability object. Defines a date interval based on starting and ending dates when the subscription is available to use. If this object is omitted from the request, the availability dates are left unchanged. When it is included, omitting finish_at (or sending it as null) removes any previously set end date; omitting start_at leaves the current start date unchanged.
The retries configuration to apply going forward. Accepts the same object as Create Subscription — including strategy and schedule — except cancel_on_exhausted_retries, which is create-only. Changes apply the next time retries are scheduled: a billing cycle already running its retries finishes on the configuration it started with, and the update takes effect from the next cycle.
Moves the subscription to another plan. effective: NEXT_BILLING_CYCLE (the default) schedules the change for the next renewal — no proration, no mid-cycle charge. effective: IMMEDIATE applies the change in place, in this call: the subscription keeps its id, the new plan's price bills from the next charge, and billing_cycle_behavior decides what happens to the billing anchor. The subscription must be ACTIVE or TRIALING and already on a plan; the target plan must be ACTIVE. For scheduled changes only one can be pending at a time — send "plan_change": null to undo it before it applies (an IMMEDIATE change while another is pending returns 409). amount, frequency, billing_date and country are managed by the plan and cannot be sent for a plan-linked subscription — combining any of them with plan_change returns 400.
For subscriptions that are not linked to a plan: re-anchors billing in the same way as plan_change.billing_cycle_behavior, typically combined with a frequency change in the same call (e.g. monthly to yearly, restarting the cycle from today). KEEP (default): the next charge date is untouched. RESTART: re-anchors the next charge to now plus the (possibly updated) frequency; the anchor alone resets — cycle counters, the retry configuration and the subscription status survive. On a subscription that has not started yet (CREATED — accepted here, unlike plan_change), the anchor clamps to its start date. Rules: cannot be combined with plan_change (400 — use the nested field); on a plan-linked subscription this field returns 400 (managed through plan_change); a PAUSED subscription returns 409 INVALID_SUBSCRIPTION_STATUS. Write-only: never echoed in any response.
KEEP, RESTART Applies a promotion attached to the subscription's plan. Send exactly one of id or code. The subscription must be ACTIVE or TRIALING, and the discount takes effect from the next charge. Applying a promotion while another one is active replaces it: the current one ends with end_reason REPLACED, and the new one starts at 0 cycles used. See Promotions on subscription plans.
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.
The copy of the promotion stored on the subscription. See The Subscription Promotion Object.