post
https://secure.fusebill.com/v1/subscriptions
This action will create a new Subscription. Subscriptions are applied to specific Customers, identified by the customerId field, and are instances of a specific frequency of a specific Plan, identified by the planFrequencyId below.
When you create a Subscription you have the option of providing a subscriptionOverride. This override will allow you to change the name and description of the subscription, as it appears on the Customer's invoice, as well as specify a different recurring charge value and setup fee value. This allows you to customize the pricing for this Subscription for your Customer if you want.
Creating a Subscription will include all the Products in the associated Plan in the newly created Subscription. You can Edit the Subscription if you wish to modify aspects of the Products. See the Edit Subscription page for details.
Subscriptions have a status of Draft when created and you will need to perform an additional action to Activate the Subscription. See the Activation page for details.
This action will return the full Subscription object of the newly created Subscription.
Minimum Request: The minimum request key-value pairs include fields "customerID", "PlanID", "PlanName", "Reference" and "PlanFrequencyID".
Subscription Object Fields
| Property | Type | Description |
|---|---|---|
id | Decimal | This is the Subscription Id which uniquely identifies this individual Subscription. This Id is used to refer to this Subscription specifically. |
customerId | Decimal | This is the Id of the Customer to whom this Subscription has been applied. |
planCode | String | This is the unique code which represents the Plan of which this Subscription is an instance. |
planName | String | This is the name of the Plan of which this Subscription is an instance. |
planDescription | String | This is the description text of the Plan of which this Subscription is an instance. |
planReference | String | This is a text field which will be populated with the reference text from the Plan. This field is not exposed on the Invoice. |
status | String | This is the status of this subscription. Accepted values are "Active", "Draft", "Canceled", "Provisioning" and "Expired". 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. |
reference | String | This is a text field you can populate with reference text for this subscription. This field is not exposed on the Invoice. |
hasPostedInvoice | Boolean | This indicates if this Subscription has caused an invoice to be created and posted against the Customer's account. |
CreatedTimestamp | DateTime | This indicates when the Subscription was created. |
ActivatedTimestamp | DateTime | This indicates when the Subscription was activated. |
ProvisionedTimestamp | DateTime | This indicates when the Subscription was provisioned. |
NextPeriodStartDate | DateTime | This indicates when the next billing period for the Subscription will begin. Normally, this indicates when the Subscription will bill and apply charges to the Customer's account.This indicates when the next billing period for the Subscription will begin. Normally, this indicates when the Subscription will bill and apply charges to the Customer's account. |
remainingInterval | Decimal | This is the number of billing intervals in the lifetime of this Subscription. If this value is set to "null" the Subscription will renew indefinitely. If this is set to a number than after that number of intervals has passed the subscription will change into an "Expired" status automatically and stop billing the Customer. |
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 | Decimal | This lists the default number of intervals that remain before expiry. This is a default set at the plan level. |
remainingIntervalPushOut | Decimal | This is the setting to default what the new remaining interval when the subscription is up for renewal. |
openSubscriptionPeriodEndDate | DateTime | This is the date that the current billing period will end. Often, this field will match the "nextPeriodStartDate" value. |
chargeDiscount | chargeDiscount | This is the Discount entity which applies to the base recurring charge for this subscription. (This is a legacy object use chargeDiscounts collection) |
setupFeeDiscount | Decimal | This is the Discount entity which applies to the base setup fee charge for this subscription.(This is a legacy object use setupFeeDiscounts collection) |
chargeDiscounts | Decimal | This is the Discount entity which applies to the base recurring charge for this subscription. (Use this collection for discounts) |
setupFeeDiscount | Decimal | This is the Discount entity which applies to the base setup fee charge for this subscription.(This is a legacy object use setupFeeDiscounts collection) |
chargeDiscounts | Discount | This is the Discount entity which applies to the base recurring charge for this subscription. (Use this collection for discounts) |
setupFeeDiscounts | Decimal | This is the Discount entity which applies to the base setup fee charge for this subscription. (Use this collection for discounts) |
planAutoApplyChanges | Boolean | This field related to Grandfathering control. If True, this indicates that the Plan from which this Subscription is made usually pushes changes to the Plan down to existing Subscriptions - this forces existing customers onto the newest version of the Plan. If set to False, this 'grandfathers' the Customer into the version of the Plan they Subscribed to and does not push changes. |
autoApplyCatalogChanges | Boolean | This field controls if this specific Subscription should automatically push changes to the underlying Plan to this Subscription. If set to True, changes will be pushed automatically. If False, this Subscription will not reflect updates to the Plan from which it was made. |
monthlyRecurringRevenue | Decimal | The calculated monthly recurring revenue value for this Customer. This is calculated based on expected income based on the current Subscription value. Only recurring charges are included in this calculation and One Time Goods and Physical Goods purchases, which do not recur, are not included. |
netMonthlyRecurringRevenue | Decimal | The net MRR of the customer. Calculated by considering any discounts on the customers active subscription products. |
amount | Decimal | The amount of the subscription. |
contractStartTimestamp | DateTime | This is the date that the contract period will begin. |
contractEndTimestamp | DateTime | This is the date that the contract period will end. |
uri | String | This is the URI which can be used to reference this Subscription Product directly. |
PlanFrequency Fields
| Property | Type | Description |
|---|---|---|
planRevisionId | Decimal | This is the unique identifier for this plan revision |
numberOfIntervals | Decimal | This is the number of intervals that this plan will renew for |
interval | String | Valid strings are “Monthly”, “Yearly” |
numberOfSubscriptions | Decimal | This is the number of instances of this plan currently in the system as subscriptions |
status | String | Valid strings are “Draft”, “Active”, “Retired” |
setupFees | Array | This is an Array of Setup Fee objects. There are up to one object per active currency. Setup Fees are optional and may not be included in a plan. If they are not included this array would be empty. |
charges | Array | This is an Array of Charges objects. There are up to one object per active currency. These Charges are optional and may not be included in a plan. If they are not included this array would be empty. |
isProrated | Boolean | This indicates if this Subscription should prorate its charges if activated in the middle of a billing cycle. |
prorationGranularity | String | This defines how granular the proration calculation should be. Valid strings are "Monthly" or "Daily". |
planFrequencyUniqueId | Number | This is an internal only identifier, do not modify this value. |
id | Decimal | This is the unique identifier. |
uri | String | This is the URI referring to this Plan Frequency object. |
Setup Fee Fields
| Property | Type | Description |
|---|---|---|
amount | Decimal | This is the cost of the setup fee |
currency | String | This indicates which currency this fee applied is charged in |
id | Decimal | This is the unique identifier for this fee |
url | String | This is the URI to view this object |
Charge Fields
| Property | Type | Description |
|---|---|---|
amount | Decimal | This is the monthly recurring charge |
currency | String | This indicates which currency this charge is charged in |
id | Decimal | This is the unique identifier for this charge |
url | String | This is the URI to view this object |
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. |
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. |
Charge | Decimal | This value will override the cost of the recurring charge in the Plan. The amount entered here becomes the new amount charged to the Customer when the Subscription bills each period. Additional charges, from Products for example, are not affected by this and will continue to bill normally. |
SetupFee | Decimal | This value will override the cost of the setup fee charge in the Plan. The amount entered here becomes the new amount charged to the Customer when the Subscription is activated. Additional charges, from Products for example, are not affected by this and will continue to bill normally. |
PlanProducts Fields
| Property | Type | Description |
|---|---|---|
subscriptionId | Decimal | This is the Subscription Product Id that uniquely refers to this Subscription product. This is important for action including this object such as managing the Subscription Product Items inventory. |
planProduct | Array | This is the Plan Product object. This object contains most of the details and configuration regarding the product being sold as part of this subscription. See Plan Product for more details. |
Quantity | Decimal | This is the number of units of this Subscription Product being purchased. |
isIncluded | Boolean | This indicates if this Subscription Product is included in the Customer's Subscription |
subscriptionProductOverride | Array | This contains a set of fields to override the name and description of the Subscription Product. |
subscriptionProductPriceOverride | Array | This contains a set of fields to override the pricing for the Subscription Product |
ChargeAtSubscriptionActivation | Boolean | This flag informs the system to either charge for this Subscription Product when the Subscription is activated (True) or to charge when it is Provisioned (False). |
StartDate | DateTime | This is the date on which this Subscription Product should begin to charge the Customer |
IsCharged | Boolean | This flag indicates if this Subscription Product has been charged. If it has applied a charge then this field will be True. |
subscriptionProductDiscount | Array | This is the Discount entity applied to this Subscription Product. See the ChargeDiscount description below for details. |
customFields | Array | This is the list of Custom Fields applied to this Subscription Product. These fields will match the Plan Product fields unless the field values in the Subscription have been changed in which case these fields show the data applied to the Subscription Product and not the default value seen in the Plan Product. |
monthlyRecurringRevenue | Number | The calculated monthly recurring revenue value for this Customer. This is calculated based on expected income based on the current Subscription value. Only recurring charges are included in this calculation and One Time Goods and Physical Goods purchases, which do not recur, are not included. |
netMonthlyRecurringRevenue | Decimal | The net MRR of the customer. Calculated by considering any discounts on the customers active subscription products. |
customServiceDateNumberOfIntervals | Decimal | This value represents the number of intervals in the past or in the future that you would like to set this service date for. |
customServiceDateInterval | String | Possible service date values are "Periods", "Dates" and "Months". |
customServiceDateProjection | String | Possible values are "Past" or "Future". |
amount | Decimal | This is the dollar amount to apply against the above invoice. |
status | String | This is the current status of the plan product. |
lastPurchaseDate | DateTime | This is the last date of purchase. |
earningSettings | Array | This is a small collection of th earning interval type and timing. |
id | Decimal | This is the unique identifier |
uri | String | This is the URI which can be used to reference this Subscription Product directly. |
Earning Interval Settings
| Property | Type | Description |
|---|---|---|
earningInterval | String | The period in which a product will earn. Strings may be "Daily", "Monthly", or "Yearly". |
earningNumberOfIntervals | Number | |
earningTimingInterval | String | |
earningTimingType | String | This delineates if the earnage is to occur at the beginning or the end of the period. The accepted strings are "StartOfInterval" or "EndOfInterval" |
Subscription Product Override Fields
| Property | Type | Description |
|---|---|---|
Name | String | This is the value which will override the ProductName field value. This override value will appear on invoices and in other Customer facing locations. |
Description | String | This is the value which will override the Product Description field value. This override value will appear on invoices and in other Customer facing locations. |
Subscription Product Price Fields
| Property | Type | Description |
|---|---|---|
ChargeAmount | Decimal | This value will override the cost of the Product. The amount entered here becomes the new amount charged to the Customer when the Subscription bills each period or when the Quantity is increased on this Product. Additional charges, from the Subscription for example, are not affected by this and will continue to bill normally. |
Subscription Product Discounts
| Property | Type | Description |
|---|---|---|
discountType | String | This field indicates the type of discount applied. Valid entries are "Percentage" or "Amount". |
amount | Number | 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 | Number | This is the number of billing cycles which must pass before the discount is applied. |
remainingUsage | Number | 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. |
Custom Fields
| Property | Type | Description |
|---|---|---|
key | String | This is the unique key of the Custom Field you wish to modify. |
friendlyName | String | This is the text friendly label for the key. |
dataType | String | This is the data type for the custom field. |
value | String | This is the value you wish to update the custom field to. This will always be the string version of the value. If you wish to pass a number, for example, pass it as "123". Likewise, a DateTime would be passed as "2014-06-26T04:00:00". We will use the known data type of the custom field to properly convert the String to a Number, DateTime, etc. |
Price Uplift Fields
| Property | Type | Description |
|---|---|---|
priceUpliftEnabled | Boolean | This is a True or False value, which allows you to set the price uplift feature as enabled or disabled. |
priceUplifts | List | This is a list of price uplift interval objects. |
historicalPriceUplifts | List | This is list of surpassed price uplift intervals. |
Examples
curl -X POST "https://stg-secure.fusebill.com/v1/subscriptions" \
-H "Content-Type: application/json" \
-H "Authorization: Basic {APIKey}" \
-d "{customerid:{customerId},code:'YourPlanCodeHere',name:'YourPlanNameHere',reference:null,planFrequencyId:{planFrequencyId}}"//Json Payload
string jsonData = "{customerid:{customerId},code:'YourPlanCodeHere',name:'YourPlanNameHere',reference:null,planFrequencyId:{planFrequencyId}}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-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 = "POST";
//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},"code":'sampleplan',"name":"Sample Plan","reference":None,"planFrequencyId":{id}}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/subscriptions', data=json.dumps(payload), headers=headers)
print(r.content)Response
{
"customerId": 1930362,
"planFrequency": {
"planRevisionId": 3135696,
"numberOfIntervals": 1,
"interval": "Monthly",
"numberOfSubscriptions": 1,
"status": "Active",
"setupFees": [
],
"charges": [
],
"isProrated": false,
"prorationGranularity": null,
"planFrequencyUniqueId": 1283935,
"remainingInterval": null,
"id": 1868701,
"uri": null
},
"planCode": "premiumplan",
"planName": "Premium Plan",
"planDescription": null,
"planReference": null,
"status": "Active",
"reference": null,
"subscriptionOverride": null,
"hasPostedInvoice": true,
"createdTimestamp": "2017-05-12T21:36:31.0000794Z",
"activatedTimestamp": "2017-05-12T21:36:31.0000794Z",
"provisionedTimestamp": null,
"nextPeriodStartDate": "2017-06-12T04:00:00",
"scheduledActivationTimestamp": null,
"subscriptionProducts": [
{
"subscriptionId": 3135696,
"planProduct": {
"status": "Active",
"productId": 1421752,
"planId": 828556,
"productCode": "premiumproduct",
"productName": "Premium Product",
"productStatus": "Active",
"productDescription": null,
"productType": "RecurringService",
"productGLCode": "",
"quantity": 1,
"maxQuantity": null,
"isRecurring": true,
"isFixed": false,
"isOptional": true,
"isIncludedByDefault": true,
"isTrackingItems": false,
"chargeAtSubscriptionActivation": true,
"orderToCashCycles": [
{
"planFrequencyId": 1868701,
"planProductId": 1719495,
"numberOfIntervals": 1,
"interval": "Monthly",
"chargeModels": [
{
"chargeModelType": "Signup",
"chargeTimingType": "StartOfPeriod",
"prorationGranularity": "Daily",
"prorateOnPositiveQuantity": false,
"prorateOnNegativeQuantity": false,
"reverseChargeOnNegativeQuantity": false,
"id": 56403857,
"uri": null
},
{
"chargeModelType": "Lifetime",
"chargeTimingType": "Immediate",
"prorationGranularity": "Daily",
"prorateOnPositiveQuantity": false,
"prorateOnNegativeQuantity": false,
"reverseChargeOnNegativeQuantity": false,
"id": 56403857,
"uri": null
}
],
"remainingInterval": null,
"groupQuantityChangeCharges": false,
"planProductPriceUplifts": null,
"customServiceDateNumberOfIntervals": 0,
"customServiceDateInterval": "Periods",
"customServiceDateProjection": "Future",
"earningInterval": "Monthly",
"earningNumberOfIntervals": 1,
"earningTimingInterval": "Daily",
"earningTimingType": "StartOfInterval",
"pricingModel": {
"pricingModelType": "Standard",
"quantityRanges": [
{
"min": 0,
"max": null,
"prices": [
{
"amount": 39.99,
"currency": "USD",
"id": 56403857,
"uri": null
}
],
"id": 0,
"uri": null
}
],
"id": 56403857,
"uri": null
},
"id": 56403857,
"uri": null
}
],
"resetType": "Never",
"planProductUniqueId": 1509277,
"id": 1719495,
"uri": ""
},
"quantity": 1,
"isIncluded": true,
"startDate": null,
"subscriptionProductOverride": null,
"subscriptionProductPriceOverride": null,
"chargeAtSubscriptionActivation": true,
"isCharged": true,
"subscriptionProductDiscount": null,
"subscriptionProductDiscounts": [
],
"customFields": null,
"monthlyRecurringRevenue": 39.99,
"netMonthlyRecurringRevenue": 39.99,
"amount": 39.99,
"status": "Active",
"lastPurchaseDate": "2017-05-12T21:36:31.0000794Z",
"earningSettings": {
"earningTimingInterval": "Daily",
"earningTimingType": "StartOfInterval"
},
"remainingInterval": null,
"groupQuantityChangeCharges": false,
"priceUpliftsEnabled": false,
"priceUplifts": [
],
"historicalPriceUplifts": [
],
"customServiceDateNumberOfIntervals": 0,
"customServiceDateInterval": "Periods",
"customServiceDateProjection": "Future",
"id": 56403857,
"uri": "https://qa-secure.fusebill.com/v1/SubscriptionProducts/56403857"
}
],
"remainingInterval": null,
"remainingIntervalPushOut": null,
"openSubscriptionPeriodEndDate": "2017-06-12T04:00:00",
"chargeDiscount": null,
"setupFeeDiscount": null,
"chargeDiscounts": null,
"setupFeeDiscounts": null,
"customFields": null,
"planAutoApplyChanges": false,
"autoApplyCatalogChanges": false,
"monthlyRecurringRevenue": 39.99,
"netMonthlyRecurringRevenue": 39.99,
"amount": 39.99,
"contractStartTimestamp": null,
"contractEndTimestamp": null,
"expiredTimestamp": null,
"coupons": [
],
"subscriptionHasRecurringEndOfPeriodCharge": false,
"id": 3135696,
"uri": "https://qa-secure.fusebill.com/v1/subscriptions/3135696"
}