/subscriptions

Last modified August 22, 2016

Subscription Instances

All API endpoints work with subscription instances which are represented by unique identifiers. Those identifiers can be obtained by subscribing to Webhooks or by requesting all subscriptions using GET /subscriptions.

Get all subscription instances

GET /subscriptions?page=2&limit=15

Response Example
{
  "action": "subscription.getall",
  "result": "success",
  "nextPage": 3,
  "subscriptions": [
    "khyNPLY3TYiQhBfHyjZINg",
    "w46bQ2-gTayzJfFXbV1VWg",
    "86cFjtgCRlSmOPbLcX_mCA",
    "v0yPCSTLSyarVe9NlNalSA",
    "FWhWZ3b6StyfiJ_GnyHswQ",
    "A5xx9TF_R26PcCMdagAC8Q",
    "pgNumDwTSbaLeNY6FtUF3Q",
    "IK2eD1nvSP-L3yilE6K7BQ",
    "iZ8qUO-MSwuezTn_elPb3g",
    "gLspcP3NRqmdOm615HSTig",
    "HYKxh1JfTcyUhTgJxAxfWg",
    "1RkJixj_QKOg_c7G_wGIZA",
    "LiPzVuKnT2Go1WWteQkZtw",
    "V5wXtLilSsWGkMYSiLVy2g",
    "MseNZ_LBRu63R84k9knIKg"
  ]
}

Get one or more subscription instances

GET /subscriptions/{id1}[,{id2},{id3},...]

Response Example
{
  "action": "subscription.get",
  "result": "success",
  "subscriptions": [
    {
      "id": "0RH-6ZKhRxSN-NdthqyL4Q",
      "subscription": "0RH-6ZKhRxSN-NdthqyL4Q",                         // subscription ID
      "active": true,                                                   // false if subscription has been deactivated
      "state": "trial",                                                 // current status of the subscription: "active", "overdue", "canceled", "deactivated", "trial"
      "changed": 1471902101759,                                         // date of the most recent update to this subscription record, in milliseconds
      "changedValue": 1471902101759,
      "changedInSeconds": 1471902101,                                   // date of the most recent update to this subscription record, in seconds
      "changedDisplay": "8/22/16",                                      // date of the most recent update to this subscription record, formatted for display based on the language in which the order was processed, as selected by the customer
      "live": false,                                                    // true if not a test order
      "currency": "USD",
      "account": "0y6eieIDRS2MQs08iQrDmw",                              // FastSpring-generated customer account ID
      "product": "falcon-monthly-subscriptions",
      "sku": "furious10",
      "display": "Falcon Monthly Subscription",
      "quantity": 1,
      "adhoc": false,                                                   // true if managed subscription
      "price": 14.95,
      "priceDisplay": "$14.95",
      "priceInPayoutCurrency": 14.95,
      "priceInPayoutCurrencyDisplay": "$14.95",
      "discount": 3.74,
      "discountDisplay": "$3.74",
      "discountInPayoutCurrency": 3.74,
      "discountInPayoutCurrencyDisplay": "$3.74",
      "subtotal": 11.21,
      "subtotalDisplay": "$11.21",
      "subtotalInPayoutCurrency": 11.21,
      "subtotalInPayoutCurrencyDisplay": "$11.21",
      "attributes": {                                                   // optional custom product attributes
        "CustomAttribute1": "CustomValue1",
        "CustomAttribute2": "CustomValue2"
      },
      "next": 1472083200000,                                            // date of the next event (e.g. charge, notification, deactivation, trial period end date), in milliseconds
      "nextValue": 1472083200000,
      "nextInSeconds": 1472083200,                                      // date of the next event (e.g. charge, notification, deactivation, trial period end date), in seconds
      "nextDisplay": "8/25/16",                                         // date of the next event, formatted for display based on the language in which the order was processed, as selected by the customer
      "end": null,
      "endValue": null,
      "endInSeconds": null,
      "endDisplay": null,
      "deactivationDate": null,                                         // scheduled deactivation date if rebill payment failed, see cancellation setting
      "deactivationDateValue": null,
      "deactivationDateInSeconds": null,
      "deactivationDateDisplay": null,
      "sequence": 1,                                                    // sequence number of the current period
      "periods": null,                                                  // expected total number of periods, if limited (null = unlimited)
      "remainingPeriods": null,
      "begin": 1471824000000,
      "beginValue": 1471824000000,
      "beginInSeconds": 1471824000,
      "beginDisplay": "8/22/16",
      "intervalUnit": "month",                                          // "adhoc", "day", "week", "month", "year"
      "intervalLength": 1,
      "nextChargeCurrency": "USD",
      "nextChargeDate": 1472083200000,                                  // date of the next scheduled charge, in milliseconds
      "nextChargeDateValue": 1472083200000,
      "nextChargeDateDisplay": "8/25/16",                               // date of the next scheduled charge, formatted for display based on the language in which the order was processed, as selected by the customer
      "nextChargeTotal": 11.21,
      "nextChargeTotalDisplay": "$11.21",
      "nextChargeTotalInPayoutCurrency": 11.21,
      "nextChargeTotalInPayoutCurrencyDisplay": "$11.21",
      "nextNotificationType": "TRIAL_REMINDER",
      "nextNotificationDate": 1471824000000,
      "nextNotificationDateValue": 1471824000000,
      "nextNotificationDateInSeconds": 1471824000,
      "nextNotificationDateDisplay": "8/22/16",
      "trialReminder": {
        "intervalUnit": "day",
        "intervalLength": 3
      },
      "paymentReminder": {                                              // configured at the subscription product level via the Pricing field
        "intervalUnit": "day",
        "intervalLength": 1
      },
      "paymentOverdue": {                                               // configured at the subscription product level via the Pricing field
        "intervalUnit": "week",
        "intervalLength": 2,
        "total": 1,
        "sent": 0
      },
      "cancellationSetting": {                                          // configured at the subscription product level via the Pricing field
        "cancellation": "AFTER_LAST_NOTIFICATION",                      // or AFTER_PAYMENT_FAILURE if no paymentOverdue notices are configured
        "intervalUnit": "week",
        "intervalLength": 1
      },
      "discounts": [                                                    // information about the coupon applied to the subscription order, if any
        {
          "discountPath": "summer-promotion",
          "discountDuration": null,
          "percentValue": 25
        }
      ],
      "instructions": [
        {                                                               // exists only if there is a free trial
          "type": "trial",
          "periodStartDate": 1471824000000,
          "periodStartDateValue": 1471824000000,
          "periodStartDateInSeconds": 1471824000,
          "periodStartDateDisplay": "8/22/16",
          "periodEndDate": 1471996800000,
          "periodEndDateValue": 1471996800000,
          "periodEndDateInSeconds": 1471996800,
          "periodEndDateDisplay": "8/24/16",
          "discountDurationUnit": "day",
          "discountDurationLength": 3,
          "discountPercent": 100,
          "discountPercentValue": 100,
          "discountPercentDisplay": "100%",
          "unitDiscount": 14.95,
          "unitDiscountDisplay": "$14.95",
          "unitDiscountInPayoutCurrency": 14.95,
          "unitDiscountInPayoutCurrencyDisplay": "$14.95",
          "discountTotal": 14.95,
          "discountTotalDisplay": "$14.95",
          "discountTotalInPayoutCurrency": 14.95,
          "discountTotalInPayoutCurrencyDisplay": "$14.95",
          "total": 0,
          "totalDisplay": "$0.00",
          "totalInPayoutCurrency": 0,
          "totalInPayoutCurrencyDisplay": "$0.00",
          "price": 14.95,
          "priceDisplay": "$14.95",
          "priceInPayoutCurrency": 14.95,
          "priceInPayoutCurrencyDisplay": "$14.95",
          "priceTotal": 14.95,
          "priceTotalDisplay": "$14.95",
          "priceTotalInPayoutCurrency": 14.95,
          "priceTotalInPayoutCurrencyDisplay": "$14.95",
          "unitPrice": 0,
          "unitPriceDisplay": "$0.00",
          "unitPriceInPayoutCurrency": 0,
          "unitPriceInPayoutCurrencyDisplay": "$0.00"
        },
        {                                                              // exists only if there is a product-level discount
          "type": "discounted",
          "periodStartDate": 1472083200000,
          "periodStartDateValue": 1472083200000,
          "periodStartDateInSeconds": 1472083200,
          "periodStartDateDisplay": "8/25/16",
          "periodEndDate": null,
          "periodEndDateValue": null,
          "periodEndDateInSeconds": null,
          "periodEndDateDisplay": null,
          "discountIntervalUnit": "month",
          "discountIntervalLength": 1,
          "discountDuration": null,
          "discountDurationUnit": "month",
          "discountDurationLength": null,
          "unitDiscount": 3.74,
          "unitDiscountDisplay": "$3.74",
          "unitDiscountInPayoutCurrency": 3.74,
          "unitDiscountInPayoutCurrencyDisplay": "$3.74",
          "discountPercent": 25,
          "discountPercentValue": 25,
          "discountPercentDisplay": "25%",
          "discountTotal": 3.74,
          "discountTotalDisplay": "$3.74",
          "discountTotalInPayoutCurrency": 3.74,
          "discountTotalInPayoutCurrencyDisplay": "$3.74",
          "price": 14.95,
          "priceDisplay": "$14.95",
          "priceInPayoutCurrency": 14.95,
          "priceInPayoutCurrencyDisplay": "$14.95",
          "priceTotal": 14.95,
          "priceTotalDisplay": "$14.95",
          "priceTotalInPayoutCurrency": 14.95,
          "priceTotalInPayoutCurrencyDisplay": "$14.95",
          "unitPrice": 11.21,
          "unitPriceDisplay": "$11.21",
          "unitPriceInPayoutCurrency": 11.21,
          "unitPriceInPayoutCurrencyDisplay": "$11.21",
          "total": 11.21,
          "totalDisplay": "$11.21",
          "totalInPayoutCurrency": 11.21,
          "totalInPayoutCurrencyDisplay": "$11.21"
        }
      ],
      "action": "subscription.get",
      "result": "success"
    }
  ]
}
 

Get subscription instance entries

GET /subscriptions/{id1}/entries

Response Example
{
  [
    {
	 "id": "entryId",
	 "beginEntryDate": "yyyy_MM_dd",
	 "beginPeriodDate": "yyyy_MM_dd",
	 "endPeriodDate": "yyyy_MM_dd",
	 "order": {
		// order resource response
	  }
    }
  ]
}

Update existing subscription instances

POST /subscriptions

Note

If you change the product on an active subscription to a different subscription product via the API:

  • Any free trial period associated with the new product will be ignored. In case you need to change the product on a subscription and have the new product's free trial period take effect, you can make this change via the Dashboard under the Activity menu.
  • The product price of the new product will be used for future billings. In case you need to change the product on a subscription and have the original product's price remain in effect, you can also pass the optional pricing info as shown in the third example below.
  • If the product price of the new product is greater than the price of the original product, the change will be recorded as an upgrade. If the price of the new product is less than the original product, the change will be recorded as a downgrade.
Request example - Changing the product for an active subscrpition
{
    "subscriptions": [
	{
        "subscription": "m6s7NWxJQum8GIklEqnHHQ",  // subscription ID to be updated
        "product": "soar-monthly-subscription",    // product path of the new product
        "quantity": 1                              // quantity of the new product
        "coupons": ["coupon_code"],                // only supports one coupon to be applied, pass an empty array to remove coupon
    }
  ]
}

Request example - Changing the date, quantity, or applied coupon for an active subscription
{
  "subscriptions": [
    {
      "subscription": "subscription-id-1",
      "next": 1448496000000 or "yyyy-mm-dd",      	// Next charge date
      "end": 1449496000000 or "yyyy-mm-dd" or 0,  	// Last charge date will be on or before this date. 0 as unlimited subscription
      "product": "subscription-product-1",
      "quantity": 1,
      "coupons": ["coupon_code"],			// only support one coupon to be applied, pass an empty array to remove coupon
      "prorate": true,            			// when implementing proration. *Cannot prorate with updating next charge date
    }, ...
  ]
}
Request example - Changing the price or discount for an active subscription without changing the product
  {
     "subscriptions":  [
        {
           "subscription":"subscription-id-1",
           "pricing":{
              "price":10 or {"USD":10}                      // see note below
              "discount":{
                 "type":"percent"/"amount",
                 "percentage"/"amount":5 or {"USD":}        // see note below
                 "duration":2 or "all"
              }
           }
        }
     ]
 }
// 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.
Request example - Adding or editing a subscription addon to an active subscription
{
  "subscriptions": [
    {
      "subscription": "subscription-id",
      "addons": [
        {
          "product": "add-on-product-being-added-or-updated",
          "quantity": 2,            			// update quantity
          "pricing":{          
            "price": {"USD":10}     			// update pricing            
            "discount":{                		// update discount
              "type":"percent"/"amount",
              "percentage"/"amount":10 or {"USD":5},
              "duration":2 or "all"
              }
            }
        }
      ]
    }
  ]
}
Request example - Removing a subscription addon from an active subscription
{
  "subscriptions": [
    {
      "subscription": "subscription-id",
      "addons": [
        {
          "product": "existing-add-on-product-being-removed",
          "quantity": 0
        }
      ]
    }
  ]
}

Response Example
{
  "subscription": [
    // Successful response
    {
      "subscription": "subscription-id-1",
      "action": "subscription.update",
      "result": "success"
    },
    // Possible errors
    {
      "subscription": "subscription-id-2",
      "action": "subscription.update",
      "result": "error"
      "error": {
        "subscription": "Not found",
        "subscription" : "Subscription is not changeable" // Canceled or ended
        "next": "Date format yyyy-mm-dd or milliseconds",
        "end": "Set 0 for no end date or Date format yyyy-mm-dd or milliseconds",
        "product": "Not found",
        "product": "Not a subscription product",
        "quantity": "Must be greater than zero",
        "coupons": "coupon_code is not a valid coupon: DOES_NOT_EXIST/USE_LIMIT_REACHED/NOT_VALID_TODAY",
        "prorate": "Cannot prorate with updating next period date"
      }
    },...
  ]
}

Cancel subscription instances

Cancel after the current period is ended (default behavior).

DELETE /subscriptions/{id1}[,{id2},{id3},...]

Cancel immediately

DELETE /subscriptions/{id1}[,{id2},{id3},...]?billingPeriod=0

Response Example
{
  "subscriptions": [
 
    // Successful response
    {
      "subscription": "id1",
      "action": "subscription.cancel",
      "result": "success"
    },
 
    // Possible errors
    {
      "subscription": "id2",
      "action": "subscription.cancel",
      "result": "error"
      "error": {
         "subscription":"The subscription is already canceled",
         "subscription":"The subscription is not active",
         "subscription":"The subscription is in the last billing period",
         "subscription":"Subscription not found",
         "billingPeriod":"billingPeriod must be a number",
         "billingPeriod":"billingPeriod=0 to cancel immediately or billingPeriod=1 to cancel at the next period.",
      }
    },
    ...
  ]
}

Uncancel a canceled subscription instance prior to deactivation

If you need to reverse or undo the cancelation of a subscription instance prior to the subscription's deactivation, you can uncancel the subscription instance by passing in "deactivation": null. However, if the subscription has already reached its deactivation date, it cannot be uncanceled.

You can also pass other values in the same uncancel request.

POST /subscriptions
Request example
{  
   "subscriptions":[  
      {  
         "subscription":"u5UUIZ7ISk68eT1P9lje_w",
         "deactivation":null
      },
   ]
}
Response example
{
	"subscriptions": [
	{
		"action": "subscription.update",
		"result": "success",
		"subscription": "u5UUIZ7ISk68eT1P9lje_w"
	},
  
	// Possible errors: attempting to uncancel a subscription that has already been deactivated
	{
	        "action": "subscription.update",
	        "subscription": "u5UUIZ7ISk68eT1P9lje_w",
	        "result": "error",
	        "error": {
	          "uncancel": "Subscription is not active."
	    	}
	},
	// Passing a value other than 'null' for "deactivation"
	{
	        "action": "subscription.update",
	        "subscription": "u5UUIZ7ISk68eT1P9lje_w",
	        "result": "error",
	        "error": {
	          "deactivation": "Pass null to uncancel the subscription"
		}
	}

	// Attempting to uncancel a subscription that has not been canceled:
	{
		"action": "subscription.update",
		"result": "success",
		"subscription": "u5UUIZ7ISk68eT1P9lje_w"		
	}
    ]
}

Rebill "managed" subscription instances

To learn more about managed subscriptions please refer to the corresponding section of the Subscriptions article.

If you would like to change rebill amount or subscription contents you will need to update the subscription instance first by using the corresponding operation above.

Note

On-demand billings for a managed subscription are limited on a per-subscription basis to no more than one transaction per day, and no more than four transactions per 30-day period.

POST /subscriptions/charge

Request Example
{
  "subscriptions": [
    {
      "subscription": "subscription-id",
    }
 ]

}
Response Example
{
  "subscription": [
    {
      "subscription": "subscription-id-1",
      "action": "subscription.charge",
      "result": "success"
    },
    // Possible errors
    {
      "subscription": "subscription-id-2",
      "action": "subscription.charge",
      "result": "error",
      "error": {
          "subscription": "EXPIRED_CARD",
          "subscription": "Subscription not found",
          "subscription": "Subscription is not active."
      }
    }
  ]
}