Change the product in a subscription

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.

Subscription Update Flags

The following flags modify behavior when used in conjunction with product paths as part of a subscription change request.

Prorate

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

Preview

The preview flag in combination with prorate flag returns a response of proratable charges and credits for a recent and eligible plan change.

ProratePreviewBehavior
truefalseThe POST to subscriptions endpoint calculates the charges and credits resulting from the subscription changes, prorate the changes, and commits the changes accordingly. It returns a response based on the success/failure of the subscription change update.
truetrueThe POST to subscriptions endpoint should calculate the charges and credits resulting from the subscription changes, prorate the changes and return the estimates as a response. It will NOT commit the changes.
falsetrueNot Supported
falsefalseThe POST to subscriptions endpoint modifies the subscription as requested. It does NOT prorate the proposed changes. It also does NOT return a response containing a preview of the changes. It will return a response based on the success/failure of the subscription change update.

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-id-1",
           "pricing":{
              "price": {"USD":10}
           }
        }
     ]
 }
{
     "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)
    }
  ]
}

Proration Preview

You can request a preview of prorated charges for a subscription that is eligible for proration. For a list of conditions when proration is not applicable, see Managing Active Subscriptions

To request a preview for a prorated subscription, use the example request shown below for an eligible subscription id.

{
    "subscriptions": [ 
      {
        "subscription": "subscription-id",     // Subscription ID to be updated (From Subscription detail page)
        "prorate" : true,                      // If true the subscription is prorated upto the day of API call - any refunds are applied as credit to the remaining period
        "preview" : true
      }
  ]
}

Responses

See the following code snippets for examples of successful responses in case of a charge, or in case of a refund/credit

{
    "subscriptions": [
        {
            "action": "subscription.update",
            "result": "success",
            "subscription": "tbELUuXiSN-kDUcBIW6zIw",
            "prorated": true,
            "proration": {
                "productPath": "add-on-subscription",
                "currency": "USD",
                "nextPeriodStartDate": "2022-11-01T00:00:00.000Z",
                "nextPeriodEndDate": "2022-11-30T00:00:00.000Z",
                "previousRemainingDays": 29.0,
                "periodPastDays": 1.0,
                "nextRemainingDays": 29.0,
                "regularPeriod": {
                    "unit": "MONTH",
                    "unitCount": 1
                },
                "nextPricePerPeriod": {
                    "amount": 410.0,
                    "period": {
                        "count": 1,
                        "unit": "month"
                    }
                },
                "previousPricePerPeriod": {
                    "amount": 205.0,
                    "period": {
                        "count": 1,
                        "unit": "month"
                    }
                },
                "utilizedAmount": 6.83,
                "creditAmount": 198.17,
                "proratedAmount": 396.34,
                "chargeAmount": 198.17
            }
        }
    ]
}
{
    "subscriptions": [
        {
            "action": "subscription.update",
            "result": "success",
            "subscription": "athBG1DPTFuOcw0iwPwi4A",
            "prorated": true,
            "proration": {
                "productPath": "japan-sub",
                "currency": "USD",
                "nextPeriodStartDate": "2022-11-03T00:00:00.000Z",
                "nextPeriodEndDate": "2022-11-09T00:00:00.000Z",
                "previousRemainingDays": 30.0,
                "periodPastDays": 0.0,
                "nextRemainingDays": 7.0,
                "regularPeriod": {
                    "unit": "WEEK",
                    "unitCount": 1
                },
                "nextPricePerPeriod": {
                    "amount": 10.0,
                    "period": {
                        "count": 1,
                        "unit": "week"
                    }
                },
                "previousPricePerPeriod": {
                    "amount": 100.0,
                    "period": {
                        "count": 1,
                        "unit": "month"
                    }
                },
                "utilizedAmount": 0.0,
                "prorateAdjustment": 100.0,
                "proratedAmount": 10.0,
                "refundAmount": 90.0
            }
        }
    ]
}

Response Parameters

Parameter NameDescription
proratedAdjustmentPertains to the old subscription item replaced or removed as part of a recent plan change
This is the prorated price for the unused portion of the item
proratedAmountPertains to the new subscription item added as part of a recent plan change
Prorated price of the new item
refundAmountAmount credited to the customer for the unused portion of the changed item by issuing a refund
utilizedAmountPertains to the old subscription item replaced or removed as part of the recent plan change
This is the prorated amount for the used portion of the item

Error Responses

{
    "subscriptions": [
        {
            "action": "subscription.update",
            "result": "error",
            "subscription": "athBG1DPTFuOcw0iwPwi4A",
            "prorated": false,
            "proration": "Not currently supported"
        }
    ]
}
{
    "subscriptions": [
        {
            "action": "subscription.update",
            "subscription": "ZxMOne-aQ9qY3ykoamuJ-A",
            "result": "error",
            "error": {
                "subscription.prorate": "Items not eligible for proration"
            }
        }
    ]
}
{
    "subscriptions": [
        {
            "action": "subscription.update",
            "subscription": "ZxMOne-aQ9qY3ykoamuJ-A",
            "result": "error",
            "error": {
                "subscription.prorate": "Unable to prorate"
            }
        }
    ]
}

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
Authorization
Basic
base64
:
Click Try It! to start a request and see the response here!