Skip to main content

Upgrade and downgrade

Changing the plan on an active subscription is done by posting a new set of items to the subscription's items endpoint. The request takes two flags that control when the change takes effect and whether the partial cycle is prorated.

Endpoint​

POST /v1/public-api/organizations/{organizationId}/subscriptions/{subscriptionId}/items

Posting a new plan to this endpoint replaces the subscription's current items.

Request body​

{
  "items": [
    { "plan": { "id": "plan_new" } }
  ],
  "retainRenewalTime": "retain",
  "proRataCredit": true
}
FieldTypeDescription
itemsarrayThe new set of items. Each item is { plan: { id } }, the same shape used when creating a subscription.
retainRenewalTimestring ("reset" or "retain")Controls when the new plan takes effect. "retain" keeps the existing renewal date so the change applies within the current cycle. "reset" starts a fresh cycle from the change date.
proRataCreditbooleanWhether the partial cycle on the old plan is prorated against the new plan. See Proration.

What changes, what stays​

  • Renewal date: kept when retainRenewalTime: "retain", reset to the change date when retainRenewalTime: "reset".
  • Trial: if the subscription is still in a trial period, switching plans does not extend the trial — the trial runs out as scheduled.
  • Payment instrument: unchanged. The new plan is charged against the same instrument as the original subscription.

Charge or credit at change time​

Whether the customer is charged or credited at the moment of change, and the exact amount, depends on the combination of retainRenewalTime and proRataCredit, plus the prices of the old and new plans. Confirm the resulting amount in the response from the plan-change call before relying on it for accounting. See Proration for how proRataCredit controls the calculation.