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. Currently, only card as available as payment methods. You can use the card token, the vaulted_token or the card information using 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.
Specified the 'retries' object. If we need to retry declined transactions in Yuno and the amount if necessary. If modified, the retries will apply to the next payment intent.
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"