get https://api.fastspring.com/subscriptions//history
Get plan change history
The Subscription Plan Change History API returns an array of history entry objects, each one describing a change in the subscription plan. These objects include specifics on what part of the subscription plan changed, when it changed, and how it changed.
Input
Send the subscriptionId to see all plan changes for the specified subscription. This will return all plan changes made on the subscription starting from the most recent.
Parameters
- You can filter the results by item type. To get all base plan level changes only, use
&scope=base_plan. To see add-on specific line item changes, use&scope=add_on. - You can also get the history in chronological or reverse chronological order. Just add &order=increasing to see the oldest changes to the newest. The endpoint returns changes in decreasing order of timestamp by default.
Output
The endpoint returns an array of change history entries describing changes made on the subscription. These entries include both data and metadata designed to categorize the type of change, provide context on data’s origin and user intent, introduce searchability and facilitate discoverability.
Important
Plan Change history is only available from March 10, 2023. Change history prior to this date will be not returned in the response.
Examples
Use Case 1: Get all plan changes starting from the most recent (default)
The original subscription was purchased on May 18. It contains 3 units of Bronze for $100/mo/unit. Since date of purchase, the following plan changes had occurred:
- On May 18:
- The base plan quantity changed from 3 to 4
- The document viewer add-on was removed
- The changes were prorated
- On May 22nd:
- The base plan changed from Bronze to Silver
- 2 units of consultation add-on were added
- 1 unit of document-viewer add-on was also added
- The changes were prorated
- On May 29:
- The tax exempt ID was set to 1234567
GET /subscriptions/OapmwBYlS8CE36nlo7Vm9w/history
{
"currency": "USD",
"timezone": "UTC",
"changes": [
{
"insertTimestamp": 1684378979000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEJYF3IHF35ZDI3N3E5CQGSABR6A",
"prorated": true,
"orderId": "LFH1PZcITzyb93qXbnZL8Q",
"orderRef": null,
"itemType": ADD_ON,
"itemId": "ZjZFslRvRdG0FSVY-03wMg",
"itemProductPath": "document-viewer",
"itemProductDisplay": "Document Viewer",
"itemProductSku": "",
"changeType": "ADD_ON_REMOVE",
"changedFrom": "1",
"changedFromDisplay": "1",
"changedTo": "0",
"changedToDisplay": "0"
},
{
"insertTimestamp": 1684378972000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CE5FINSLQ6DRBUPP2TKT5LYARICE",
"prorated": true,
"orderId": "LFH1PZcITzyb93qXbnZL8Q",
"orderRef": null,
"itemType": BASE_PLAN,
"itemId": "OapmwBYlS8CE36nlo7Vm9w",
"itemProductPath": "silver",
"itemProductDisplay": "Silver",
"itemProductSku": null,
"changeType": "BASE_PLAN_QTY_CHANGE",
"changedFrom": "3",
"changedFromDisplay": "3",
"changedTo": "4",
"changedToDisplay": "4"
},
{
"insertTimestamp": 1680105140000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEJONYRB7QUZFG3AACVI5JBAC6XY",
"prorated": false,
"orderId": null,
"orderRef": null,
"itemType": BASE_PLAN,
"itemId": "",
"itemProductPath": "",
"itemProductDisplay": "",
"itemProductSku": "OapmwBYlS8CE36nlo7Vm9w",
"changeType": "BASE_PLAN_TAX_EXEMPTION_CHANGE",
"changedFrom": "",
"changedFromDisplay": "",
"changedTo": "1234567890",
"changedToDisplay": "1234567890"
},
{
"insertTimestamp": 1679526897000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CE2NH3KEAU5RCMLKGO2JGBA3GKC4",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": ADD_ON,
"itemId": "ZjZFslRvRdG0FSVY-03wMg",
"itemProductPath": "document-viewer",
"itemProductDisplay": "Document Viewer",
"itemProductSku": "",
"changeType": "ADD_ON_ADD",
"changedFrom": "0",
"changedFromDisplay": "0",
"changedTo": "1",
"changedToDisplay": "1"
},
{
"insertTimestamp": 1679526882000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CESMKJKB7GBZDF7DHRFZ2NBLOJGM",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": ADD_ON,
"itemId": "1sJskqDeQRejPzxhW11cSQ",
"itemProductPath": "consultation",
"itemProductDisplay": "Consultation",
"itemProductSku": "",
"changeType": "ADD_ON_ADD",
"changedFrom": "0",
"changedFromDisplay": "0",
"changedTo": "2",
"changedToDisplay": "2"
},
{
"insertTimestamp": 1679526882000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CESMKJKB7GBZDF7DHRFZ2NBLOJGM",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": ADD_ON,
"itemId": "1sJskqDeQRejPzxhW11cSQ",
"itemProductPath": "consultation",
"itemProductDisplay": "Consultation",
"itemProductSku": "",
"changeType": "ADD_ON_DISCOUNT_CHANGE",
"changedFrom": "0.0000",
"changedFromDisplay": "$0.00",
"changedTo": "10.0000",
"changedToDisplay": "$10.00"
},
{
"insertTimestamp": 1679526862000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VEeL5biRTs",
"changeId": "CEXUP5MTEKQNFJLFLNSHS2AMTRWU",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": BASE_PLAN,
"itemId": "OapmwBYlS8CE36nlo7Vm9w",
"itemProductPath": "silver",
"itemProductDisplay": "Silver",
"itemProductSku": null,
"changeType": "BASE_PLAN_UPGRADE",
"changedFrom": "bronze",
"changedFromDisplay": "Bronze",
"changedTo": "silver",
"changedToDisplay": "Silver"
},
{
"insertTimestamp": 1679526862000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEXUP5MTEKQNFJLFLNSHS2AMTRWU",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": BASE_PLAN,
"itemId": "OapmwBYlS8CE36nlo7Vm9w",
"itemProductPath": "silver",
"itemProductDisplay": "Silver",
"itemProductSku": null,
"changeType": "BASE_PLAN_PRICE_CHANGE",
"changedFrom": "100.0000",
"changedFromDisplay": "$100.00",
"changedTo": "180.0000",
"changedToDisplay": "$180.00"
}
]
}
Use Case 2: Get all plan changes in chronological order
This is the same subscription and plan changes as above but with?order=increasing.
The original subscription was purchased on May 18. It contains 3 units of Bronze for $100/mo/unit. Since date of purchase, the following plan changes had occurred:
- On May 29:
- The tax exempt ID was set to 1234567
- On May 22nd:
- The base plan changed from Bronze to Silver
- 2 units of consultation add-on were added
- 1 unit of document-viewer add-on was also added
- The changes were prorated
- On May 18:
- The base plan quantity changed from 3 to 4
- The document viewer add-on was removed
- The changes were prorated
- On May 22nd:
- The base plan changed from Bronze to Silver
- 2 units of consultation add-on were added
- 1 unit of document-viewer add-on was also added
- The changes were prorated
GET /subscriptions/OapmwBYlS8CE36nlo7Vm9w/history
{
"currency": "USD",
"timezone": "UTC",
"changes": [
{
"insertTimestamp": 1679526862000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEXUP5MTEKQNFJLFLNSHS2AMTRWU",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": "BASE_PLAN",
"itemId": "OapmwBYlS8CE36nlo7Vm9w",
"itemProductPath": "silver",
"itemProductDisplay": "Silver",
"itemProductSku": null,
"changeType": "BASE_PLAN_UPGRADE",
"changedFrom": "bronze",
"changedFromDisplay": "Bronze",
"changedTo": "silver",
"changedToDisplay": "Silver"
},
{
"insertTimestamp": 1679526862000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEXUP5MTEKQNFJLFLNSHS2AMTRWU",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": "BASE_PLAN",
"itemId": "OapmwBYlS8CE36nlo7Vm9w",
"itemProductPath": "silver",
"itemProductDisplay": "Silver",
"itemProductSku": null,
"changeType": "BASE_PLAN_PRICE_CHANGE",
"changedFrom": "100.0000",
"changedFromDisplay": "$100.00",
"changedTo": "180.0000",
"changedToDisplay": "$180.00"
},
{
"insertTimestamp": 1679526882000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CESMKJKB7GBZDF7DHRFZ2NBLOJGM",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": "ADD_ON",
"itemId": "1sJskqDeQRejPzxhW11cSQ",
"itemProductPath": "consultation",
"itemProductDisplay": "Consultation",
"itemProductSku": "",
"changeType": ADD_ON_ADD",
"changedFrom": "0",
"changedFromDisplay": "0",
"changedTo": "2",
"changedToDisplay": "2"
},
{
"insertTimestamp": 1679526882000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CESMKJKB7GBZDF7DHRFZ2NBLOJGM",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": "ADD_ON",
"itemId": "1sJskqDeQRejPzxhW11cSQ",
"itemProductPath": "consultation",
"itemProductDisplay": "Consultation",
"itemProductSku": "",
"changeType": ADD_ON_DISCOUNT_CHANGE",
"changedFrom": "0.0000",
"changedFromDisplay": "$0.00",
"changedTo": "10.0000",
"changedToDisplay": "$10.00"
},
{
"insertTimestamp": 1679526897000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CE2NH3KEAU5RCMLKGO2JGBA3GKC4",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": "ADD_ON",
"itemId": "ZjZFslRvRdG0FSVY-03wMg",
"itemProductPath": "document-viewer",
"itemProductDisplay": "Document Viewer",
"itemProductSku": "",
"changeType": ADD_ON_ADD",
"changedFrom": "0",
"changedFromDisplay": "0",
"changedTo": "1",
"changedToDisplay": "1"
},
{
"insertTimestamp": 1680105140000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEJONYRB7QUZFG3AACVI5JBAC6XY",
"prorated": false,
"orderId": null,
"orderRef": null,
"itemType": "BASE_PLAN",
"itemId": "",
"itemProductPath": "",
"itemProductDisplay": "",
"itemProductSku": "OapmwBYlS8CE36nlo7Vm9w",
"changeType": "BASE_PLAN_TAX_EXEMPTION_CHANGE",
"changedFrom": "",
"changedFromDisplay": "",
"changedTo": "1234567890",
"changedToDisplay": "1234567890"
},
{
"insertTimestamp": 1684378972000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CE5FINSLQ6DRBUPP2TKT5LYARICE",
"prorated": true,
"orderId": "LFH1PZcITzyb93qXbnZL8Q",
"orderRef": null,
"itemType": "BASE_PLAN",
"itemId": "OapmwBYlS8CE36nlo7Vm9w",
"itemProductPath": "silver",
"itemProductDisplay": "Silver",
"itemProductSku": null,
"changeType": "BASE_PLAN_QTY_CHANGE",
"changedFrom": "3",
"changedFromDisplay": "3",
"changedTo": "4",
"changedToDisplay": "4"
},
{
"insertTimestamp": 1684378979000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEJYF3IHF35ZDI3N3E5CQGSABR6A",
"prorated": true,
"orderId": "LFH1PZcITzyb93qXbnZL8Q",
"orderRef": null,
"itemType": "ADD_ON",
"itemId": "ZjZFslRvRdG0FSVY-03wMg",
"itemProductPath": "document-viewer",
"itemProductDisplay": "Document Viewer",
"itemProductSku": "",
"changeType": ADD_ON_REMOVE",
"changedFrom": "1",
"changedFromDisplay": "1",
"changedTo": "0",
"changedToDisplay": "0"
}
]
}
Use Case 3: Get add-on only plan changes in reverse chronological order
Use the scope=add_on parameter to only return plan changes for add_on products.
/subscriptions/OapmwBYlS8CE36nlo7Vm9w/history?scope=add_on&order=increasing
{
"currency": "USD",
"timezone": "UTC",
"changes": [
{
"insertTimestamp": 1679526882000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CESMKJKB7GBZDF7DHRFZ2NBLOJGM",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": "ADD_ON",
"itemId": "1sJskqDeQRejPzxhW11cSQ",
"itemProductPath": "consultation",
"itemProductDisplay": "Consultation",
"itemProductSku": "",
"changeType": "ADD_ON_ADD",
"changedFrom": "0",
"changedFromDisplay": "0",
"changedTo": "2",
"changedToDisplay": "2"
},
{
"insertTimestamp": 1679526882000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CESMKJKB7GBZDF7DHRFZ2NBLOJGM",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": "ADD_ON",
"itemId": "1sJskqDeQRejPzxhW11cSQ",
"itemProductPath": "consultation",
"itemProductDisplay": "Consultation",
"itemProductSku": "",
"changeType": "ADD_ON_DISCOUNT_CHANGE",
"changedFrom": "0.0000",
"changedFromDisplay": "$0.00",
"changedTo": "10.0000",
"changedToDisplay": "$10.00"
},
{
"insertTimestamp": 1679526897000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CE2NH3KEAU5RCMLKGO2JGBA3GKC4",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": "ADD_ON",
"itemId": "ZjZFslRvRdG0FSVY-03wMg",
"itemProductPath": "document-viewer",
"itemProductDisplay": "Document Viewer",
"itemProductSku": "",
"changeType": "ADD_ON_ADD",
"changedFrom": "0",
"changedFromDisplay": "0",
"changedTo": "1",
"changedToDisplay": "1"
},
{
"insertTimestamp": 1684378979000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEJYF3IHF35ZDI3N3E5CQGSABR6A",
"prorated": true,
"orderId": "LFH1PZcITzyb93qXbnZL8Q",
"orderRef": null,
"itemType": "ADD_ON",
"itemId": "ZjZFslRvRdG0FSVY-03wMg",
"itemProductPath": "document-viewer",
"itemProductDisplay": "Document Viewer",
"itemProductSku": "",
"changeType": "ADD_ON_REMOVE",
"changedFrom": "1",
"changedFromDisplay": "1",
"changedTo": "0",
"changedToDisplay": "0"
}
]
}
Use Case 4: Get base-plan only changes
Use the scope=base_plan parameter to only return plan changes for base products.
/subscriptions/OapmwBYlS8CE36nlo7Vm9w/history?scope=base_plan
{
"currency": "USD",
"timezone": "UTC",
"changes": [
{
"insertTimestamp": 1684378972000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CE5FINSLQ6DRBUPP2TKT5LYARICE",
"prorated": true,
"orderId": "LFH1PZcITzyb93qXbnZL8Q",
"orderRef": null,
"itemType": BASE_PLAN,
"itemId": "OapmwBYlS8CE36nlo7Vm9w",
"itemProductPath": "silver",
"itemProductDisplay": "Silver",
"itemProductSku": null,
"changeType": "BASE_PLAN_QTY_CHANGE",
"changedFrom": "3",
"changedFromDisplay": "3",
"changedTo": "4",
"changedToDisplay": "4"
},
{
"insertTimestamp": 1680105140000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEJONYRB7QUZFG3AACVI5JBAC6XY",
"prorated": false,
"orderId": null,
"orderRef": null,
"itemType": BASE_PLAN,
"itemId": "",
"itemProductPath": "",
"itemProductDisplay": "",
"itemProductSku": "OapmwBYlS8CE36nlo7Vm9w",
"changeType": "BASE_PLAN_TAX_EXEMPTION_CHANGE",
"changedFrom": "",
"changedFromDisplay": "",
"changedTo": "1234567890",
"changedToDisplay": "1234567890"
},
{
"insertTimestamp": 1679526862000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VEeL5biRTs",
"changeId": "CEXUP5MTEKQNFJLFLNSHS2AMTRWU",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": BASE_PLAN,
"itemId": "OapmwBYlS8CE36nlo7Vm9w",
"itemProductPath": "silver",
"itemProductDisplay": "Silver",
"itemProductSku": null,
"changeType": "BASE_PLAN_UPGRADE",
"changedFrom": "bronze",
"changedFromDisplay": "Bronze",
"changedTo": "silver",
"changedToDisplay": "Silver"
},
{
"insertTimestamp": 1679526862000,
"subscriptionId": "OapmwBYlS8CE36nlo7Vm9w",
"siteId": "VcEeL5biRTs",
"changeId": "CEXUP5MTEKQNFJLFLNSHS2AMTRWU",
"prorated": true,
"orderId": "zn8E8IoyROGs2rpXaG3log",
"orderRef": null,
"itemType": BASE_PLAN,
"itemId": "OapmwBYlS8CE36nlo7Vm9w",
"itemProductPath": "silver",
"itemProductDisplay": "Silver",
"itemProductSku": null,
"changeType": "BASE_PLAN_PRICE_CHANGE",
"changedFrom": "100.0000",
"changedFromDisplay": "$100.00",
"changedTo": "180.0000",
"changedToDisplay": "$180.00"
}
]
}