Change a subscription plan

Schedule a plan change for a subscription. The change is applied at the end of the current billing cycle.

Use cases​

  • Plan upgrades: Moving a customer to a higher-tier plan with more features or capacity.
  • Plan downgrades: Moving a customer to a lower-tier plan that better fits their usage and budget.
  • Customer requests: Accommodating a customer's request to switch to a different plan variation.

How it works​

When you schedule a plan change, the subscription continues operating under its current plan variation until the current billing cycle ends. At that point, the next cycle is created under the new plan variation.

  • Scheduled change: The plan change is scheduled to take effect at_cycle_end. The current cycle completes normally, and the new plan variation applies starting from the next cycle.
  • Plan variation phases: Some plan variations are divided into phases - distinct pricing or duration periods within a single variation. If the target plan variation has multiple phases, use plan_variation_phase_id to specify which phase to start from. If omitted, the change starts from the first phase.
  • Trial periods: If the target plan variation includes a trial period, it is skipped when changing plans. Trial periods only apply when a subscription is first created.
  • Subsequent cycles: After the transition, future cycles follow the cadence and pricing defined by the new plan variation.

Request​

Path parameters
Path parameters

The ID of the subscription.

Header parameters
Header parameters

Example: "Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq"

This parameter accepts the Merchant API Secret key to authorise requests coming from the merchant's backend.

It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a Bearer token.

Info

For more information, see: Authentication

Possible values: [2023-09-01, 2024-05-01, 2024-09-01, 2025-10-16, 2025-12-04, 2026-03-12, 2026-04-20]
Example: "2026-04-20"

The version of the Merchant API, specified in YYYY-MM-DD format.

If not specified, you will receive an error.

Info

For more information about API versioning, see: API versions.

Request body
Body object

Unique identifier for the subscription plan variation.

Unique identifier for the subscription plan phase.

Possible values: [at_cycle_end]
Example: "at_cycle_end"

When the plan change should take effect.

ValueDescription
at_cycle_endThe change is applied at the end of the current billing cycle.

Possible values: [customer_request, merchant_request]
Example: "customer_request"

Default value: merchant_request

The reason for the scheduled action. This field is informational and does not affect how the action is processed.

ValueDescription
customer_requestThe action was requested by the customer.
merchant_requestThe action was initiated by the merchant.

Response​

Plan change scheduled successfully
Was this page helpful?