Skip to content
Search Articles/

less than a minute read • Updated an hour ago

Upgrade or downgrade a subscription

How to replace the products in an existing subscription using sub_modify=replace, for use cases like plan changes and auto-ship updates.

To upgrade or downgrade a customer’s subscription, use the sub_modify=replace parameter combined with a sub_token to completely replace the existing subscription’s products with new ones.

By default, loading a sub_token into the cart appends products to the existing subscription. Adding sub_modify=replace changes this behaviour so the existing products are replaced entirely.

How to set it up

  1. 1

    Retrieve the customer’s sub_token from the Foxy admin, API, or Subscription XML Datafeed.

  2. 2

    Build an add-to-cart link or form for the new subscription plan that includes:

    • The new product(s) and pricing

    • sub_token set to the customer’s token

    • sub_modify=replace

For example:

https://YOURSTORE.foxycart.com/cart?
  name=Premium+plan&price=40&sub_frequency=1m
  &sub_token=TOKEN&sub_modify=replace

When the customer completes checkout, their existing subscription products are replaced with the new ones.

Use cases

Plan upgrades and downgrades: Build upgrade and downgrade links for each plan combination. When a customer clicks the link and checks out, their subscription is updated to the new plan.

Auto-ship subscription changes: If a customer has a subscription containing multiple products and wants to change the product mix entirely, use sub_modify=replace to swap out the full set of products in one transaction.

Notes

  • sub_modify=replace does not prorate the subscription. If the customer is mid-period, any price difference between the old and new subscription is not adjusted.

  • To remove an end date from the subscription when replacing it, include sub_enddate=00000000 in the link.

  • Any new subscription products added via a sub_token will automatically have their sub_startdate set to the next scheduled date for that subscription, preventing the customer from being charged again for the current period.

  • PayPal Express (non-Reference Transactions) does not support subscription modification via sub_token. Foxy strongly recommends using the Reference Transaction option for PayPal Express Checkout.

Need Help?

Did this article answer your questions? Need help with anything? Please click below to contact us.