put https://secure.fusebill.com/v1/subscriptions
This action allows you to edit a Subscription. Editing a Subscription will return the updated Subscription object so you can verify your changes.
Special Considerations
Request considerations: Due to the complex nature of the subscription DTO we recommend using a get/put methodology when modifying a subscription. If values are not included, they may get nullified.
Request limitations: Only the specific fields listed in the below Object tables can be edited via the PUT Subscription operation.
**To change quantity or to include or un-include a plan product the manipulation must occur here.
Change subscription name/description: To change the subscription name or description you must enter new values in the subscriptionOveride element
Editing reference: This can be done by simply submitting a value in the Reference field directly
Editing contract start and end dates: This can set by submitting UTC datetime values in the contract fields
Setting, modifying and removing the scheduled activation date: This can be set by submitting UTC date time value in the scheduledActivtionTimestamp field
Setting the expiry period: This can set by submitting a number for the remaining expiry periods in the remainingInterval field. Note that the value “0” will result in an initial charge and then immediate expiry of the subscription following activation.
Query considerations: If you wish to temporarily disable automatically sending invoice changes we have an appendable query that can temporarily turn off that feature. Here's an example of that
secure.fusebill.com/v1/subscriptions?temporarilyDisableAutoPost=true
A few more important notes:
One consideration we must note is that the charges will remain on a draft unsent invoice until that draft invoice is posted.
When modifying a subscription with discounts you are required to remove the subscriptionProductDiscount (legacy object) entity and leave subscriptionProductDiscounts in place in order to carry forward your discounts.
Setting the PriceUpliftsEnabled key-value to "False" from a previous value of "True" will delete existing, future and historical price uplifts.
Request Parameters
| Property | Type | Description |
|---|---|---|
subscriptionOverride | Object. Defined below | This is an object which can override certain fields from the plan |
status | Enum: {Active, Draft, Cancelled, Provisioning, Expired, Migrated, Suspended, StandingOrder} | This is the status of this subscription. Draft indicates that the Subscription has not yet been activated. Provisioning indicates this Subscription has been provisioned but that the Setup Fee and recurring Charge has not been applied to the Customer. To set a Subscription as "Provisioned" you must set a Scheduled Activation Date for some time in the future. Most subscription status changes cannot be done through this call. |
reference | String | This is a text field you can populate with reference text for this subscription. This field is not exposed on the Invoice. [Max Length: 255 characters] |
subscriptionProducts | List of Objects. Defined below | This indicates if this Subscription has caused an invoice to be created and posted against the Customer's account. |
scheduledActivationTimestamp | DateTime | If set, this indicates when the Subscription should activate. To set a Subscription as "Provisioned" you must set a Scheduled Activation Date for some time in the future. The Subscription will automatically set to an "Active" status on the Scheduled Activation Date. |
remainingInterval | Integer | This lists the default number of intervals that remain before expiry. This is a default set at the plan level. |
remainingIntervalPushOut | Integer | This is the setting to default what the new remaining interval when the subscription is up for renewal. |
invoiceDay | Integer | The day of the month this subscription invoices on |
invoiceMonth | Integer | The month of the year this subscription invoices on |
contractStartTimestamp | Timestamp | This is the date that the contract period will begin. |
contractEndTimestamp | Timestamp | This is the date that the contract period will end. |
id | Integer | The Fusebill generated ID uniquely identifying this subscription |
Subscription Override Properties
| Property | Type | Description |
|---|---|---|
Name | String | This is the value which will override the PlanName field value. This override value will appear on invoices and in other Customer facing locations. [Max Length: 100 characters] |
Description | String | This is the value which will override the PlanDescription field value. This override value will appear on invoices and in other Customer facing locations. [Max Length: 500 characters] |
Subscription Products
| Property | Type | Description |
|---|---|---|
quantity | Decimal | This is the quantity of this Subscription Product being purchased. Used by the pricing model and price ranges to calculate the overall price. |
isIncluded | Boolean | Controls whether this subscription product is included if the plan product is optional. |
startDate | Timestamp | Controls scheduling for when this product generates charges. Can only be changed before the subscription has charges |
subscriptionProductOverride | Object. Defined below | Used to override name and description |
subscriptionProductPriceOverride | Object. See Subsctiptions: Subscription Product Price Override for details | Used to override pricing details |
chargeAtSubscriptionActivation | Boolean | Controls whether this subscription product will charge at activation. Can only be changed before the subscription has charges |
subscriptionProductDiscount | Object | Deprecated. Use the list subscriptionProductDiscounts instead |
subscriptionProductDiscounts | List of objects. Defined below. | A list of discounts applied to this subscription product |
earningSettings | Object. Defined below | Controls how this subscription product earns |
remainingInterval | Integer | The number of intervals until this subscription product expires |
upliftPriorToRecharge | Boolean | Controls whether price uplifts occur just prior to recharge |
includingInitialCharge | Boolean | Controls whether the initial charge counts when timing price uplifts |
priceUpliftsEnabled | Boolean | Controls whether price uplifts are being used for this subscription product |
priceUplifts | List of objects. Definition below. | A schedule of price uplifts |
customServiceDateNumberOfIntervals | Integer | Service dates control the dates displayed on invoice below the line item representing this subscription product on this plan frequency. This indicates how many intervals away from the invoice date is to be displayed. |
customServiceDateInterval | Enum: {Days, Periods} | Service dates control the dates displayed on invoice below the line item representing this subscription product. This controls whether the distance from the invoice date is measured in days or periods. |
customServiceDateProjection | Enum: {Past, Future} | Service dates control the dates displayed on invoice below the line item representing this plan product on this plan frequency. This controls whether the service date is before the posted invoice, or after. |
generateZeroDollarCharge | Boolean | Indicates whether this subscription product should generate a charge if it is zero dollars |
id | Integer | The Fusebill generated ID that uniquely identifies this subscription product. |
Subscription Product Override Fields
| Property | Type | Description |
|---|---|---|
name | String | This is the value which will be displayed instead of planProduct.productName on invoices and in other customer facing locations. [Max Length: 100 characters] |
description | String | This is the value which will be displayed instead of planProuct.productDescription on invoices and in other customer facing locations. [Max Length: 500 characters] |
Price Uplift Fields
| Property | Type | Description |
|---|---|---|
sequenceNumber | Integer | Indicates which position this uplift is in the sequence |
remainingIntervals | Integer | The remaining number of intervals before this price uplift takes effect after the previous uplift in the sequence occurs |
amount | Decimal | The percent amount this uplift will increase the price by |
repeatForever | Boolean | If this uplift is the last in the sequence, this indicates whether this uplift will repeat every numberOfIntervals after its first occurrence |
upliftPriorToRecharge | Boolean | Indicates whether the uplift occurs just prior to or just after the recharge |
Subscription Product Discount
| Property | Type | Description |
|---|---|---|
discountType | Enum:{ Percentage, Amount, AmountPerUnit} | This field indicates the type of discount applied. |
amount | Decimal | For Percentage discounts, this is the percentage which is discounted from the charge (if the discount is 25%, this value will be 25). For Amount discounts this is the actual value to subtract from the charge. |
remainingUsagesUntilStart | Integer | This is the number of billing cycles which must pass before the discount is applied. |
remainingUsage | Integer | This is the number of billing cycles which must pass before the discount automatically expires and is removed. This will be NULL for discounts which are perpetual. |
Earning Settings Fields
| Property | Type | Description |
|---|---|---|
earningTimingInterval | Enum:{Daily, Monthly, Yearly, Interval, EarnImmediately, DoesNotEarn} | Controls how the earning timing is measured for this subscription product |
earningTimingType | Enum:{StartOfInterval, EndOfInterval} | Controls whether the earning occurs at the start or end of the interval defined in earningTimingInterval |
Examples
curl -X PUT "https://secure.fusebill.com/v1/subscriptions" \
-H "Content-Type: application/json" \
-H "Authorization: Basic {APIKey}" \
-d "{id:{subscriptionId},customerId:{customerId},planCode:'PlanCode',planName:'PlanName',status:'Draft',reference:null,subscriptionProducts:[]}"
//Json Payload
string jsonData = "{id:{subscriptionId},customerId:{customerId},planCode:'PlanCode',planName:'PlanName',status:'Draft',reference:null,subscriptionProducts:[]}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://secure.fusebill.com/v1/subscriptions");
//Add Content type
request.ContentType = "application/json";
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "PUT";
//Add the json data to request
using (var streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(jsonData);
streamWriter.Flush();
streamWriter.Close();
}
//Perform the request
var httpResponse = (HttpWebResponse)request.GetResponse();
//Record the response from our request
var result = "";
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
result = streamReader.ReadToEnd();
}
#Import library JSON
import json
#Import library Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in a dictionary to the Payload parameter
payload = {"customerId":{id},"planFrequency":
{"planRevisionId":{id},"numberOfIntervals":1,"interval":"Monthly","numberOfSubscriptions":1,"status":"Active","setupFees":[],"charges":
[],"isProrated":"false","prorationGranularity":None,"planFrequencyUniqueId":{id},"remainingInterval":None,"id":{id},"uri":None},"planCode":"plan2","planName
":"Plan-
2","planDescription":None,"planReference":None,"status":"Active","reference":None,"subscriptionOverride":None,"hasPostedInvoice":"true","createdTimestamp":"
2017-02-09T19:35:55","activatedTimestamp":"2017-02-09T19:36:26","provisionedTimestamp":None,"nextPeriodStartDate":"2017-03-
09T05:00:00","scheduledActivationTimestamp":None,"subscriptionProducts":[{"subscriptionId":131087,"planProduct":
{"status":"Active","productId":{id},"planId":{id},"productCode":"product1","productName":"Product-
1","productStatus":"Active","productDescription":None,"productType":"RecurringService","productGLCode":"","quantity":1.0,"maxQuantity":None,"isRecurring":"t
rue","isFixed":"false","isOptional":"true","isIncludedByDefault":"false","isTrackingItems":"false","chargeAtSubscriptionActivation":"true","orderToCashCycle
s":[{"planFrequencyId":{id},"planProductId":{id},"numberOfIntervals":1,"interval":"Monthly","chargeModels":
[{"chargeModelType":"Signup","chargeTimingType":"StartOfPeriod","prorationGranularity":"Daily","prorateOnPositiveQuantity":"false","prorateOnNegativeQuantit
y":"false","reverseChargeOnNegativeQuantity":"false","id":{id},"uri":None},
{"chargeModelType":"Lifetime","chargeTimingType":"Immediate","prorationGranularity":"Daily","prorateOnPositiveQuantity":"false","prorateOnNegativeQuantity":
"false","reverseChargeOnNegativeQuantity":"false","id":{id},"uri":None}],"remainingInterval":None,"groupQuantityChangeCharges":"false","planProductPriceUp
lifts":None,"earningInterval":"Monthly","earningNumberOfIntervals":1,"earningTimingInterval":"Daily","earningTimingType":"StartOfInterval","pricingModel":
{"pricingModelType":"Standard","quantityRanges":[{"min":0.0,"max":None,"prices":
[{"amount":0.0,"currency":"USD","id":747012,"uri":None}],"id":0,"uri":None}],"id":{id},"uri":None},"id":{id},"uri":None}],"resetType":"Never","planProdu
ctUniqueId":{id},"id":{id},"uri":""},"quantity":1.0,"isIncluded":"true","startDate":None,"subscriptionProductOverride":None,"subscriptionProductPriceOverr
ide":None,"chargeAtSubscriptionActivation":"true","isCharged":"true","subscriptionProductDiscount":None,"subscriptionProductDiscounts":
[],"customFields":None,"monthlyRecurringRevenue":0.0,"netMonthlyRecurringRevenue":0.0,"amount":0.0,"status":"Active","lastPurchaseDate":None,"earningSetting
s":
{"earningTimingInterval":"Daily","earningTimingType":"StartOfInterval"},"remainingInterval":None,"groupQuantityChangeCharges":"false","priceUpliftsEnabled":
"false","priceUplifts":[],"historicalPriceUplifts":[],"id":{id},"uri":"https://stg-
secure.fusebill.com/v1/SubscriptionProducts/{id}"}],"remainingInterval":None,"remainingIntervalPushOut":None,"openSubscriptionPeriodEndDate":"2017-03-
09T05:00:00","chargeDiscount":None,"setupFeeDiscount":None,"chargeDiscounts":None,"setupFeeDiscounts":None,"customFields":None,"planAutoApplyChanges":"false
","autoApplyCatalogChanges":"false","monthlyRecurringRevenue":0.0000,"netMonthlyRecurringRevenue":0.0000,"amount":0.0000,"contractStartTimestamp":None,"cont
ractEndTimestamp":None,"expiredTimestamp":None,"coupons":[],"subscriptionHasRecurringEndOfPeriodCharge":"false","id":{id},"uri":"https://stg-
secure.fusebill.com/v1/subscriptions/{id}"}
#Pass in your URI, Payload and Headers
r = requests.put('https://secure.fusebill.com/v1/subscriptions', data=json.dumps(payload), headers=headers)
print(r.content)
{
"customerId": 186838,
"planFrequency": {
"planRevisionId": 177229,
"numberOfIntervals": 1,
"interval": "Monthly",
"numberOfSubscriptions": 1,
"status": "Active",
"setupFees": [],
"charges": [],
"isProrated": false,
"prorationGranularity": null,
"planFrequencyUniqueId": 4791,
"remainingInterval": null,
"id": 4791,
"uri": null
},
"planCode": "simplemonthly",
"planName": "Simple Monthly",
"planDescription": null,
"planReference": null,
"status": "Active",
"reference": null,
"subscriptionOverride": null,
"hasPostedInvoice": true,
"createdTimestamp": "2017-04-05T17:11:10",
"activatedTimestamp": "2017-04-05T17:15:11",
"provisionedTimestamp": null,
"nextPeriodStartDate": "2017-04-10T04:00:00",
"scheduledActivationTimestamp": null,
"subscriptionProducts": [
{
"subscriptionId": 177229,
"planProduct": {
"status": "Active",
"productId": 16758,
"planId": 2804,
"productCode": "recurringmonthlyproduct",
"productName": "Recurring Monthly Product",
"productStatus": "Active",
"productDescription": null,
"productType": "RecurringService",
"productGLCode": "",
"quantity": 1,
"maxQuantity": null,
"isRecurring": true,
"isFixed": false,
"isOptional": true,
"isIncludedByDefault": false,
"isTrackingItems": false,
"chargeAtSubscriptionActivation": true,
"orderToCashCycles": [
{
"planFrequencyId": 4791,
"planProductId": 18374,
"numberOfIntervals": 1,
"interval": "Monthly",
"chargeModels": [
{
"chargeModelType": "Signup",
"chargeTimingType": "StartOfPeriod",
"prorationGranularity": "Daily",
"prorateOnPositiveQuantity": false,
"prorateOnNegativeQuantity": false,
"reverseChargeOnNegativeQuantity": false,
"id": 970993,
"uri": null
},
{
"chargeModelType": "Lifetime",
"chargeTimingType": "Immediate",
"prorationGranularity": "Daily",
"prorateOnPositiveQuantity": false,
"prorateOnNegativeQuantity": false,
"reverseChargeOnNegativeQuantity": false,
"id": 970993,
"uri": null
}
],
"remainingInterval": null,
"groupQuantityChangeCharges": false,
"planProductPriceUplifts": null,
"customServiceDateNumberOfIntervals": 1,
"customServiceDateInterval": "Periods",
"customServiceDateProjection": "Future",
"earningInterval": "Monthly",
"earningNumberOfIntervals": 1,
"earningTimingInterval": "Daily",
"earningTimingType": "StartOfInterval",
"pricingModel": {
"pricingModelType": "Standard",
"quantityRanges": [
{
"min": 0,
"max": null,
"prices": [
{
"amount": 20,
"currency": "USD",
"id": 970993,
"uri": null
}
],
"id": 0,
"uri": null
}
],
"id": 970993,
"uri": null
},
"id": 970993,
"uri": null
}
],
"resetType": "Never",
"planProductUniqueId": 18108,
"id": 18374,
"uri": ""
},
"quantity": 1,
"isIncluded": true,
"startDate": null,
"subscriptionProductOverride": null,
"subscriptionProductPriceOverride": null,
"chargeAtSubscriptionActivation": true,
"isCharged": true,
"subscriptionProductDiscount": null,
"subscriptionProductDiscounts": [],
"customFields": null,
"monthlyRecurringRevenue": 20,
"netMonthlyRecurringRevenue": 20,
"amount": 20,
"status": "Active",
"lastPurchaseDate": null,
"earningSettings": {
"earningTimingInterval": "Daily",
"earningTimingType": "StartOfInterval"
},
"remainingInterval": null,
"groupQuantityChangeCharges": false,
"priceUpliftsEnabled": false,
"priceUplifts": [],
"historicalPriceUplifts": [],
"customServiceDateNumberOfIntervals": 1,
"customServiceDateInterval": "Periods",
"customServiceDateProjection": "Future",
"id": 970993,
"uri": "https://secure.fusebill.com/v1/SubscriptionProducts/970993"
}
],
"remainingInterval": null,
"remainingIntervalPushOut": null,
"openSubscriptionPeriodEndDate": "2017-04-10T04:00:00",
"chargeDiscount": null,
"setupFeeDiscount": null,
"chargeDiscounts": null,
"setupFeeDiscounts": null,
"customFields": null,
"planAutoApplyChanges": false,
"autoApplyCatalogChanges": false,
"monthlyRecurringRevenue": 20,
"netMonthlyRecurringRevenue": 20,
"amount": 20,
"contractStartTimestamp": null,
"contractEndTimestamp": null,
"expiredTimestamp": null,
"coupons": [],
"subscriptionHasRecurringEndOfPeriodCharge": false,
"id": 177229,
"uri": "https://secure.fusebill.com/v1/subscriptions/177229"
}
Response
{
"customerId": 186838,
"planFrequency": {
"planRevisionId": 177229,
"numberOfIntervals": 1,
"interval": "Monthly",
"numberOfSubscriptions": 1,
"status": "Active",
"setupFees": [
],
"charges": [
],
"isProrated": false,
"prorationGranularity": null,
"planFrequencyUniqueId": 4791,
"remainingInterval": null,
"id": 4791,
"uri": null
},
"planCode": "simplemonthly",
"planName": "Simple Monthly",
"planDescription": null,
"planReference": null,
"status": "Active",
"reference": null,
"subscriptionOverride": null,
"hasPostedInvoice": true,
"createdTimestamp": "2017-04-05T17:11:10",
"activatedTimestamp": "2017-04-05T17:15:11",
"provisionedTimestamp": null,
"nextPeriodStartDate": "2017-04-10T04:00:00",
"scheduledActivationTimestamp": null,
"subscriptionProducts": [
{
"subscriptionId": 177229,
"planProduct": {
"status": "Active",
"productId": 16758,
"planId": 2804,
"productCode": "recurringmonthlyproduct",
"productName": "Recurring Monthly Product",
"productStatus": "Active",
"productDescription": null,
"productType": "RecurringService",
"productGLCode": "",
"quantity": 1,
"maxQuantity": null,
"isRecurring": true,
"isFixed": false,
"isOptional": true,
"isIncludedByDefault": false,
"isTrackingItems": false,
"chargeAtSubscriptionActivation": true,
"orderToCashCycles": [
{
"planFrequencyId": 4791,
"planProductId": 18374,
"numberOfIntervals": 1,
"interval": "Monthly",
"chargeModels": [
{
"chargeModelType": "Signup",
"chargeTimingType": "StartOfPeriod",
"prorationGranularity": "Daily",
"prorateOnPositiveQuantity": false,
"prorateOnNegativeQuantity": false,
"reverseChargeOnNegativeQuantity": false,
"id": 970993,
"uri": null
},
{
"chargeModelType": "Lifetime",
"chargeTimingType": "Immediate",
"prorationGranularity": "Daily",
"prorateOnPositiveQuantity": false,
"prorateOnNegativeQuantity": false,
"reverseChargeOnNegativeQuantity": false,
"id": 970993,
"uri": null
}
],
"remainingInterval": null,
"groupQuantityChangeCharges": false,
"planProductPriceUplifts": null,
"customServiceDateNumberOfIntervals": 1,
"customServiceDateInterval": "Periods",
"customServiceDateProjection": "Future",
"earningInterval": "Monthly",
"earningNumberOfIntervals": 1,
"earningTimingInterval": "Daily",
"earningTimingType": "StartOfInterval",
"pricingModel": {
"pricingModelType": "Standard",
"quantityRanges": [
{
"min": 0,
"max": null,
"prices": [
{
"amount": 20,
"currency": "USD",
"id": 970993,
"uri": null
}
],
"id": 0,
"uri": null
}
],
"id": 970993,
"uri": null
},
"id": 970993,
"uri": null
}
],
"resetType": "Never",
"planProductUniqueId": 18108,
"generateZeroDollarCharge": false,
"id": 18374,
"uri": ""
},
"quantity": 1,
"isIncluded": true,
"startDate": null,
"subscriptionProductOverride": null,
"subscriptionProductPriceOverride": null,
"chargeAtSubscriptionActivation": true,
"isCharged": true,
"subscriptionProductDiscount": null,
"subscriptionProductDiscounts": [
],
"customFields": null,
"monthlyRecurringRevenue": 20,
"netMonthlyRecurringRevenue": 20,
"amount": 20,
"status": "Active",
"lastPurchaseDate": "2017-04-05T17:11:20",
"earningSettings": {
"earningTimingInterval": "Daily",
"earningTimingType": "StartOfInterval"
},
"remainingInterval": null,
"groupQuantityChangeCharges": false,
"priceUpliftsEnabled": false,
"priceUplifts": [
],
"historicalPriceUplifts": [
],
"customServiceDateNumberOfIntervals": 1,
"customServiceDateInterval": "Periods",
"customServiceDateProjection": "Future",
"generateZeroDollarCharge": false,
"id": 970993,
"uri": "https://secure.fusebill.com/v1/SubscriptionProducts/970993"
}
],
"remainingInterval": null,
"remainingIntervalPushOut": null,
"openSubscriptionPeriodEndDate": "2017-04-10T04:00:00",
"chargeDiscount": null,
"setupFeeDiscount": null,
"chargeDiscounts": null,
"setupFeeDiscounts": null,
"customFields": null,
"planAutoApplyChanges": false,
"autoApplyCatalogChanges": false,
"monthlyRecurringRevenue": 20,
"netMonthlyRecurringRevenue": 20,
"amount": 20,
"contractStartTimestamp": null,
"contractEndTimestamp": null,
"expiredTimestamp": null,
"cancellationTimestamp": null,
"modifiedTimestamp": "2020-04-27T19:10:14.023",
"coupons":[
],
"invoiceDay": 1,
"invoiceMonth": null,
"canMigrate": false,
"migrationDate": null,
"scheduledMigrationDate": null,
"migrations": null,
"subscriptionHasRecurringEndOfPeriodCharge":false,
"id":122453,
"uri":"https://secure.fusebill.com/v1/subscriptions/122453"
}
{
"ErrorId": 0,
"HttpStatusCode": 400,
"Errors": [
{
"Key": "Api Error",
"Value": "Cannot suspend subscription."
}
]
}