You can upgrade or downgrade an active subscription by changing the product associated with it. However, free trials associated with the new product are ignored. To apply a free trial period to an upgraded or downgraded subscription, apply the change from the Activity page.

Modify the primary subscription product path, quantity, next charge date or coupon

An upgrade is when your Monthly recurring revenue increases after the change, else the change is marked as a downgrade. The POST API allows modification of not just the primary product, but also other details on the subscription like dates, coupons, quantity

{
    "subscriptions": [
    {
        "subscription": "subscription-uuid-1",     // Subscription ID to be updated (From Subscription detail page)
        "product": "new-monthly-subscription",     // Catalog product path of the new subscription primary product from the catalog 
        "quantity": 1,                             // quantity of the new product
        "coupons": ["coupon_code"],                // only supports one coupon to be applied, pass an empty array to remove coupon
        "prorate" : true                           // If true the subscription is prorated upto the day of API call - any refunds are applied as credit to the remaining period
    }
  ]
}
{
  "subscriptions": [
    {
      "subscription": "subscription-uuid-2",
      "next": 1448496000000, // or "yyyy-mm-dd",        // Next charge date (UTC epoch time in millis) - Setting next date in past may immediately rebill the subscription
      "end": "2024-12-01",  // or UTC Millis or 0,      // Last charge date will be on or before this date. 0 as unlimited (indefinitely renews) subscription
      "product": "subscription-product-1",
      "quantity": 1,
      "coupons": ["valid_coupon_code"],     // only support one coupon to be applied, pass an empty array to remove coupon
      "prorate": false                      // When implementing proration. *Cannot prorate with updating next charge date
    }, ...
  ]
}

Modify the price or discount for an active subscription without changing the product, programmatically apply a discount without changing the product

{
     "subscriptions":  [
        {
           "subscription":"subscription-uuid-4",
           "pricing":{
              "price":{"USD":10},          // see note below about currency
              "discount":{
                 "type":"amount",
                 "amount":3.5,             // (OR can be "amount" : {"USD":3.50}, )  see note below about currency
                 "duration":"all"          // indefinitely apply discount
              }
           }
        }
     ]
 }
// Note:  If the currency is not specified, the currency of the subscription instance will be used;
// if the currency is specified and differs from the subscription's currency, the amount will be converted to subscription's currency.
{
     "subscriptions":  [
        {
           "subscription":"subscription-uuid-3",
           "pricing":{
              "price": 9.95,                // see note below about currency
              "discount":{
                 "type":"percent",
                 "percentage":5,            // (OR can be "amount" : {"USD":3.50}, )  see note below about currency
                 "duration":2               // (OR "all") - restrict discount to periods specified in duration (2 periods for monthly will give 5% discount for 2 monthly rebills)
              }
           }
        }
     ]
 }
// Note:  If the currency is not specified, the currency of the subscription instance will be used; if the currency is specified and differs to the subscription's currency, the amount will be converted to subscription's currency.

Add or edit subscription addon to an active subscription

A Subscription Addon product path is a standalone non-subscription product path from the catalog - which has been marked in the subscription product as an Add-on Related Offer. Addons renew along with the subscription so the price on the Addon is assumed periodic and not one-time charge.

{
  "subscriptions": [
    {
      "subscription": "subscription-uuid-1",
      "addons": [
        {
          "product": "add-on-seats-being-added-or-updated",  // Catalog product path must be in catalog AND marked as relationship to base/parent subscription product
          "quantity": 20,                                    // update quantity of addon (this can be used for variable component price or usage based pricing like seats, Gigabytes, users, API calls)
          "pricing":{         
             "price": {"USD":5}                              // Addon's pricing (Skip if applying catalog price)                                                             // Can also add discount block but coupons only appliicable at subscription level
          }
        }
      ],
      "prorate": true                                                              // Will prorate the subscription thus far, and apply any credits to the difference being charged (or if downgrading, the credits are refunded as a partial order return)
    }
  ]
}
{
  "subscriptions": [
    {
      "subscription": "subscription-id",
      "addons": [
        {
          "product": "existing-add-on-product-being-removed", // addon must be on the subscription
          "quantity": 0
        }
      ],
      "prorate" : false      // No proration (will only apply change in pricing from next period rebill)
    }
  ]
}

📘

Prorate Flag

Editing a subscription with prorate flag set to true will first calculate the remaining balance on the subscription before the changes are applied, then apply the changes and either deduct the balance from the applicable remainder charges (for upgrades), or refund/credit the buyer for the excess charges (for downgrades).
A proration order is created for the changes made accessible under the subscription detail page on the FastSpring app

Changing a subscription from automatic renewal to manual renewal

Use the Subscriptions POST API to switch auto renewed subscriptions to manual renew - Where there are no payment details stored on file and requires the buyer to pay for each period manually.

{
    "subscriptions": [
    {
        "subscription": "subscription-uuid-x",
        "manualRenew": "true"
    }
  ]
}
Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!