Create Subscription

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. 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 Update Subscription page for more details. Subscriptions have a status of Draft when created and you will need to perform an additional action to Activate the Subscription. See the Activate Subscription page for details. Coupons can be provided when creating the subscription using the "couponCodes" value. The minimum request key-value pairs for a successful include fields "customerID" and "PlanFrequencyID".

This action will return the full Subscription object of the newly created Subscription. To include the full invoice in the response, include the parameter ?view=sideeffects as shown below

URL Parameters

Parameter NameTypeDescriptionRequired
viewEnum: {
sideeffects
}
When included and set to "sideeffects" the response will include a sideeffects object showing the resulting draft invoiceOptional
previewBooleanIf true, no subscription will be created. Instead a preview subscription will be returned containing an invoicePreview objectOptional
currency3 character ISO currency codeIf preview is set to true and no customerId is supplied in the body, this is a way to preview the invoice in the specified currency specified. The currency must be configured for your Fusebill accountOptional

Request Parameters

PropertyTypeDescriptionRequired
customerIDIntegerThis is the Fusebill ID of the customer.Yes, unless preview=true is set
taxationAddressObject. Defined belowIf preview=true this address is used to calculate taxes for the draft invoice preview. This allows for a tax preview without needing a customer ID.Optional
planFreqencyIDIntegerThis is the plan frequency ID that this subscription is based offYes
subscriptionOverrideObject. Defined below.This is an override of the name and description of this subscription if it differs from the planOptional
referenceStringThis will appear as the 3rd line item in the main subscription header on an invoice [Max Length: 255 characters]Optional
scheduledActivationTimestampDateTimeIt will accept a scheduled date in the future identifying when to Activate Subscription if it is placed into "Provisioning" Status. The submitted DateTime will automatically be interpreted in your account timezone. This field should be omited if the subscription should not be scheduled to activate in the future.Optional
remainingIntervalDecimalNumber of billing intervals that can iterate before the subscription status is set to "Expired".Optional
remainingIntervalPushOutDecimalNumber of billing intervals that are added to the Remaining interval counter whenever the expiry pushout button is pressed by the customer via the Self-Service-PortalOptional
contractStartTimestampDateTimeThis is the string of the contract start date returned in subscription reportsOptional
contractEndTimestampDateTimeThis is the string of the contract end date returned in subscription reportsOptional
billingPeriodIDIntegerThe unique id of an existing billing period on the customer that the subscription should be assigned toOptional
invoiceDayInteger (1-28)Tells the system to create a billing period that cycles on the specified day and assign this subscription to it. You can only specify an invoice day if the invoice rule "Prompt" (called 'Ask me each time' in the UI) is being used.Optional. Required when using the 'Prompt' invoice rule
invoiceMonthInteger (1-12)Tells the system to create a billing period that cycles on the specified day and month and assign this subscription to it. This parameter can only be used for subscriptions with an annual frequency. You can only specify an invoice month if the invoice rule "Prompt" (called 'Ask me each time' in the UI) is being used.Optional. Required when using the 'Prompt' invoice rule and yearly interval
couponCodesList of StringsCan hold a list of coupon codes to be automatically applied to the subscription at time of creation, Coupons can be pre-configured to apply specific discounts to specific subscription products on the subscriptionOptional
subscriptionProductsList of objects. Defined belowSpecifying a list of subscription product objects allows upfront overrides of certain plan product fields. This would not allow a means of providing additional products not specified as available in the underlying plan. Not providing this list means the collection of subscription products will have default settings.Optional

Taxation Address Fields

PropertyTypeDescription
line1Stringstandard line 1 of an address.

[Max Length: 60]
line2Stringstandard line 1 of an address.

[Max Length: 60]
countryIdIntegerThe ID of the country. Retrievable with the Read Country ID call.
stateIdIntegerThe ID of the state, province, or territory. Retrievable with the Read Country ID call.
cityStringThe city of the Customer.
postalZipStringThe postal code or zip code.

[Max Length: 10]

Subscription Override Fields

PropertyTypeDescription
NameStringThis 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]
DescriptionStringThis 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

PropertyTypeDescription
planProductUniqueIdIntegerThe Fusebill plan product unique ID. This is not the same as the plan product ID.
nameStringA name override for the subscription product [Max Length: 100 characters]
descriptionStringA description override for the subscription product [Max Length: 500 characters]
quantityDecimalThe quantity of the subscription product. Used for pricing calculations
isIncludedBooleanIf the subscription product is optional, this dictates its inclusion
priceDecimalIf the pricing model type is "Standard", this can be used to override the price. Otherwise use quantityRanges
pricingModelTypeEnum: {Standard, Tiered, Stairstep, Volume}Dictates how the price is calculated using the quantity. This is for the subscription product that is based on this plan product on this plan frequency.
quantityRangesList of Objects. Defined below.A collection of ranges that control the price of the subscription product based on its quantity field.
subscriptionProductDiscountsList of Objects. Defined below.A list of discounts that can directly be applied to the subscription product

Quantity Ranges Fields

PropertyTypeDescription
minDecimalThe lower bound of the range
maxDecimalThe upper bound of the range. Null is interpreted as infinity
priceDecimalThe price for this range

Subscription Product Discount

PropertyTypeDescription
discountTypeEnum:{ Percentage,
Amount, AmountPerUnit}
This field indicates the type of discount applied.
amountDecimalFor 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.
remainingUsagesUntilStartIntegerThis is the number of billing cycles which must pass before the discount is applied.
remainingUsageIntegerThis 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.
Examples
curl -X POST "https://secure.fusebill.com/v1/subscriptions" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"  \
  -d "{customerID:'310045',planFrequencyID: '19384'}"
//Json Payload
string jsonData = "{customerID:'310045',planFrequencyID: '19384'}";
//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 = "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:'310045',planFrequencyID: '19384'}"
#Pass in your URI, Payload and Headers
r = requests.post('https://secure.fusebill.com/v1/subscriptions', data=json.dumps(payload), headers=headers)
print(r.content)
{
  "CustomerID": 310045,
  "planFrequencyID": '19384'
}
{
   "planFrequencyId":456,
   "customerId":789,
   "subscriptionOverride":{
   	"Name":"newName",
   	"Description":"newDescription"
   },
   "reference":"custom Value",
   "scheduledActivationTimestamp":"2021-02-09",
   "remainingInterval":9,
   "remainingIntervalPushOut":2,
   "contractStartTimestamp":"2018-01-05T10:10:10",
   "contractEndTimestamp":"2028-01-05T10:10:10",
   "invoiceDay":7,
   "invoiceMonth":3,
   "couponCodes":[
   	"coupon_12",
   	"coupon_43"
   	]
}
{
  "customerId": 310045,
  "planFrequencyId": 19384,
  "subscriptionOverride": {
    "name": "override default name",
    "description": "override default description"
  },
  "scheduledActivationTimestamp": "2019-10-20",
  "reference": "sample reference string",

  "contractStartTimestamp": "2018-03-01",
  "contractEndTimestamp": "2018-03-01",
}
https://secure.fusebill.com/subscriptions?preview=true&view=sideeffects
{
    "taxationAddress": {
        "line1": "117 Waba Road",
        "line2": "UNIT 300",
        "countryId": 124,
        "stateId": 9,
        "city": "Pakenham",
        "postalZip": "K0A2X0"
    },
    "planFrequencyId": 22104
}
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,
                "generateZeroDollarCharge": false,
                "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",
            "generateZeroDollarCharge": false,
            "id": 56403857,
            "uri": "https://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,
    "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": 404,
    "Errors": [
        {
            "Key": "Api Error",
            "Value": "Plan with id 123 not found."
        }
    ]
}
Language
Authorization