Change the recurring plan

Update the price schedule on an active subscription. The new price schedule takes effect immediately upon the API call. The price array requires at least two objects: one with repeat: false for the initial charge, and one with repeat: true for the recurring charges.

curl --request PUT \
  --url https://api.centrobill.com/subscription/{id} \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "price": [
      {
        "offset": "30d",
        "amount": 14.99,
        "currency": "USD",
        "repeat": true
      }
    ]
  }'

Request fields:

A successful response returns the updated subscription object, price object, and metadata if passed.

Note: Same SKU building rules apply as described here.

Plan changes: upgrade, downgrade, and mid-cycle swaps

PUT /subscription/{id} rewrites the subscription's recurring price schedule. The new schedule takes effect when the API call is executed, depending on the newly passed price schema.

To charge the customer immediately as part of the plan change, include a price entry with offset: "0d". To start charging the new amount on a specific day, set the first offset to {desired date} number of days and the second offset to the recurring interval (for example, "30d" for a monthly plan).

Upgrade example: charge the difference immediately, then bill monthly:

curl --request PUT \
  --url https://api.centrobill.com/subscription/{id} \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "price": [
      {
      "repeat": false,
      "offset": "0d",
      "amount": 9.99,
      "currency": "USD"
    },
    {
      "repeat": true,
      "offset": "30d",
      "amount": 9.99,
      "currency": "USD"
    }
  ]
}

Downgrade example: apply new lower price from next renewal only:

curl --request PUT \
  --url https://api.centrobill.com/subscription/{id} \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "price": [
      {
        "offset": "30d",
        "amount": 8.00,
        "currency": "USD",
        "repeat": true
      }
    ]
  }'

Proration

Centrobill does not calculate or apply proration automatically. If you want to credit or charge the customer for the unused or additional portion of the current billing period, calculate the amount in your system and issue it separately:

• To credit the customer for unused time: use POST /payment/{id}/credit against the most recent transaction
• To charge an additional upgrade fee: include an offset: "0d" price entry in the plan change request, as shown in the upgrade example above

Cancel and recreate vs. plan change

For most plan changes, PUT /subscription/{id} is the right approach, it rewrites the price schedule on the existing subscription with no service gap.

If your business logic requires treating an upgrade or downgrade as a distinct new subscription (for example, for revenue attribution, entitlement tracking, or your own billing records), you can cancel the existing subscription and create a new one instead. There is no substantial delay between cancelling and creating a new subscription. Set cancelDate to null to cancel the existing subscription immediately before initiating the new payment.