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.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.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.Authorizations
Path Parameters
The unique identifier of the subscription.
Body
The subscription plan name (MAX 255; MIN 3).
The subscription plan description (MAX 255; MIN 3).
The unique identifier of the account that will have the subscription plan available to use (MAX 64 ; MIN 36).
Identification of the subscription plan (MAX 255; MIN 3).
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.
255The subscription's country.
Specifies the amount object, with the value of each subscription payment and the used currency.
Specifies the frequency object. Defines the billing frequency for the subscription. Including type and value.
Specifies the billing_cycles object. Defines the number of charges associated to the subscription.
Specifies the customer_payer object to identify the customer.
Specifies the payment_method object. Supported types are CARD and PAYPAL_ENROLLMENT. You can use the token, the vaulted_token, or the card information through the card object.
Specifies 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 Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
Response
200
"0c7fed3e-ee0d-4d34-9547-778be4ec0798"
"Test Subscription"
"493e9374-510a-4201-9e09-de669d75f256"
"US"
"Subscription Test"
"subscription-ref-merchant-AA01"
"ACME SUBSCRIPTION"
"ACTIVE"
The plan change scheduled for the next billing cycle, or null when none is pending.
"2024-09-30T12:04:23.265372Z"
"2024-09-30T12:04:23.265372Z"