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.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.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.
Schedules a move to another plan, effective at the next billing cycle. The subscription must be ACTIVE or TRIALING and already on a plan; the target plan must be ACTIVE. Only one change can be pending at a time. Send "plan_change": null to undo a pending change before it applies. 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.
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"