Integrate with Fusebill's API to Automate Invoices, Payments and Collections

Dive into our comprehensive Documentation, API Reference and Tutorials to start working with the Fusebill Subscription Billing platform. Connect easily with Fusebill support to help get your integrations to market as quickly and as seamlessly as possible.

Get Started
 

Overview

The Fusebill API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

Fusebill Staging Account

Before you do anything, you should create a free Fusebill staging account that you can test the API against and register for an API key so that you can make API calls. Please contact support to create a staging account.

Example Requests

Sample API calls are provided next to each method using cURL, a standard command line tool. All you need to do is drop in your specific parameters, and you can test the calls from the command line. If the command line isn’t your preference, a great alternative is POSTMAN, an easy-to-use tool for making HTTP requests.

Sample workflows and tutorials walking you through common use cases and best practices are also available.

Fusebill uses the Fusebill API

In order to ensure our API serves the needs of our customers and is a pleasure for developers to use, the development team at Fusebill builds all of our account and customer-facing applications using the Fusebill API.

We want to ensure our API has a stable interface and performs well under the stresses of real-world use. To ensure we provide the best possible solutions to integrators, we first launch features against a private API resource. As we become confident in the interface and performance stability of these new resources, they may be made available through the Fusebill API.

Suggest Edits

Resources

 

API Resources URLs

Production Endpoint

The base URL for all Fusebill API calls is secure.fusebill.com. To this base you would append one of the URLs described in this documentation.

Example

secure.fusebill.com/v1/customers would return the list of customers from your production account.

Staging Endpoint

The base URL for staging Fusebill API calls is stg-secure.fusebill.com. To this base you would append one of the URLs described in this documentation.

Example

stg-secure.fusebill.com/v1/customers would return the list of customers from your staging account.

Note

All code samples and workflows in this documentation use the staging account URL.

Resource URLs

The Fusebill API resource URLs are structured in a limited hierarchy. There are a number of parent URLs followed by a number of child URLs. The child URLs return a list of child resources. Individual resources in this list are then accessed at parent URLs.

Example

v1/customers returns a list of customers
v1/customers/{id} returns a single customer
v1/customers/{id}/subscriptions returns a list of all subscriptions belonging to the customer
v1/subscriptions/{id} returns a single subscription

Each resource contains a URI that can be used to access it. We recommend following the URIs in the resources as opposed to hard coding URLs because it reduces the amount of work necessary to integrate and keep URL structure decoupled from your implementation.

Suggest Edits

Authentication

 

Authenticate your account when using the API by including your secret API key in the request. You can manage your API key in Fusebill's UI. Your API key carries many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value -H "Authorization: Basic YourAPIKeyHere" \. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Error Messages

Fusebill uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Fusebill's servers (these are rare). Basic codes below.

Error Code
Detail

200 - OK

Everything worked as expected

400 - Bad Request

The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications

401 - Unauthorized

Missing or invalid authorization.

Check your API Key and which environment the call is being made against.

404 - Not Found

The requested resource could not be found. Verify the endpoint in use, or the resource ID provided.

409 - Conflict

The format is valid but the request fails business rules. For example - activating a subscription that is already active

429 - Too Many Requests

API Rate limit has been exceeded.

500 - Server Error

System error with Fusebill API

Note

Not all errors map cleanly onto HTTP response codes, however, when a request is valid but does not complete successfully (e.g., a creating a customer), we return a 4xx error code.

Handling Errors

Our API libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions

Rate Limits

The Fusebill API is rate-limited under the following constraints:

  • Maximum of 1,000 requests per minute
  • Maximum of 180,000 requests per day

If either one of these maximums has been reached, an HTTP 429 error will be returned.
The body of the error will indicate which limit.

Example Error Response
{
   "ErrorId":0,
   "HttpStatusCode":400,
   "Errors":[
      {
         "Key":"Api Error",
         "Value":"Authorization key is not in the correct format."
      }
   ]
}
Suggest Edits

Pagination and Sorting

 

Paging

Pagination Example

GET stg-secure.fusebill.com/v1/customers?pageSize=1&pageNumber=5

Property
Type
Description

pageNumber

Integer

Zero based index for page to return

pageSize

Integer

Number of records to return

Several headers are returned to provide additional information about the pagination such as the previous/next page, and total # of results found.
X-Count will return the total amount of results.

Sorting

Sorting Example

GET stg-secure.fusebill.com/v1/customers?SortOrder=Ascending&SortExpression=ID

Property
Type
Description

sortOrder

String

Ascending, Descending

sortExpression

String

Property to sort on. Can be any root property of the response object.

In some cases you are able to verify the sorting by looking at the X-SortExpression and X-SortOrder headers in the HTTP response

Suggest Edits

Customer Object

The Customer object is a basic customer record in the Fusebill system. It includes the Customer ID that is used to make reference to the particular customer throughout the system. Each Customer ID is unique and automatically generated by the Fusebill system.

 

Customer Object Fields

Property
Type
Description

firstName

String

The first name of the Customer.

[Max Length: 50 characters]

middleName

String

The middle name of the Customer.

[Max Length: 50 characters]

lastName

String

The last name of the Customer.

[Max Length: 50 characters]

companyName

String

The company name associated with this Customer.

[Max Length: 50 characters]

suffix

String

The name suffix of the customer, for example Jr. or Sr.

[Max Length: 50 characters]

primaryEmail

String

The primary contact email for the Customer. Allows multiple entries in the format "emailA@email.ema; emailB@email.ema; emailC@email.ema". Invoices and other email communications will be sent to this address(s).

primaryPhone

String

The primary contact number for the Customer.

[Max Length: 50 characters]

secondaryEmail

String

The secondary contact email for the Customer. Allows multiple entries in the format "emailA@email.ema; emailB@email.ema; emailC@email.ema". No communications are sent to this address

secondaryPhone

String

The secondary contact number for the Customer.

[Max Length: 50 characters]

title

String

The prefix-title of the customer. Valid strings are: "Mr", "Mrs",
"Ms", "Miss" or "Dr".

[Max Length: 50 characters]

reference

String

This is a free form reference field where you can store a reference string for this customer. Generally, this is used to store the reference/Id of this Customer in some external system to facilitate matching up the Fusebill Customer record to that system.

[Max Length: 255 characters]

status

String

The status of the Customer. This reflects the state of the account and will indicate if the account is in "Draft", is "Active", is on "Hold", is "Suspended" or is "Cancelled". This field is not used to change status, only to show it.

[Read Only]

customerAccountStatus

String

The accounting status of the Customer. This reflects the financial status of the Customer and relates to if the Customer has past-due invoices. This field will show if the customer is in "Good" standing, is in "PoorStanding" or is in "Collection" status. Customer's enter Poor Standing if they have at least one (1) unpaid, overdue Invoice. This field is not used to change status, only to show it.

[Read Only]

currency

String

The Currency configured for this Customer. The currency is represented using a 3 Character ISO Currency code.

[Read Only]

customerReference

Collection

This is a collection of key. value pairs. Each can be used to store additional data related to this Customer including stalesTrackingCodes.

customerAcquisition

Object

This is a collection of Strings. Each can be used to store different details about how this Customer was acquired. Generally, this is used to store marketing channel information.

[Object see below for object definition]

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.

[Read Only]

netMonthlyRecurringRevenue

Decimal

The net MRR of the customer. Calculated by considering any discounts on the customers active subscription products. Number generated by Fusebill automatically.

[Read Only]

salesforceId

String

The Salesforce Account Id associated with this Customer. This field is only populated if you are using the Fusebill Salesforce plugin.

salesforceAccountType

String

This will dictate how the Salesforce account name will be created. Your options are:
1)"Company" where the company name and Fusebill Id will be combined and used as the account name
2)"Person" where the first and last names will be combined to populate the account name field.
3) NULL, the account level default will be used

salesforceSynchStatus

String

This setting controls if the account will synchronize the Fusebill account with Salesforce. The string options are "Enabled" or "Disabled"

[Read Only]

netsuiteId

String

If you are using a Netsuite integration this is the number which uniquely identifies the customer in Netsuite.

[Read Only]

netsuiteCustomerType

String

Identifies the customer type of the customer latched in NetSuite.
This field is only populated if you are using the Fusebill NetSuite plugin.
String, "Company" or "Individual", generated automatically by Fusebill, cannot be changed.

[Read Only]

portalUserName

String

If the customer has login credentials this field contains the username.

[Read Only]

parentId

long

The Parent Id key value relates to the Fusebill hierarchy feature. If hierarchy is enabled, the parent customer will have their own parentId and a child customer will display the id of their respective parent.​

[Read Only]

id

long

The id uniquely identifies the customer.

The id field is always included in any response from any applicable calls on a Customer. It is also often used as part a URL parameter on GET calls.

[Read Only]

uri

String

Full path to a particular customer object.

[Read Only]

Customer Reference Fields

Property
Type
Description

reference1

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

reference2

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

reference3

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

salesTrackingCodes

Collection

A collection of up to 5 SalesTrackingCode objects

[Object definition Below]

SalesTrackingCode Fields

Property
Type
Description

type

String

Identification of the sales tracking code type being set. The sales tracking code type can be configured under the sales tracking code section under your account settings

By default the accepted values are "Sales Tracking Code 1", "Sales Tracking Code 2" ... up to "Sales Tracking Code 5".

If you rename your Sales Tracking code, those names or the default names can be used.

**[Max default the accepted values are "Sales Tracking Code 1", "Sales Tracking Code 2" ... up to "Sales Tracking Code 5".

[Max Length: 255 characters]

code

String

The specific sales tracking code value. The code must exist under the appropriate salestrackingcode type being referenced

[Max Length: 255 characters]

name

String

Display name

description

String

Text field for additional information

email

String

Optional email field. String must be in valid email format.

Customer Acquisition Fields

Property
Type
Description

adContent

String

Typically used to set the content description for the campaign ad. For all campaigns, or for a particular campaign, this appears as Ad Content under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

campaign

String

This variable is used to define the name of your campaign, which appears in the Analytics reports on the top-level campaign report.

[Max Length: 255 characters]

keyword

String

These are the words that visitors use to find your Website when using a search engine. Google Analytics provides a list of keywords that have been searched by users who find your Website. This information shows you what searchers are actually looking for when they find your Website. This also allows you to discover potential new keywords to target.

[Max Length: 255 characters]

landingPage

String

The first page a visitor views during a session; also known as the entrance page.

[Max Length: 255 characters]

medium

String

Typically used to define the type of the campaign, such as a banner ad, email campaign, or click ad. For all campaigns, or for a particular campaign, this appears as Keyword under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

source

String

The source variable is typically used to define where the campaign is originating from, such as a website name or a company. For all campaigns, or for a particular campaign, this appears as Source under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

Suggest Edits

List Customers

This function is used to retrieve a list of Customer objects.

In order to manage the size of the data returned it is recommended that you control the number of records selected via the pagesize parameter. To return the most recent 20 customers created under an account

Get stg-secure.fusebill.com/v1/customers/?pageNumber=0&pageSize=20&sortOrder=descending&sortExpression=createdTimestamp

Note: the pagenumber parameter can be incremented in order to cycle through the customer base in groups of 20.

The query=field:queryString call supports a type of search and filter behavior using the query parameter. You can enter any field in the Customer record as the field value and the call will return only those Customers where the queryString provided matches the value of the field in the Customer record.

Note: this is an exact match query and partial matches are not supported. In addition, all Customer records which match the query will be returned as a list so this may return multiple Customers if the queryString is not unique across your Customers.

A common query is: /v1/customers/query=reference:{someString}

This query searches using the Customer Id field from the Fusebill admin interface (called reference in the API). The Customer Id (reference) field is often used to store unique identifiers for this Customer from some external system, such as a provisioning system. Some additional filtering and sorting features are available, see the paging article for those additional parameters.

 
gethttps://stg-secure.fusebill.com/v1/customers/?query=field:queryString
 

Customer Object Fields

Property
Type
Description

firstName

String

The first name of the Customer.

[Max Length: 50 characters]

middleName

String

The middle name of the Customer.

[Max Length: 50 characters]

lastName

String

The last name of the Customer.

[Max Length: 50 characters]

companyName

String

The company name associated with this Customer.

[Max Length: 50 characters]

suffix

String

The name suffix of the customer, for example Jr. or Sr.

[Max Length: 50 characters]

primaryEmail

String

The primary contact email for the Customer. Allows multiple entries in the format "emailA@email.ema; emailB@email.ema; emailC@email.ema". Invoices and other email communications will be sent to this address(s).

primaryPhone

String

The primary contact number for the Customer.

[Max Length: 50 characters]

secondaryEmail

String

The secondary contact email for the Customer. Allows multiple entries in the format "emailA@email.ema; emailB@email.ema; emailC@email.ema". No communications are sent to this address

secondaryPhone

String

The secondary contact number for the Customer.

[Max Length: 50 characters]

title

String

The prefix-title of the customer. Valid strings are: "Mr", "Mrs",
"Ms", "Miss" or "Dr".

[Max Length: 50 characters]

reference

String

This is a free form reference field where you can store a reference string for this customer. Generally, this is used to store the reference/Id of this Customer in some external system to facilitate matching up the Fusebill Customer record to that system.

[Max Length: 255 characters]

status

String

The status of the Customer. This reflects the state of the account and will indicate if the account is in "Draft", is "Active", is on "Hold", is "Suspended" or is "Cancelled". This field is not used to change status, only to show it.

[Read Only]

customerAccountStatus

String

The accounting status of the Customer. This reflects the financial status of the Customer and relates to if the Customer has past-due invoices. This field will show if the customer is in "Good" standing, is in "PoorStanding" or is in "Collection" status. Customer's enter Poor Standing if they have at least one (1) unpaid, overdue Invoice. This field is not used to change status, only to show it.

[Read Only]

currency

String

The Currency configured for this Customer. The currency is represented using a 3 Character ISO Currency code.

[Read Only]

customerReference

Collection

This is a collection of key. value pairs. Each can be used to store additional data related to this Customer including stalesTrackingCodes.

customerAcquisition

Object

This is a collection of Strings. Each can be used to store different details about how this Customer was acquired. Generally, this is used to store marketing channel information.

[Object see below for object definition]

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.

[Read Only]

netMonthlyRecurringRevenue

Decimal

The net MRR of the customer. Calculated by considering any discounts on the customers active subscription products. Number generated by Fusebill automatically.

[Read Only]

salesforceId

String

The Salesforce Account Id associated with this Customer. This field is only populated if you are using the Fusebill Salesforce plugin.

salesforceAccountType

String

This will dictate how the Salesforce account name will be created. Your options are:
1)"Company" where the company name and Fusebill Id will be combined and used as the account name
2)"Person" where the first and last names will be combined to populate the account name field.
3) NULL, the account level default will be used

salesforceSynchStatus

String

This setting controls if the account will synchronize the Fusebill account with Salesforce. The string options are "Enabled" or "Disabled"

[Read Only]

netsuiteId

String

If you are using a Netsuite integration this is the number which uniquely identifies the customer in Netsuite.

[Read Only]

netsuiteCustomerType

String

Identifies the customer type of the customer latched in NetSuite.
This field is only populated if you are using the Fusebill NetSuite plugin.
String, "Company" or "Individual", generated automatically by Fusebill, cannot be changed.

[Read Only]

portalUserName

String

If the customer has login credentials this field contains the username.

[Read Only]

parentId

long

The Parent Id key value relates to the Fusebill hierarchy feature. If hierarchy is enabled, the parent customer will have their own parentId and a child customer will display the id of their respective parent.​

[Read Only]

id

long

The id uniquely identifies the customer.

The id field is always included in any response from any applicable calls on a Customer. It is also often used as part a URL parameter on GET calls.

uri

String

[Read Only]

Customer Object Fields

Property
Type
Description

reference1

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

reference2

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

reference3

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

salesTrackingCodes

Collection

A collection of up to 5 SalesTrackingCode objects

[Object definition Below]

SalesTracking Code Fields

Property
Type
Description

type

String

Identification of the sales tracking code type being set. The sales tracking code type can be configured under the sales tracking code section under your account settings

[Max Length: 255 characters]

code

String

The specific sales tracking code value. The code must exist under the appropriate salestrackingcode type being referenced

[Max Length: 255 characters]

Customer Reference Fields

Property
Type
Description

adContent

String

Typically used to set the content description for the campaign ad. For all campaigns, or for a particular campaign, this appears as Ad Content under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

campaign

String

This variable is used to define the name of your campaign, which appears in the Analytics reports on the top-level campaign report.

[Max Length: 255 characters]

keyword

String

These are the words that visitors use to find your Website when using a search engine. Google Analytics provides a list of keywords that have been searched by users who find your Website. This information shows you what searchers are actually looking for when they find your Website. This also allows you to discover potential new keywords to target.

[Max Length: 255 characters]

landingPage

String

The first page a visitor views during a session; also known as the entrance page.

[Max Length: 255 characters]

medium

String

Typically used to define the type of the campaign, such as a banner ad, email campaign, or click ad. For all campaigns, or for a particular campaign, this appears as Keyword under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

source

String

The source variable is typically used to define where the campaign is originating from, such as a website name or a company. For all campaigns, or for a particular campaign, this appears as Source under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

Example
curl -X GET "https://stg-secure.fusebill.com/v1/customers?query=firstName:John" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//Query String
string queryString = "firstName:john";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customers/?query="+queryString);
//Add Content type
request.ContentType = "application/json";
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";      
//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 requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI, Payload and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/customers?query=firstName:John', headers=headers)
print(r.content)
Response
[
    {
        "firstName" : "John",
        "middleName" : "J",
        "lastName" : "Smith",
        "companyName" : "John Co.",
        "suffix" : "Jr",
        "primaryEmail" : "john@johnco.com",
        "primaryPhone" : "1-555-555-5555",
        "secondaryEmail" : null,
        "secondaryPhone" : null,
        "title" : "Mr",
        "reference" : "000001",
        "status" : "Active",
        "customerAccountStatus" : "Good",
        "activeSubscriptionsCount" : 2,
        "currency" : "USD",
        "customerReference" : {
            "reference1" : null,
            "reference2" : null,
            "reference3" : null,
            "id" : 32473,
            "uri" : "http://secure.fusebill.com/v1/customers/32473"
        },
        "customerAcquisition" : {
            "adContent" : null,
            "campaign" : null,
            "keyword" : null,
            "landingPage" : null,
            "medium" : null,
            "source" : null,
            "id" : 32473,
            "uri" : "http://secure.fusebill.com/v1/customers/32473"
        },
        "id" : 15,
        "uri" : "/v1/customers/15/"
    }, {
        "firstName" : "John",
        "middleName" : "J",
        "lastName" : "Smith",
        "companyName" : "John Co.",
        "suffix" : "Jr",
        "primaryEmail" : "john@johnco.com",
        "primaryPhone" : "1-555-555-5555",
        "secondaryEmail" : null,
        "secondaryPhone" : null,
        "title" : "Mr",
        "reference" : "000001",
        "status" : "Active",
        "customerAccountStatus" : "Good",
        "activeSubscriptionsCount" : 2,
        "currency" : "USD",
        "customerReference" : {
            "reference1" : null,
            "reference2" : null,
            "reference3" : null,
            "id" : 32473,
            "uri" : "http://secure.fusebill.com/v1/customers/32473"
        },
        "customerAcquisition" : {
            "adContent" : null,
            "campaign" : null,
            "keyword" : null,
            "landingPage" : null,
            "medium" : null,
            "source" : null,
            "id" : 32473,
            "uri" : "http://secure.fusebill.com/v1/customers/32473"
        },
        "id" : 15,
        "uri" : "/v1/customers/15/"
    }
]
Suggest Edits

Read Customer

This function is used to retrieve a Customer object. Specify the unique Fusebill ID of the customer as the id parameter in your request.

 
gethttps://stg-secure.fusebill.com/v1/customers/customerId
 

Property
Type
Description

customerId

integer

This is the id value which uniquely identifies a Customer record in the Fusebill system. This value is unique to each customer.

Examples
curl -X GET "https://stg-secure.fusebill.com/v1/customers/{customerId}" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//query parameter
int queryParameter = {customerId};
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customers/"+queryParameter);
//Add Content type
request.ContentType = "application/json";
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI, Payload and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/customers/183365', headers=headers)
print(r.content)
Response
{ 
   "firstName":"John",
   "middleName":null,
   "lastName":"Smith",
   "companyName":"Acme Inc.",
   "suffix":null,
   "primaryEmail":null,
   "primaryPhone":null,
   "secondaryEmail":null,
   "secondaryPhone":null,
   "title":"Mr",
   "reference":null,
   "status":"Draft",
   "customerAccountStatus":"Good",
   "currency":"USD",
   "customerReference":{ 
      "reference1":null,
      "reference2":null,
      "reference3":null,
      "salesTrackingCodes":[ 
      ],
      "id":169456,
      "uri":"https://stg-secure.fusebill.com/v1/customers/169456"
   },
   "customerAcquisition":{ 
      "adContent":null,
      "campaign":null,
      "keyword":null,
      "landingPage":null,
      "medium":null,
      "source":null,
      "id":169456,
      "uri":"https://stg-secure.fusebill.com/v1/customers/169456"
   },
   "monthlyRecurringRevenue":0.0000,
   "netMonthlyRecurringRevenue":0.0000,
   "salesforceId":null,
   "salesforceAccountType":null,
   "salesforceSynchStatus":"Enabled",
   "netsuiteId":null,
   "netsuiteCustomerType":"",
   "portalUserName":null,
   "parentId":null,
   "id":169456,
   "uri":"https://stg-secure.fusebill.com/v1/customers/169456"
}
Suggest Edits

Create Customer

This function is used to create a new Customer entity.

A successful result will return the id of the customer, otherwise known as the Fusebill ID. We recommend that you latch this unique ID into any system integrating with Fusebill.

It is possible to create a blank customer with no information, although we strongly recommend using at least some combination of firstName, lastName, comanyName, and primaryEmail as a bare minimum.

 
posthttps://stg-secure.fusebill.com/v1/customers
 

If your account is configured to use more than one currency, you must specify the currency of the customer at the time of creation.

  • If no value is set, the account default will be used.
  • This value can not be edited after the customer has been created.
  • A customer can only have one currency.

Sample Requests

POST https://stg-secure.fusebill.com/v1/customers
// Basic example to create a customer with a first/last name, company name, and email

{
    "firstName": "John",
    "lastName": "Smith",
    "companyName": "Fusebill",
    "primaryEmail": "test@example.com"
}


POST https://stg-secure.fusebill.com/v1/customers
// This example will post a customer, and override some accounts level billing settings

{  
   "firstName": "Bob",
   "companyName": "Fusebill",
   "billingSetting":[  
      {  
         "term":"N30",
         "autoCollect":true,
         "rechargeType":"",
         "rechargeThresholdAmount":null,
         "rechargeTargetAmount":null,
         "statusOnThreshold":null,
         "autoPostDraftInvoice":true,
         "customerGracePeriod":30,
         "gracePeriodExtension":null,
         "standingPoNumber":"PO#123",
         "acquisitionCost":200,
         "showZeroDollarCharges":"false",
         "taxExempt":true,
         "taxExemptCode":"123" ,
         "useCustomerBillingAddress":true,
         "avalaraUsageType":"",
         "vatIdentificationNumber":"",
         "customerServiceStartOption":"",
         "rollUpTaxes":null,
         "rollUpDiscounts":null
      
    		}
         ],
         
          "trackedItemDisplay":[
         	{
			"trackedItemDisplayFormat": null,
			"showTrackedItemName": null,
			"showTrackedItemReference": null,
			"showTrackedItemDescription": null,
			"showTrackedItemCreatedDate": null
         	}
         	]
         
      }
POST https://stg-secure.fusebill.com/v1/customers
// This example will post a customer with basic contact details, reference data, acquisition data, Salesforce/Quickbooks ID's, and a billing address

{  
   "firstName":"Trev",
   "middleName":null,
   "lastName":"Smith",
   "companyName":"Fusebill",
   "suffix":"text",
   "primaryEmail":"test@example.com",
   "primaryPhone":"123-456-7890",
   "secondaryEmail":"test2@example.com",
   "secondaryPhone":"123-456-7890",
   "title":"Dr",
   "currency":"USD",
   "customerReference":{  
      "reference1":"google",
      "reference2":null,
      "reference3":"linkedIn",
      "salesTrackingCodes":[  

      ]
   },
   "customerAcquisition":{  
      "adContent":null,
      "campaign":null,
      "keyword":null,
      "landingPage":null,
      "medium":null,
      "source":null
   },
   "salesforceId":null,
   "salesforceAccountType":null,
   "salesforceSynchStatus":"Enabled",
   "portalUserName":"portal9000",
   "parentId":null,
   "quickBooksLatchType":null,
   "quickBooksId":null,
   "quickBooksSyncToken":null,
   "billing":{  
      "companyName":"Fusebill",
      "line1":"109 Old House Street",
      "line2":"Suite 17",
      "city":"Sittsville",
      "postalZip":"12345",
      "country":"CA",
      "state":"NY"
   },

}
POST https://stg-secure.fusebill.com/v1/customers
// This customer will use a different currency 
// They also have separate billing & shipping addresses defined 

{  
   "firstName":"John",
   "lastName":"Smith",
   "companyName":"Fusebill",
   "primaryEmail":"test@example.com",
   "currency":"CAD",
   "billing":{  
      "companyName":"Billing Company",
      "line1":"109 Old House Street",
      "line2":"Suite 17",
      "city":"Sittsville",
      "postalZip":"12345",
      "country":"CA",
      "state":"NY"
   },
   "shipping":{  
      "companyName":"Shipping Company",
      "line1":"109 Old House Street",
      "line2":"Suite 17",
      "city":"Sittsville",
      "postalZip":"12345",
      "country":"CA",
      "state":"NY"
   }
}

Customer Object Fields

The fields in the tables below are all optional parameters that can be included in the customer POST.

Property
Type
Description

firstName

String

The first name of the Customer.

[Max Length: 50 characters]

middleName

String

The middle name of the Customer.

[Max Length: 50 characters]

lastName

String

The last name of the Customer.

[Max Length: 50 characters]

companyName

String

The company name associated with this Customer.

[Max Length: 50 characters]

suffix

String

The name suffix of the customer, for example Jr. or Sr.

[Max Length: 50 characters]

primaryEmail

String

The primary contact email for the Customer. Allows multiple entries in the format "emailA@email.ema; emailB@email.ema; emailC@email.ema". Invoices and other email communications will be sent to this address(s).

primaryPhone

String

The primary contact number for the Customer.

[Max Length: 50 characters]

secondaryEmail

String

The secondary contact email for the Customer. Allows multiple entries in the format "emailA@email.ema; emailB@email.ema; emailC@email.ema". No communications are sent to this address

secondaryPhone

String

The secondary contact number for the Customer.

[Max Length: 50 characters]

title

String

The prefix-title of the customer. Valid strings are: "Mr", "Mrs",
"Ms", "Miss" or "Dr".

[Max Length: 50 characters]

reference

String

This is a free form reference field where you can store a reference string for this customer. Generally, this is used to store the reference/Id of this Customer in some external system to facilitate matching up the Fusebill Customer record to that system.

[Max Length: 255 characters]

status

String

The status of the Customer. This reflects the state of the account and will indicate if the account is in "Draft", is "Active", is on "Hold", is "Suspended" or is "Cancelled". This field is not used to change status, only to show it.

[Read Only]

customerAccountStatus

String

The accounting status of the Customer. This reflects the financial status of the Customer and relates to if the Customer has past-due invoices. This field will show if the customer is in "Good" standing, is in "PoorStanding" or is in "Collection" status. Customer's enter Poor Standing if they have at least one (1) unpaid, overdue Invoice. This field is not used to change status, only to show it.

[Read Only]

currency

String

The Currency configured for this Customer. The currency is represented using a 3 Character ISO Currency code.

[Read Only]

customerReference

Object

This is a collection of key-value pairs. Each can be used to store additional data related to this Customer including salesTrackingCodes. [ see below for object definition]

billingSetting

Object

Customer billing settings. [ see below for object definition]

shipping

Object

Customer shipping address. [ see below for object definition]

billing

Object

Customer billing address.
[ see below for object definition]

addressPreference

Object

Set address preferences

[ see below for object definition]

customerReference

Object

Customer reference fields.

[ see below for object definition]

monthlyBillingPeriodConfiguration

Object

Monthly billing period definition for the customer.

[ see below for object definition]

yearlyBillingPeriodConfiguration

Object

Annual billing period definition for the customer.

[ see below for object definition]

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.

[Read Only]

netMonthlyRecurringRevenue

Decimal

The net MRR of the customer. Calculated by considering any discounts on the customers active subscription products. Number generated by Fusebill automatically.

[Read Only]

salesforceId

String

The Salesforce Account Id associated with this Customer. This field is only populated if you are using the Fusebill Salesforce plugin.

salesforceAccountType

String

This will dictate how the Salesforce account name will be created. Your options are:
1)"Company" where the company name and Fusebill Id will be combined and used as the account name
2)"Person" where the first and last names will be combined to populate the account name field.
3) NULL, the account level default will be used

salesforceSynchStatus

String

This setting controls if the account will synchronize the Fusebill account with Salesforce. The string options are "Enabled" or "Disabled"

netsuiteId

String

If you are using a Netsuite integration this is the number which uniquely identifies the customer in Netsuite.

[Read Only]

netsuiteCustomerType

String

Identifies the customer type of the customer latched in NetSuite.
This field is only populated if you are using the Fusebill NetSuite plugin.
String, "Company" or "Individual", generated automatically by Fusebill, cannot be changed.

[Read Only]

portalUserName

String

If the customer has login credentials this field contains the username.

[Read Only]

parentId

long

The parentId key value relates to the Fusebill hierarchy feature. If hierarchy is enabled, the parent customer will have their own parentId and a child customer will display the id of their respective parent.​

[Read Only]

id

long

The id uniquely identifies the customer.

The id field is always included in any response from any applicable calls on a Customer. It is also often used as part a URL parameter on GET calls.

uri

String

[Read Only]

Customer Billing/Shipping Address

Property
Type
Description

companyName

String

The company name associated with this Customer.

line1

String

Line 1 of the address

line2

String

Line 2 of the address

city

String

City

postalZip

String

Postal or ZIP code

country

String

Country using 2-character ISO code

state

String

State using 2-character ISO code

Customer Reference Fields

Property
Type
Description

reference1

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

reference2

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

reference3

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

salesTrackingCodes

Collection

A collection of up to 5 SalesTrackingCode objects

[Object definition Below]

SalesTracking Code Fields

Property
Type
Description

type

String

Identification of the sales tracking code type being set. The sales tracking code type can be configured under the sales tracking code section under your account settings

[Max Length: 255 characters]

code

String

The specific sales tracking code value. The code must exist under the appropriate salestrackingcode type being referenced

[Max Length: 255 characters]

Customer Reference Fields

Property
Type
Description

adContent

String

Typically used to set the content description for the campaign ad. For all campaigns, or for a particular campaign, this appears as Ad Content under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

campaign

String

This variable is used to define the name of your campaign, which appears in the Analytics reports on the top-level campaign report.

[Max Length: 255 characters]

keyword

String

These are the words that visitors use to find your Website when using a search engine. Google Analytics provides a list of keywords that have been searched by users who find your Website. This information shows you what searchers are actually looking for when they find your Website. This also allows you to discover potential new keywords to target.

[Max Length: 255 characters]

landingPage

String

The first page a visitor views during a session; also known as the entrance page.

[Max Length: 255 characters]

medium

String

Typically used to define the type of the campaign, such as a banner ad, email campaign, or click ad. For all campaigns, or for a particular campaign, this appears as Keyword under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

source

String

The source variable is typically used to define where the campaign is originating from, such as a website name or a company. For all campaigns, or for a particular campaign, this appears as Source under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

Customer BillingSetting

Property
Type
Description

term

String

This defines the Payment Terms for this Customer. Valid strings are "Net0", "Net10", "Net15", "Net30", "Net45", "Net60" and "Net90".

autocollect

String

This defines whether the billing system will automatically attempt to collect from the Customer's default payment method on file.

Valid values:
"true", "false", NULL (default)

rechargeType

String

This value should be set to "BringBalanceBackTo" in any case where you want to use the threshold billing feature.

rechargeThresholdAmount

String

This is the value which triggers a threshold collection. If the customer balance drops below this number when an invoice is posted the system will automatically collect enough funds to bring the balance back to the rechargeTargetAmount.

rechargeTargetAmount

Integer

This is the customer balance which will be collected when the customer balance dips below the threshold. For example, the threshold amount could be $20 and this value set to $50. In this case, the system will collect funds if to bring the balance back to $50 if the customer drops below $20

statusOnThreshold

Boolean

This setting determines if the customer should enter poor standing if their balance dips below the set threshold and the payment to restore the balance fails.

autoPostDraftInvoice

Boolean

This defines whether the billing system will attempt to automatically post draft Invoices against the Customer's account.

The global autoPostDraftInvoice setting is used by default and by setting this field explicitly on the Customer the setting can be overridden for this Customer.

If set to true then when an Invoice is generated in Draft status the Invoice will be automatically converted to a Posted invoice and the charges from the Invoice will be applied to the Customer. If set to false the billing system will not post the Invoices automatically. If set to NULL then the billing system will use the global autoPostDraftInvoice setting.

customerGracePeriod

Integer

This filed defines the number of days that the Customer is allowed to be in a PoorStanding status before the system will automatically place the Customer account in a Suspended state. Customer's enter PoorStanding when one or more Invoices go unpaid and enter an Overdue status.

gracePeriodExtension

Integer

This field is an add-on number of days which extends the Grace Period for this Customer. It is added to the normal Grace Period.

standingPoNumber

String

This is the PO number which will be added to this customer's invoices.

acquisitionCost

Integer

This is the cost in dollars spent to acquire this customer. This factors into the Customer Profitability metric.

showZeroDollarCharges

Boolean

This defines if this customer will show or not show $0 charges on their invoices. This can be either true, which means Fusebill will show charges, or false, which means Fusebill will hide these charges, or null which means the customer is using the account level default option.

taxExempt

Boolean

This defines if this customer should be charged taxes.

taxExemptCode

String

This is the tax exemption code for this customer. If taxExempt is set to True this field must be populated.

useCustomerBillingAddress

Boolean

If true, billing address is used as shipping address.

avalaraUsageType

String

This is a string sent to Alavara for determining the application of various sales taxes.

vatIdentificationNumber

Integer

The number associated with the clients EU Vat ID.

customerServiceStartOption

String

This setting allows you to specify how you would like the system to behave if a customer is automatically moved from Suspend Status back to Active status as a result of successfully auto-collecting outstanding balances.

rollUpTaxes

Boolean

This option determines if the taxes on the customer's invoices will appear 'rolled up' as one line (eg: Taxes: $4.56) or if the will be broken into multiple lines (eg: State Tax: $3.45 and Federal Tax: $1.34).

rollUpDiscounts

Boolean

trackedItemDisplay

collection

see trackedItemDisplayFormat object definition below.

trackedItemDisplayFormat Object

Property
Type
Description

showTrackedItemName

Boolean

showTrackedItemReference

Boolean

showTrackedItemDescription

Boolean

showTrackedItemCreatedDate

Boolean

Address Preference Object

Property
Type
Description

contactName

String

shippingInstructions

String

useBillingAddressAsShippingAddress

Boolean

If true, billing address is used as the shipping address.

Monthly Billing Period Object

Property
Type
Description

type

String

Billing period types. Available options are: CustomerActivation, FirstSubscriptionActivation, SpecifiedDate.

rule

String

Invoicing rule. Available options are: SingleInvoice, MultipleInvoices, Prompt, OneInvoicePerDay.

day

Integer (1-28)

Day of the month to begin invoicing.

Annual Billing Period Object

Property
Type
Description

type

String

Billing period types. Available options are: CustomerActivation, FirstSubscriptionActivation, SpecifiedDate.

rule

String

Invoicing rule. Available options are: SingleInvoice, MultipleInvoices, Prompt, OneInvoicePerDay.

month

Integer (1-12)

Month to begin annual invoicing.

day

Integer (1-28)

Day of the month to begin invoicing.

Examples
curl -X POST "https://stg-secure.fusebill.com/v1/customers" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{title:'Mr',firstName:'John',lastName:'Smith',companyName:'Acme Inc.'}"
//Json Payload
string jsonData = "{'firstName':'John', 'lastName':'Doe'}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customers");
//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 dict to the Payload parameter
payload = {'firstName': 'John', 'lastName': 'Smith'}
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/customers',data=json.dumps(payload), headers=headers)
print(r.content)
Response
{ 
   "firstName":"John",
   "middleName":null,
   "lastName":"Smith",
   "companyName":"Acme Inc.",
   "suffix":null,
   "primaryEmail":null,
   "primaryPhone":null,
   "secondaryEmail":null,
   "secondaryPhone":null,
   "title":"Mr",
   "reference":null,
   "status":"Draft",
   "customerAccountStatus":"Good",
   "currency":"USD",
   "customerReference":{  
      "reference1":null,
      "reference2":null,
      "reference3":null,
      "salesTrackingCodes":[  
      ],
      "id":169456,
      "uri":"https://stg-secure.fusebill.com/v1/customers/169456"
   },
   "customerAcquisition":{  
      "adContent":null,
      "campaign":null,
      "keyword":null,
      "landingPage":null,
      "medium":null,
      "source":null,
      "id":169456,
      "uri":"https://stg-secure.fusebill.com/v1/customers/169456"
   },
   "monthlyRecurringRevenue":0.0,
   "netMonthlyRecurringRevenue":0.0,
   "salesforceId":null,
   "salesforceAccountType":null,
   "salesforceSynchStatus":"Enabled",
   "netsuiteId":null,
   "netsuiteCustomerType":"",
   "portalUserName":null,
   "parentId":null,
   "id":169456,
   "uri":"https://stg-secure.fusebill.com/v1/customers/169456"
}
Suggest Edits

Activate Customer

This function allows you to activate a Customer currently in Draft status.

There are various parameters required when activating a draft customer. These options are activateAllSubscriptions , activateAllDraftPurchases and temporarilyDisableAutoPost. All of these parameters are required unless preview has been set to true, in which case only the customerID is required.

To include the full invoice object created from the activation , you can include the parameter view=sideeffects in the URL. This will cause the newly created invoice object to be included in the response.

 
posthttps://stg-secure.fusebill.com/v1/CustomerActivation?preview=preview&showzerodollarcharges=showzerodollarcharges&view=view
 

Sample Requests

POST https://stg-secure.fusebill.com/v1/customerActivation?Preview=true&showzerodollarcharges=true&view=sideeffects

//This request will preview the customer activation, and show any zero dollar charges on invoices. After this call the customer will still be in draft state. 

{
  "customerId": 8708457,
  "activateAllSubscriptions": true,
  "activateAllDraftPurchases": true,
  "temporarilyDisableAutoPost": false
}


POST https://stg-secure.fusebill.com/v1/customerActivation

//This request will activate the customer

{
  "customerId": 8708457,
  "activateAllSubscriptions": true,
  "activateAllDraftPurchases": true,
  "temporarilyDisableAutoPost": false
}
POST https://stg-secure.fusebill.com/v1/customerActivation?view=sideeffects

//This request will activate the customer, and the resulting response will include the invoice object within the payload. 

{
  "customerId": 8708457,
  "activateAllSubscriptions": true,
  "activateAllDraftPurchases": true,
  "temporarilyDisableAutoPost": false
}

Request Parameters

Property
Type
Description
Required

customerId

Decimal

This is the Fusebill ID of the customer

Yes

activateAllSubscriptions

Boolean

If True, draft subscriptions will be activated along with the customer

Yes, unless preview is set to true.

activateAllDraftPurchases

Boolean

If True, draft purchases will be activated along with the customer

Yes, unless preview is set to true.

temporarilyDisableAutoPost

Boolean

This will specify whether or not the resulting invoice from this call will post the related invoice or not

Yes, unless preview is set to true.

URL Parameters

Property
Type
Description

preview

String

If the Preview url parameter is set to True the customer is not activated, the call will simple simulate the activation and calculate the mock invoice.

showZeroDollarCharges

Boolean

If set to true, zero dollar charges will be included on invoices.

view

Sideeffects

Displays resulting invoices

Example
curl -X POST "https://stg-secure.fusebill.com/v1/CustomerActivation?preview=true" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{"customerId": 8708457, "activateAllSubscriptions": true,                            	   "activateAllDraftPurchases": true, "temporarilyDisableAutoPost": false}"
//Query string
string previewQuery = "false";
//Json Payload
string jsonData = "{
  "customerId": 8708457,
  "activateAllSubscriptions": true,
  "activateAllDraftPurchases": true,
  "temporarilyDisableAutoPost": false
}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/CustomerActivation?preview="+previewQuery);
//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 json
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": 8708457, "activateAllSubscriptions": true, "activateAllDraftPurchases": true, "temporarilyDisableAutoPost": false}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/CustomerActivation?preview=true',data=json.dumps(payload), headers=headers)
print(r.content)
Response
{
  "firstName": "John",
  "middleName": "B",
  "lastName": "Smith",
  "companyName": "Acme Inc",
  "suffix": "Sr",
  "primaryEmail": "jsmith@acme.com",
  "primaryPhone": "809997777",
  "secondaryEmail": "jdoe@gmail.com",
  "secondaryPhone": "1 (800) 445-6000",
  "title": "Mr",
  "reference": null,
  "status": "Active",
  "customerAccountStatus": "Good",
  "currency": "USD",
  "customerReference": {
    "reference1": null,
    "reference2": null,
    "reference3": null,
    "salesTrackingCodes": [],
    "id": 169494,
    "uri": "https://stg-secure.fusebill.com/v1/CustomerActivation/169494"
  },
  "customerAcquisition": {
    "adContent": null,
    "campaign": null,
    "keyword": null,
    "landingPage": null,
    "medium": null,
    "source": null,
    "id": 169494,
    "uri": "https://stg-secure.fusebill.com/v1/CustomerActivation/169494"
  },
  "monthlyRecurringRevenue": 0,
  "netMonthlyRecurringRevenue": 0,
  "salesforceId": null,
  "salesforceAccountType": null,
  "salesforceSynchStatus": "Enabled",
  "netsuiteId": null,
  "netsuiteCustomerType": "",
  "portalUserName": null,
  "parentId": null,
  "id": 169494,
  "uri": "https://stg-secure.fusebill.com/v1/CustomerActivation/169494"
}
Suggest Edits

Update Customer

This function is used to modify an existing Customer object.

Please Note: Most fields must be fully detailed in the JSON passed in as the body of the PUT – The system will nullify fields that are not included and detailed.

Minimum Request: Currency does not need to be included as it will default to your selected default currency. In all cases, include id and status even if you are not planning to change the status value as failing to do so will return an error from the system.

 
puthttps://stg-secure.fusebill.com/v1/customers
 

Customer Object

Property
Type
Description

firstName

String

The first name of the Customer.

[Max Length: 50 characters]

middleName

String

The middle name of the Customer.

[Max Length: 50 characters]

lastName

String

The last name of the Customer.

[Max Length: 50 characters]

companyName

String

The company name associated with this Customer.

[Max Length: 50 characters]

suffix

String

The name suffix of the customer, for example Jr. or Sr.

[Max Length: 50 characters]

primaryEmail

String

The primary contact email for the Customer. Allows multiple entries in the format "emailA@email.ema; emailB@email.ema; emailC@email.ema". Invoices and other email communications will be sent to this address(s).

primaryPhone

String

The primary contact number for the Customer.

[Max Length: 50 characters]

secondaryEmail

String

The secondary contact email for the Customer. Allows multiple entries in the format "emailA@email.ema; emailB@email.ema; emailC@email.ema". No communications are sent to this address

secondaryPhone

String

The secondary contact number for the Customer.

[Max Length: 50 characters]

title

String

The prefix-title of the customer. Valid strings are: "Mr", "Mrs",
"Ms", "Miss" or "Dr".

[Max Length: 50 characters]

reference

String

This is a free form reference field where you can store a reference string for this customer. Generally, this is used to store the reference/Id of this Customer in some external system to facilitate matching up the Fusebill Customer record to that system.

[Max Length: 255 characters]

status

String

The status of the Customer. This reflects the state of the account and will indicate if the account is in "Draft", is "Active", is on "Hold", is "Suspended" or is "Cancelled". This field is not used to change status, only to show it.

[Read Only]

customerAccountStatus

String

The accounting status of the Customer. This reflects the financial status of the Customer and relates to if the Customer has past-due invoices. This field will show if the customer is in "Good" standing, is in "PoorStanding" or is in "Collection" status. Customer's enter Poor Standing if they have at least one (1) unpaid, overdue Invoice. This field is not used to change status, only to show it.

[Read Only]

currency

String

The Currency configured for this Customer. The currency is represented using a 3 Character ISO Currency code.

[Read Only]

customerReference

Collection

This is a collection of key. value pairs. Each can be used to store additional data related to this Customer including stalesTrackingCodes.

customerAcquisition

Object

This is a collection of Strings. Each can be used to store different details about how this Customer was acquired. Generally, this is used to store marketing channel information.

[Object see below for object definition]

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.

[Read Only]

netMonthlyRecurringRevenue

Decimal

The net MRR of the customer. Calculated by considering any discounts on the customers active subscription products. Number generated by Fusebill automatically.

[Read Only]

salesforceId

String

The Salesforce Account Id associated with this Customer. This field is only populated if you are using the Fusebill Salesforce plugin.

salesforceAccountType

String

This will dictate how the Salesforce account name will be created. Your options are:
1)"Company" where the company name and Fusebill Id will be combined and used as the account name
2)"Person" where the first and last names will be combined to populate the account name field.
3) NULL, the account level default will be used

salesforceSynchStatus

String

This setting controls if the account will synchronize the Fusebill account with Salesforce. The string options are "Enabled" or "Disabled"

netsuiteId

String

If you are using a Netsuite integration this is the number which uniquely identifies the customer in Netsuite.

[Read Only]

netsuiteCustomerType

String

Identifies the customer type of the customer latched in NetSuite.
This field is only populated if you are using the Fusebill NetSuite plugin.
String, "Company" or "Individual", generated automatically by Fusebill, cannot be changed.

[Read Only]

portalUserName

String

If the customer has login credentials this field contains the username.

[Read Only]

parentId

long

The Parent Id key value relates to the Fusebill hierarchy feature. If hierarchy is enabled, the parent customer will have their own parentId and a child customer will display the id of their respective parent.​

[Read Only]

id

long

The id uniquely identifies the customer.

The id field is always included in any response from any applicable calls on a Customer. It is also often used as part a URL parameter on GET calls.

uri

String

[Read Only]

Customer Reference

Property
Type
Description

reference1

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

reference2

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

reference3

String

An optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]

salesTrackingCodes

Collection

A collection of up to 5 SalesTrackingCode objects

[Object definition Below]

SalesTracking Code Fields

Property
Type
Description

type

String

Identification of the sales tracking code type being set. The sales tracking code type can be configured under the sales tracking code section under your account settings

[Max Length: 255 characters]

code

String

The specific sales tracking code value. The code must exist under the appropriate salestrackingcode type being referenced

[Max Length: 255 characters]

Customer Reference Fields

Property
Type
Description

adContent

String

Typically used to set the content description for the campaign ad. For all campaigns, or for a particular campaign, this appears as Ad Content under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

campaign

String

This variable is used to define the name of your campaign, which appears in the Analytics reports on the top-level campaign report.

[Max Length: 255 characters]

keyword

String

These are the words that visitors use to find your Website when using a search engine. Google Analytics provides a list of keywords that have been searched by users who find your Website. This information shows you what searchers are actually looking for when they find your Website. This also allows you to discover potential new keywords to target.

[Max Length: 255 characters]

landingPage

String

The first page a visitor views during a session; also known as the entrance page.

[Max Length: 255 characters]

medium

String

Typically used to define the type of the campaign, such as a banner ad, email campaign, or click ad. For all campaigns, or for a particular campaign, this appears as Keyword under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

source

String

The source variable is typically used to define where the campaign is originating from, such as a website name or a company. For all campaigns, or for a particular campaign, this appears as Source under the Segment pull-down in the Analytics Reports.

[Max Length: 255 characters]

Examples
curl -X PUT "https://stg-secure.fusebill.com/v1/customers" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{id:{id},title:'Mr',firstName:'John',lastName:'Smith',companyName:'Acme Inc.',Status:'Active'}"
//Json Payload
string jsonData = "{'firstName':'John','middleName':'B','lastName':'Smith','companyName':'Acme Inc','suffix':'Sr','primaryEmail':'jsmith@acme.com','primaryPhone':'809997777','secondaryEmail':'jdoe@gmail.com','secondaryPhone':'1 (800) 445-6000','title':'Mr','reference':null,'status':'Cancelled','customerAccountStatus':'Good','currency':'USD','customerReference':{'reference1':null,'reference2':null,'reference3':null,'salesTrackingCodes':[],'id':169458},'customerAcquisition':{'adContent':null,'campaign':null,'keyword':null,'landingPage':null,'medium':null,'source':null,'id':169458},'monthlyRecurringRevenue':0,'netMonthlyRecurringRevenue':0,'salesforceId':null,'salesforceAccountType':null,'salesforceSynchStatus':'Enabled','netsuiteId':null,'netsuiteCustomerType':'','portalUserName':null,'parentId':null,'id':169458}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customers");
//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 dict to the Payload parameter
payload = {'id': 183365, 'firstName': 'john', 'lastName': 'smith', 'Status': 'Active'}
#Pass in your URI, Payload and Headers
r = requests.put('https://stg-secure.fusebill.com/v1/customers', data=json.dumps(payload), headers=headers)
print(r.content)
Response
{
    "firstName": "Alex",
    "middleName": "A",
    "lastName": "Dokes",
    "companyName": null,
    "suffix": null,
    "primaryEmail": "m@123.com",
    "primaryPhone": "613.729.2698",
    "secondaryEmail": null,
    "secondaryPhone": null,
    "title": "Mr",
    "reference": null,
    "status": "Active",
    "customerAccountStatus": "Good",
    "currency": "USD",
    "customerReference": {
        "reference1": null,
        "reference2": null,
        "reference3": null,
        "salesTrackingCodes": [
            {
                "type": "Sales Tracking Code 1",
                "code": "testdata",
                "name": "Test Data",
                "id": 3982,
                "uri": "https://stg-secure.fusebill.com/v1/SalesTrackingCodes/3982"
            }
        ],
        "id": 144085,
        "uri": "https://stg-secure.fusebill.com/v1/customers/144085"
    },
    "customerAcquisition": {
        "adContent": null,
        "campaign": null,
        "keyword": null,
        "landingPage": null,
        "medium": null,
        "source": null,
        "id": 144085,
        "uri": "https://stg-secure.fusebill.com/v1/customers/144085"
    },
    "monthlyRecurringRevenue": 1500,
    "netMonthlyRecurringRevenue": 1500,
    "salesforceId": null,
    "salesforceAccountType": null,
    "salesforceSynchStatus": "Enabled",
    "netsuiteId": null,
    "netsuiteCustomerType": "",
    "portalUserName": null,
    "parentId": null,
    "id": 144085,
    "uri": "https://stg-secure.fusebill.com/v1/customers/144085"
}
Suggest Edits

Read Customer Overview

This resource is used to retrieve a short form customer object with some additional payment and account balance information. Ideal for quickly checking if a customer has an unpaid balance, has a credit, or pending charges.

 
gethttps://stg-secure.fusebill.com/v1/customers/id/Overview
 
Property
Type
Description

id

Integer

This is the the Id value which uniquely identifies this Customer record in the Fusebill system. This value is unique to each customer.

Examples
curl -X GET "https://stg-secure.fusebill.com/v1/customers/{id}/Overview" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//Path parameter, Fusebill Id which corresponds to the customerId 
int pathParameter = {customerId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customers/"+pathParameter+"/Overview");
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI, Payload and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/customers/{id}/overview', headers=headers)
print(r.content)
Response
{
    "title": "",
    "firstName": "Max ",
    "middleName": null,
    "lastName": "Tractive",
    "suffix": null,
    "companyName": null,
    "reference": null,
    "createdTimestamp": "2016-08-22T15:31:07",
    "status": "Active",
    "customerAccountStatus": "Good",
    "pendingCharges": 0,
    "arBalance": 0,
    "unallocatedPayments": 0,
    "unallocatedCredits": 0,
    "unallocatedOpeningBalance": 0,
    "currency": "USD",
    "daysUntilSuspension": 0,
    "customerAccountStatusTimestamp": "2016-08-22T15:31:07",
    "statusTimestamp": "2016-08-22T15:31:21",
    "lifetimeValue": 50,
    "monthlyRecurringRevenue": 500,
    "netMonthlyRecurringRevenue": 500,
    "nextBillingDate": "2016-09-01T04:00:00",
    "salesforceSynchStatus": "Enabled",
    "parentId": 131638,
    "parentName": "Matthew Larrivee (Fusebill)",
    "isParent": false,
    "id": 132059,
    "uri": "https://stg-secure.fusebill.com/v1/Customers/132059"
}
Suggest Edits

Create Customer Note

This function is used to create a new Customer note.

 
posthttps://stg-secure.fusebill.com/v1/customerNotes
 
Property
Type
Description

customerid

Integer

This is the the Id value which uniquely identifies this Customer record in the Fusebill system. This value is unique to each customer.

note

String

The is the string of text you wish to store on a customer.

createdTimestamp

DateTime

This indicates when the note was created.

Examples
curl -X POST \
  https://stg-secure.fusebill.com/v1/CustomerNotes \
  -H 'Authorization: Basic {APIKey}' \
  -H 'Content-Type: application/json' \
  -d '{
	"note":"Sample",
	"customerid":{CustomerId}
}'
//Json data, Fusebill Id which corresponds to the customerId Field
string jsonData = "{'customerId':{customerId},'note':'Test Note String'}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customerNotes");
//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},"note":"Sample customer note"}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/customerNotes', data=json.dumps(payload), headers=headers)
print(r.content)
Response
{
   "userWhoCreatedNote":"API - User not specified",
   "note":"Test Note String",
   "createdTimestamp":"2015-07-31T15:33:46.0008354Z"
}
Suggest Edits

Hold Customer

This function is used to put a customer on the hold status. Any subscriptions on the customer will be placed into status suspended.

 
posthttps://stg-secure.fusebill.com/v1/CustomerHold/id
 
Property
Type
Description

id

integer

This is the id value which uniquely identifies a Customer record in the Fusebill system. This value is unique to each customer.

Examples
curl -X POST "https://stg-secure.fusebill.com/v1/CustomerHold/{id}" \
	-H "Content-Type: application/json" \
	-H "Content-Length: 0" \
	-H "Authorization: Basic {APIKey}"
//path parameter, Fusebill Id which corresponds to the Id Field Returned by Create/Update customer
int pathParameter = {id};
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/CustomerHold/"+pathParameter);
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "POST";
//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 your URI and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/customerHold/{id}', headers=headers)
print(r.content)
Response
{
  "firstName":"Test 2",
  "middleName":null,
  "lastName":null,
  "companyName":null,
  "suffix":null,
  "primaryEmail":"Jdoe@domain.com",
  "primaryPhone":null,
  "secondaryEmail":null,
  "secondaryPhone":null,
  "title":"",
  "reference":null,
  "status":"Active",
  "customerAccountStatus":"Good",
  "currency":"USD",
  "customerReference":{
    "reference1":null,
    "reference2":null,
    "reference3":null,
    "salesTrackingCodes":[

    ],
    "id":38884,
    "uri":"/38884"
  },
  "customerAcquisition":{
    "adContent":null,
    "campaign":null,
    "keyword":null,
    "landingPage":null,
    "medium":null,
    "source":null,
    "id":38884,
    "uri":"/38884"
  },
  "monthlyRecurringRevenue":165,
  "netMonthlyRecurringRevenue":165,
  "salesforceId":null,
  "salesforceAccountType":null,
  "salesforceSynchStatus":"Enabled",
  "netsuiteId":null,
  "netsuiteCustomerType":"",
  "portalUserName":"Jdoe",
  "id":38884,
  "uri":"/38884"
}
Suggest Edits

Un-Hold Customer

This function is used to remove the hold status from a customer.

 
posthttps://stg-secure.fusebill.com/v1/customers/unHold
 
Property
Type
Description

customerId

Integer

This is the the Id value which uniquely identifies this
Customer record in the Fusebill system. This value is unique to each customer.

serviceStartOption

String

When the customer is taken off of the Hold status, you are given a number of options for collection of outstanding funds owing. Allowable Service Start Option are:
ChargeForAllMissedPeriods, ChargeForLastMissedPeriods, NoChargesForMissedPeriods, ChargeForCurrentFullPeriod".

preview

boolean

If the Preview url parameter is set to True the customer is not taken off hold, the call will simply simulate the unhold action and calculate the mock invoice.

showZeroDollarCharges

boolean

Zero dollar charges are those charges that are usually one-time set-ups or physical goods needed for new user account set-up.

temporarilyDisableAutoPost

boolean

This key allows you to temporarily disable invoice post for the collection of outstanding amounts owing.

prorate

boolean

This indicates if this Subscription should prorate its charges if activated in the middle of a billing cycle.

Examples
curl -X POST "https://stg-secure.fusebill.com/v1/customers/unHold" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{id:{id},serviceStartOption:'ChargeForCurrentFullPeriod',showZeroDollarCharges:false,temporarilyDisableAutoPost:false,prorate:false,preview:true}"
//Json data, Fusebill Id which corresponds to the customerId Field
string jsonData = "{'id':{id},'serviceStartOption':'ChargeForCurrentFullPeriod','preview':false,'showZeroDollarCharges':false,'temporarilyDisableAutoPost':false,'prorate':false}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customers/unHold");
//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 dict to the Payload parameter
payload = {'customerId':{id},"serviceStartOption":"ChargeForAllMissedPeriods","preview":'false',"showZeroDollarCharges":'false',"temporarilyDisableAutoPost":'false'}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/customers/unHold', data=json.dumps(payload), headers=headers)
print(r.content)
Response
{
    "firstName": "Horses",
    "middleName": null,
    "lastName": null,
    "companyName": null,
    "suffix": null,
    "primaryEmail": null,
    "primaryPhone": null,
    "secondaryEmail": null,
    "secondaryPhone": null,
    "title": "",
    "reference": null,
    "status": "Suspended",
    "customerAccountStatus": "PoorStanding",
    "currency": "USD",
    "customerReference": {
        "reference1": null,
        "reference2": null,
        "reference3": null,
        "salesTrackingCodes": [
        ],
        "id": 84189,
        "uri": "/84189"
    },
    "customerAcquisition": {
        "adContent": null,
        "campaign": null,
        "keyword": null,
        "landingPage": null,
        "medium": null,
        "source": null,
        "id": 84189,
        "uri": "/84189"
    },
    "monthlyRecurringRevenue": 0,
    "netMonthlyRecurringRevenue": 0,
    "salesforceId": null,
    "salesforceAccountType": null,
    "salesforceSynchStatus": "Enabled",
    "netsuiteId": null,
    "netsuiteCustomerType": "",
    "portalUserName": null,
    "id": 84189,
    "uri": "/84189"
}
Suggest Edits

Cancel Customer

This function allows you to cancel a Customer currently in any non-cancelled status. Canceling a Customer also cancels Subscriptions associated with that customer. Cancelling applies the same cancellationOption to the Subscriptions as was specified in the Customer Cancellation action. For example, full will refund the Customer the full value of each Subscription active on their account.

 
posthttps://stg-secure.fusebill.com/v1/customerCancellation
 
Property
Type
Description

customerId

integer

The customerId value uniquely identifies a Customer record in the Fusebill system. This value is unique to each customer.

cancellationOption

String

This field defines if the Customer receives a refund when Subscriptions are cancelled. Valid string are "None", "Unearned", "Full". None indicates the Customer will not receive a refund. Unearned indicates the customer will receive the Unearned revenue, this is commonly called the Prorated Amount. Full indicates the customer will receive a full refund for the current billing period. String, Valid string are "None", "Unearned", "Full".

Examples
curl HTTPS://stg-secure.fusebill.com/v1/CustomerCancellation \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{customerId:{Id}, cancellationOption:'None'}"
//Json Payload
string jsonData = "{'customerId':{Id}, 'cancellationOption':'None'}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customerCancellation");
//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 dict to the Payload parameter
payload = {'customerId': {id}, 'cancellationOption': 'None'}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/customerCancellation',data=json.dumps(payload), headers=headers)
print(r.content)
Response
No Content
Suggest Edits

Uncancel Customer

This function is used to un-cancel a previously cancelled customer.

 
posthttps://stg-secure.fusebill.com/v1/customers/uncancel/id
 
Property
Type
Description

id

integer

This is the id value which uniquely identifies a Customer record in the Fusebill system. This value is unique to each customer.

Examples
curl -X POST "https://stg-secure.fusebill.com/v1/customers/uncancel/{id}" \
	-H "Content-Type: application/json" \
	-H "Content-Length: 0" \
	-H "Authorization: Basic {APIKey}"
//path parameter, Fusebill Id which corresponds to the Id Field Returned by Create/Update customer
int pathParameter = {id}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customers/uncancel/"+pathParameter);
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "POST";
//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 your URI and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/customers/uncancel/{id}', headers=headers)
print(r.content)
Response
{
  "firstName": "John",
  "middleName": "B",
  "lastName": "Smith",
  "companyName": "Acme Inc",
  "suffix": null,
  "primaryEmail": null,
  "primaryPhone": null,
  "secondaryEmail": null,
  "secondaryPhone": null,
  "title": "Mr",
  "reference": null,
  "status": "Active",
  "customerAccountStatus": "Good",
  "currency": "USD",
  "customerReference": {
    "reference1": null,
    "reference2": null,
    "reference3": null,
    "salesTrackingCodes": [],
    "id": 135482,
    "uri": "https://secure.fusebill.com/v1/Customers/135482"
  },
  "customerAcquisition": {
    "adContent": null,
    "campaign": null,
    "keyword": null,
    "landingPage": null,
    "medium": null,
    "source": null,
    "id": 135482,
    "uri": "https://secure.fusebill.com/v1/Customers/135482"
  },
  "monthlyRecurringRevenue": 0,
  "netMonthlyRecurringRevenue": 0,
  "salesforceId": "00141000005sMDzAAM",
  "salesforceAccountType": null,
  "salesforceSynchStatus": "Enabled",
  "netsuiteId": null,
  "netsuiteCustomerType": "",
  "portalUserName": null,
  "parentId": null,
  "id": 135482,
  "uri": "https://secure.fusebill.com/v1/Customers/135482"
}
Suggest Edits

Customer Email Object

The customer email object defines the email messages and preferences a customer should receive. Messages include "Credit Card Expiry Notices", "Invoice Overdue Notices" and others.

 

Currently, there are preference entities for the following emailTypes

  • InvoicePost
  • PaymentReceived
  • InvoiceOverdue
  • PasswordReset
  • PaymentFailed
  • CustomerActivation
  • SubscriptionActivation
  • SubscriptionCancellation
  • CustomerCredentialCreate
  • CustomerCredentialPasswordReset
  • CustomerSuspend
  • PaymentMethodUpdate
  • CreditCardExpiry
  • StatementNotification
  • UpcomingBillingNotification
  • Refund
  • PendingExpiryRenewalNotice

Additional preference entities may be added in the future so when editing the email preferences via the API it is suggested to always perform a GET to retrieve the full email preferences list and to then modify the data in that list and PUT that list to perform the edit action. This ensures the PUT action includes all the required preference entities.

Customer Email Preferences Fields

Field
Type
Description

id

long

This is the Fusebill ID of the customer to whom these preferences apply.

preferences

Collection

This is the list of Preference entities.

[Preferences Object described below]

Preferences Object Fields

Field
Type
Description

enabled

String

Specify whether or not the specified email notification is enabled. Values should be one of: "true", "false" or NULL (account default)

Note: To override the account default setting you must specify a value of either "true" or "false"

emailType

String

Used to specify which email notification. Valid values are any of the following:
"InvoicePost", "PaymentReceived", "InvoiceOverdue", "PasswordReset", "PaymentFailed", "CustomerActivation", "SubscriptionActivation", "SubscriptionCancellation", "CustomerCredentialCreate", "CustomerCredentialPasswordReset", "CustomerSuspend", "PaymentMethodUpdate", "CreditCardExpiry", "StatementNotification", "UpcomingBillingNotification", "Refund", "PendingExpiryRenewalNotice"

emailCategory

String

Describes the general category of the email. Mostly for internal use.

[Read Only]

Suggest Edits

Read Customer Email Preferences

This function allows you to get the email preferences for a specific customer.

 
gethttps://stg-secure.fusebill.com/v1/customers/id/CustomerEmailPreferences
 
Property
Type
Description

customerId

Integer

This is the the Id value which uniquely identifies this Customer record in the Fusebill system. This value is unique to each customer.

Field
Type
Description

customerId

long

This is the Fusebill ID of the customer to whom these preferences apply.

preferences

Collection

This is the list of Preference entities.

[Preferences Object described below]

Preferences Object Fields

Field
Type
Description

enabled

String

Specify whether or not the specified email notification is enabled. Values should be one of: "true", "false" or NULL (account default)

Note: To override the account default setting you must specify a value of either "true" or "false"

emailType

String

Used to specify which email notification. Valid values are any of the following:
"InvoicePost", "PaymentReceived", "InvoiceOverdue", "PasswordReset", "PaymentFailed", "CustomerActivation", "SubscriptionActivation", "SubscriptionCancellation", "CustomerCredentialCreate", "CustomerCredentialPasswordReset", "CustomerSuspend", "PaymentMethodUpdate", "CreditCardExpiry", "StatementNotification", "UpcomingBillingNotification", "Refund", "PendingExpiryRenewalNotice"

emailCategory

String

Describes the general category of the email. Mostly for internal use.

[Read Only]

Examples
curl -X GET "https://stg-secure.fusebill.com/v1/customers/{customerId}/CustomerEmailPreferences" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//path parameter, Fusebill Id which corresponds to the Id Field Returned by Create/Update customer
int pathParameter = {customerId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customers/"+pathParameter+"/CustomerEmailPreferences");
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/customers/{id}/CustomerEmailPreferences', headers=headers)
print(r.content)
Response
{
    "customerId": 6737347,
    "preferences": [
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "CreditCardExpiry",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "CustomerActivation",
            "emailCategory": "Customers"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "CustomerCredentialCreate",
            "emailCategory": "Customers"
        },
        {
            "enabled": false,
            "accountDefault": true,
            "emailType": "CustomerCredentialPasswordReset",
            "emailCategory": "Customers"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "CustomerSuspend",
            "emailCategory": "Customers"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "InvoiceOverdue",
            "emailCategory": "InvoicesAndStatements"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "InvoicePost",
            "emailCategory": "InvoicesAndStatements"
        },
        {
            "enabled": false,
            "accountDefault": true,
            "emailType": "PaymentFailed",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "PaymentMethodUpdate",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "PaymentReceived",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "PendingExpiryRenewalNotice",
            "emailCategory": "Subscriptions"
        },
        {
            "enabled": true,
            "accountDefault": false,
            "emailType": "Refund",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "StatementNotification",
            "emailCategory": "InvoicesAndStatements"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "SubscriptionActivation",
            "emailCategory": "Subscriptions"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "SubscriptionCancellation",
            "emailCategory": "Subscriptions"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "UpcomingBillingNotification",
            "emailCategory": "InvoicesAndStatements"
        }
    ]
}
Suggest Edits

Update Customer Email Preferences

This call allows you to edit the customer email preferences for a specific customer. You must include all the preference entities in the call to perform the edit action, even if you are not modifying some of those preference entities.

 
puthttps://stg-secure.fusebill.com/v1/CustomerEmailPreferences
 
Field
Type
Description

customerId

long

This is the Fusebill ID of the customer to whom these preferences apply.

preferences

Collection

This is the list of Preference entities.

[Preferences Object described below]

Preferences Object Fields

Field
Type
Description

enabled

String

Specify whether or not the specified email notification is enabled. Values should be one of: "true", "false" or NULL (account default)

Note: To override the account default setting you must specify a value of either "true" or "false"

emailType

String

Used to specify which email notification. Valid values are any of the following:
"InvoicePost", "PaymentReceived", "InvoiceOverdue", "PasswordReset", "PaymentFailed", "CustomerActivation", "SubscriptionActivation", "SubscriptionCancellation", "CustomerCredentialCreate", "CustomerCredentialPasswordReset", "CustomerSuspend", "PaymentMethodUpdate", "CreditCardExpiry", "StatementNotification", "UpcomingBillingNotification", "Refund", "PendingExpiryRenewalNotice"

emailCategory

String

Describes the general category of the email. Mostly for internal use.

[Read Only]

Examples
curl -X PUT "https://stg-secure.fusebill.com/v1/CustomerEmailPreferences" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{'customerId':{customerId},'preferences':[{'enabled':true,'accountDefault':false,'emailType':'CreditCardExpiry','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'CustomerActivation','emailCategory':'Customers'},{'enabled':false,'accountDefault':false,'emailType':'CustomerCredentialCreate','emailCategory':'Customers'},{'enabled':false,'accountDefault':true,'emailType':'CustomerCredentialPasswordReset','emailCategory':'Customers'},{'enabled':false,'accountDefault':false,'emailType':'CustomerSuspend','emailCategory':'Customers'},{'enabled':false,'accountDefault':false,'emailType':'InvoiceOverdue','emailCategory':'InvoicesAndStatements'},{'enabled':false,'accountDefault':false,'emailType':'InvoicePost','emailCategory':'InvoicesAndStatements'},{'enabled':false,'accountDefault':true,'emailType':'PaymentFailed','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'PaymentMethodUpdate','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'PaymentReceived','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'PendingExpiryRenewalNotice','emailCategory':'Subscriptions'},{'enabled':true,'accountDefault':false,'emailType':'Refund','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'StatementNotification','emailCategory':'InvoicesAndStatements'},{'enabled':false,'accountDefault':false,'emailType':'SubscriptionActivation','emailCategory':'Subscriptions'},{'enabled':false,'accountDefault':false,'emailType':'SubscriptionCancellation','emailCategory':'Subscriptions'},{'enabled':false,'accountDefault':false,'emailType':'UpcomingBillingNotification','emailCategory':'InvoicesAndStatements'}]}"
//Json Payload, Replace this customer Id with the FusebillId of the customer you would like to update
string jsonData = "{'customerId':{customerId},'preferences':[{'enabled':false,'accountDefault':false,'emailType':'CreditCardExpiry','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'CustomerActivation','emailCategory':'Customers'},{'enabled':false,'accountDefault':false,'emailType':'CustomerCredentialCreate','emailCategory':'Customers'},{'enabled':false,'accountDefault':true,'emailType':'CustomerCredentialPasswordReset','emailCategory':'Customers'},{'enabled':false,'accountDefault':false,'emailType':'CustomerSuspend','emailCategory':'Customers'},{'enabled':false,'accountDefault':false,'emailType':'InvoiceOverdue','emailCategory':'InvoicesAndStatements'},{'enabled':false,'accountDefault':false,'emailType':'InvoicePost','emailCategory':'InvoicesAndStatements'},{'enabled':false,'accountDefault':true,'emailType':'PaymentFailed','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'PaymentMethodUpdate','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'PaymentReceived','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'PendingExpiryRenewalNotice','emailCategory':'Subscriptions'},{'enabled':true,'accountDefault':false,'emailType':'Refund','emailCategory':'PaymentsAndRefunds'},{'enabled':false,'accountDefault':false,'emailType':'StatementNotification','emailCategory':'InvoicesAndStatements'},{'enabled':false,'accountDefault':false,'emailType':'SubscriptionActivation','emailCategory':'Subscriptions'},{'enabled':false,'accountDefault':false,'emailType':'SubscriptionCancellation','emailCategory':'Subscriptions'},{'enabled':false,'accountDefault':false,'emailType':'UpcomingBillingNotification','emailCategory':'InvoicesAndStatements'}]}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/CustomerEmailPreferences");
//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},"preferences":

[{"enabled":None,"accountDefault":"false","emailType":"CreditCardExpiry","emailCategory":"PaymentsAndRefunds"},

{"enabled":None,"accountDefault":"false","emailType":"CustomerActivation","emailCategory":"Customers"},

{"enabled":None,"accountDefault":"false","emailType":"CustomerCredentialCreate","emailCategory":"Customers"},

{"enabled":None,"accountDefault":"true","emailType":"CustomerCredentialPasswordReset","emailCategory":"Customers"},

{"enabled":None,"accountDefault":"false","emailType":"CustomerSuspend","emailCategory":"Customers"},

{"enabled":None,"accountDefault":"false","emailType":"DraftInvoice","emailCategory":"InvoicesAndStatements"},

{"enabled":None,"accountDefault":"false","emailType":"InvoiceOverdue","emailCategory":"InvoicesAndStatements"},

{"enabled":None,"accountDefault":"false","emailType":"InvoicePost","emailCategory":"InvoicesAndStatements"},

{"enabled":None,"accountDefault":"false","emailType":"PaymentFailed","emailCategory":"PaymentsAndRefunds"},

{"enabled":None,"accountDefault":"false","emailType":"PaymentMethodUpdate","emailCategory":"PaymentsAndRefunds"},

{"enabled":None,"accountDefault":"true","emailType":"PaymentReceived","emailCategory":"PaymentsAndRefunds"},

{"enabled":None,"accountDefault":"false","emailType":"PendingExpiryRenewalNotice","emailCategory":"Subscriptions"},

{"enabled":None,"accountDefault":"false","emailType":"Refund","emailCategory":"PaymentsAndRefunds"},

{"enabled":None,"accountDefault":"false","emailType":"StatementNotification","emailCategory":"InvoicesAndStatements"},

{"enabled":None,"accountDefault":"false","emailType":"SubscriptionActivation","emailCategory":"Subscriptions"},

{"enabled":None,"accountDefault":"false","emailType":"SubscriptionCancellation","emailCategory":"Subscriptions"},

{"enabled":None,"accountDefault":"false","emailType":"UpcomingBillingNotification","emailCategory":"InvoicesAndStatements"}]}
#Pass in your URI, Payload and Headers
r = requests.put('https://stg-secure.fusebill.com/v1/CustomerEmailPreferences', data=json.dumps(payload), headers=headers)
print(r.content)
Response
{
    "customerId": 6737347,
    "preferences": [
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "CreditCardExpiry",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "CustomerActivation",
            "emailCategory": "Customers"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "CustomerCredentialCreate",
            "emailCategory": "Customers"
        },
        {
            "enabled": false,
            "accountDefault": true,
            "emailType": "CustomerCredentialPasswordReset",
            "emailCategory": "Customers"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "CustomerSuspend",
            "emailCategory": "Customers"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "InvoiceOverdue",
            "emailCategory": "InvoicesAndStatements"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "InvoicePost",
            "emailCategory": "InvoicesAndStatements"
        },
        {
            "enabled": false,
            "accountDefault": true,
            "emailType": "PaymentFailed",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "PaymentMethodUpdate",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "PaymentReceived",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "PendingExpiryRenewalNotice",
            "emailCategory": "Subscriptions"
        },
        {
            "enabled": true,
            "accountDefault": false,
            "emailType": "Refund",
            "emailCategory": "PaymentsAndRefunds"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "StatementNotification",
            "emailCategory": "InvoicesAndStatements"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "SubscriptionActivation",
            "emailCategory": "Subscriptions"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "SubscriptionCancellation",
            "emailCategory": "Subscriptions"
        },
        {
            "enabled": false,
            "accountDefault": false,
            "emailType": "UpcomingBillingNotification",
            "emailCategory": "InvoicesAndStatements"
        }
    ]
}
Suggest Edits

Customer Billing Object

The customer billing settings resource defines the billing settings for the customer. In specific, these preferences control the payment terms and grace period applied to the customer as well as whether invoices auto post to the account and whether payments are automatically collected from credit card or ACH accounts on file.

Additional preferences may be added in the future so when editing the customer billing settings via the API it is suggested to always perform a GET to retrieve the full customer billing settings list and to then modify the data in that response and PUT that response to perform the edit action. This ensures the PUT action includes all the required customer billing settings fields.

 

Customer Billing Settings Fields

Property
Type
Description

invoiceDay

Int

This field is deprecated and no longer used.

[Read Only]

term

String

This defines the Payment Terms for this Customer. Valid strings are "Net0", "Net10", "Net15", "Net30", "Net45", "Net60" and "Net90".

interval

String

This field is deprecated and no longer used.

[Read Only]

autoCollect

String

This defines whether the billing system will attempt to collect from the Customer's payment method on file.

The global autoCollect setting is used by default and by setting this field explicitly on the Customer the setting can be overridden for this Customer. This setting can only be explicitly set to True if the customer has a Payment Method, such as a credit card of ACH account, on file.

If set to true then when charges are applied to the Customer the billing system will attempt to collect them in full form the payment method on file. If set to false the billing system will not collect automatically. If set to NULL then the billing system will use the global autoCollect setting.

rechargeType

String

This value should be set to "BringBalanceBackTo" in any case where you want to use the threshold billing feature.

rechargeThresholdAmount

String

This is the value which triggers a threshold collection. If the customer balance drops below this number when an invoice is posted the system will automatically collect enough funds to bring the balance back to the rechargeTargetAmount.

rechargeTargetAmount

String

This is the customer balance which will be collected when the customer balance dips below the threshold. For example, the threshold amount could be $20 and this value set to $50. In this case, the system will collect funds if to bring the balance back to $50 if the customer drops below $20.

statusOnThreshold

String

This setting determines if the customer should enter poor standing if their balance dips below the set threshold and the payment to restore the balance fails.

standingPoNumber

String

This is the PO number which will be added to this customer's invoices.

billingPeriodConfigurations

Object

This list is populated it the billing settings at the customer level have been overridden.

acquisitionCost

Decimal

This is the cost in dollars spent to acquire this customer. This factors into the Customer Profitability metric.

showZeroDollarCharges

String

This defines if this customer will show or not show $0 charges on their invoices. This can be either true, which means Fusebill will show charges, or false, which means Fusebill will hide these charges, or null which means the customer is using the account level default option.

taxExempt

Boolean

This defines if this customer should be charged taxes.

useCustomerBillingAddress

Boolean

This key-value pair allows you to set whether you want to use shipping address or billing address for taxation purposes. Available values include Null, True or False. If you choose "Null" - the system will use the customer's account level tax setting configuration, if set to "True" - the system will use the customer's billing address for taxes, if set to "False" - the system will use the customer's shipping address for taxes.

taxExemptCode

String

This is the tax exemption code for this customer. If taxExempt is set to True this field must be populated.

avalaraUsageType

String

This is a string sent to Alavara for determining the application of various sales taxes.

vatIdentificationNumber

Integer

The number associated with the clients EU Vat ID.

customerServiceStartOption

String

This setting allows you to specify how you would like the system to behave if a customer is automatically moved from Suspend Status back to Active status as a result of successfully auto-collecting outstanding balances.

rollUpTaxes

Boolean

This option determines if the taxes on the customer's invoices will appear 'rolled up' as one line (eg: Taxes: $4.56) or if the will be broken into multiple lines (eg: State Tax: $3.45 and Federal Tax: $1.34).

rollUpDiscounts

Boolean

customerBillingStatementSetting

Object

defaultPaymentMethodId

Int

id

String

This is the Customer ID of the customer to whom these preferences apply.

uri

String

Suggest Edits

Read Customer Billing Settings

This function allows you to get the Customer Billing Settings for a specific customer. In your request, the customerID is the primary unique identifier on the customer profile.

 
gethttps://stg-secure.fusebill.com/v1/customerbillingsetting/customerId
 

Customer Billing Settings Fields

Field
Data Type
Description

id

Integer

This is the Customer ID of the customer to whom these preferences apply.

invoiceDay

Integer

This is the day of the month on which the Customer will be billed for their services. Currently, all invoices will line up to this date.

term

String

This defines the Payment Terms for this Customer. Valid strings are "Net0", "Net10", "Net15", "Net30", "Net45", "Net60" and "Net90".

internal

String

This field is used by the billing engine and should not be modified.

autoCollect

Boolean

This defines whether the billing system will attempt to collect from the Customer's payment method on file.

The global autoCollect setting is used by default and by setting this field explicitly on the Customer the setting can be overridden for this Customer. This setting can only be explicitly set to True if the customer has a Payment Method, such as a credit card of ACH account, on file.

If set to true then when charges are applied to the Customer the billing system will attempt to collect them in full form the payment method on file. If set to false the billing system will not collect automatically. If set to NULL then the billing system will use the global autoCollect setting.

rechargeType

String

This value should be set to "BringBalanceBackTo" in any case where you want to use the threshold billing feature.

rechargeThresholdAmount

Integer

This is the value which triggers a threshold collection. If the customer balance drops below this number when an invoice is posted the system will automatically collect enough funds to bring the balance back to the rechargeTargetAmount.

useCustomerBillingAddress

Boolean

This key-value pair allows you to set whether you want to use shipping address or billing address for taxation purposes. Available values include Null, True or False. If you choose "Null" - the system will use the customer's account level tax setting configuration, if set to "True" - the system will use the customer's billing address for taxes, if set to "False" - the system will use the customer's shipping address for taxes.

rechargeTargetAmount

Currency

This is the customer balance which will be collected when the customer balance dips below the threshold. For example, the threshold amount could be $20 and this value set to $50. In this case, the system will collect funds if to bring the balance back to $50 if the customer drops below $20.

statusOnThreshold

Boolean

This setting determines if the customer should enter poor standing if their balance dips below the set threshold and the payment to restore the balance fails.

autoPostDraftInvoice

Boolean

This defines whether the billing system will attempt to automatically post draft Invoices against the Customer's account.

The global autoPostDraftInvoice setting is used by default and by setting this field explicitly on the Customer the setting can be overridden for this Customer.

If set to true then when an Invoice is generated in Draft status the Invoice will be automatically converted to a Posted invoice and the charges from the Invoice will be applied to the Customer. If set to false the billing system will not post the Invoices automatically. If set to NULL then the billing system will use the global autoPostDraftInvoice setting.

hasPaymentMethod

Boolean

This flag indicates if the customer has a Payment Method, such as a credit card of ACH account, on file.

customerGracePeriod

Integer

This filed defines the number of days that the Customer is allowed to be in a PoorStanding status before the system will automatically place the Customer account in a Suspended state. Customer's enter PoorStanding when one or more Invoices go unpaid and enter an Overdue status.

gracePeriodExtension

Integer

This field is an add-on number of days which extends the Grace Period for this Customer. It is added to the normal Grace Period.

standingPoNumber

String

This is the PO number which will be added to this customer's invoices.

billingPeriodConfigurations

String Collection

This list is populated it the billing settings at the customer level have been overridden.

acquisitionCost

Currency

This is the cost in dollars spent to acquire this customer. This factors into the Customer Profitability metric.

showZeroDollarCharges

Boolean

This defines if this customer will show or not show $0 charges on their invoices. This can be either true, which means Fusebill will show charges, or false, which means Fusebill will hide these charges, or null which means the customer is using the account level default option.

taxExempt

Boolean

This defines if this customer should be charged taxes.

taxExemptCode

String

This is the tax exemption code for this customer. If taxExempt is set to True this field must be populated.

avalaraUsageType

String

This is a string sent to Alavara for determining the application of various sales taxes.

vatIdentificationNumber

Integer

The number associated with the clients EU Vat ID

customerServiceStartOption

String

This setting allows you to specify how you would like the system to behave if a customer is automatically moved from Suspend Status back to Active status as a result of successfully auto-collecting outstanding balances.

rollUpTaxes

Boolean

This option determines if the taxes on the customer's invoices will appear 'rolled up' as one line (eg: Taxes: $4.56) or if the will be broken into multiple lines (eg: State Tax: $3.45 and Federal Tax: $1.34).

trackedItemDisplay

Collection

This option is a collection of boolean objects for invoice display options of tracked items.

billingPeriodConfigurations object

Field
Data Type
Description

type

String

Possible values are "FirstSubscriptionActivation", "CustomerActivation", or "SpecifiedDate".

rule

String

Possible values are "OneInvoicePerDay", "SingleInvoice", "MultipleInvoices", "Prompt".

interval

String

"Yearly" or "Monthly"

day

Integer

Required if using type of "SpecifiedDate"

month

integer

Required if using type of "SpecifiedDate" and interval of "Yearly"

Examples
curl -X GET "https://stg-secure.fusebill.com/v1/customerbillingsetting/{customerId}" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//path parameter, Fusebill Id which corresponds to the Id returned by Get Customer
int pathParameter = {customerId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customerbillingsetting/"+pathParameter);
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI, Payload and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/CustomerBillingSetting/{id}', headers=headers)
print(r.content)
Response
{
    "invoiceDay": -1,
    "term": "Net30",
    "interval": "Monthly",
    "autoCollect": null,
    "rechargeType": "",
    "rechargeThresholdAmount": null,
    "rechargeTargetAmount": null,
    "statusOnThreshold": null,
    "autoPostDraftInvoice": null,
    "hasPaymentMethod": true,
    "customerGracePeriod": null,
    "gracePeriodExtension": null,
    "standingPoNumber": null,
    "billingPeriodConfigurations": [
        {
            "type": "FirstSubscriptionActivation",
            "rule": "OneInvoicePerDay",
            "interval": "Monthly",
            "day": null,
            "month": null
        },
        {
            "type": "FirstSubscriptionActivation",
            "rule": "OneInvoicePerDay",
            "interval": "Yearly",
            "day": null,
            "month": null
        }
    ],
    "acquisitionCost": 0,
    "showZeroDollarCharges": null,
    "taxExempt": false,
    "useCustomerBillingAddress": null,
    "taxExemptCode": null,
    "avalaraUsageType": null,
    "vatIdentificationNumber": null,
    "customerServiceStartOption": "",
    "rollUpTaxes": null,
    "rollUpDiscounts": null,
    "trackedItemDisplay": null,
    "customerBillingStatementSetting": {
        "option": null,
        "type": null,
        "interval": null,
        "day": null,
        "month": null,
        "trackedItemDisplay": null
    },
    "defaultPaymentMethodId": 142291,
    "id": 342780,
    "uri": "https://stg-secure.fusebill.com/v1/customerbillingsetting/342780"
}
Suggest Edits

Update Customer Billing Settings

This function allows you to override the default customer billing settings for a specific customer.

Recommended Request: We recommend that the invoiceDay field either be omitted or the value set to null for the PUT method.

 
puthttps://stg-secure.fusebill.com/v1/customerbillingsetting
 

Customer Billing Settings Fields

Field
Data Type
Description

id

Integer

This is the Customer ID of the customer to whom these preferences apply.

invoiceDay

Integer

This is the day of the month on which the Customer will be billed for their services. Currently, all invoices will line up to this date.

term

String

This defines the Payment Terms for this Customer. Valid strings are "Net0", "Net10", "Net15", "Net30", "Net45", "Net60" and "Net90".

internal

String

This field is used by the billing engine and should not be modified.

autoCollect

Boolean

This defines whether the billing system will attempt to collect from the Customer's payment method on file.

The global autoCollect setting is used by default and by setting this field explicitly on the Customer the setting can be overridden for this Customer. This setting can only be explicitly set to True if the customer has a Payment Method, such as a credit card of ACH account, on file.

If set to true then when charges are applied to the Customer the billing system will attempt to collect them in full form the payment method on file. If set to false the billing system will not collect automatically. If set to NULL then the billing system will use the global autoCollect setting.

rechargeType

String

This value should be set to "BringBalanceBackTo" in any case where you want to use the threshold billing feature.

rechargeThresholdAmount

Integer

This is the value which triggers a threshold collection. If the customer balance drops below this number when an invoice is posted the system will automatically collect enough funds to bring the balance back to the rechargeTargetAmount.

useCustomerBillingAddress

Boolean

This key-value pair allows you to set whether you want to use shipping address or billing address for taxation purposes. Available values include Null, True or False. If you choose "Null" - the system will use the customer's account level tax setting configuration, if set to "True" - the system will use the customer's billing address for taxes, if set to "False" - the system will use the customer's shipping address for taxes.

rechargeTargetAmount

Currency

This is the customer balance which will be collected when the customer balance dips below the threshold. For example, the threshold amount could be $20 and this value set to $50. In this case, the system will collect funds if to bring the balance back to $50 if the customer drops below $20.

statusOnThreshold

Boolean

This setting determines if the customer should enter poor standing if their balance dips below the set threshold and the payment to restore the balance fails.

autoPostDraftInvoice

Boolean

This defines whether the billing system will attempt to automatically post draft Invoices against the Customer's account.

The global autoPostDraftInvoice setting is used by default and by setting this field explicitly on the Customer the setting can be overridden for this Customer.

If set to true then when an Invoice is generated in Draft status the Invoice will be automatically converted to a Posted invoice and the charges from the Invoice will be applied to the Customer. If set to false the billing system will not post the Invoices automatically. If set to NULL then the billing system will use the global autoPostDraftInvoice setting.

hasPaymentMethod

Boolean

This flag indicates if the customer has a Payment Method, such as a credit card of ACH account, on file.

customerGracePeriod

Integer

This filed defines the number of days that the Customer is allowed to be in a PoorStanding status before the system will automatically place the Customer account in a Suspended state. Customer's enter PoorStanding when one or more Invoices go unpaid and enter an Overdue status.

gracePeriodExtension

Integer

This field is an add-on number of days which extends the Grace Period for this Customer. It is added to the normal Grace Period.

standingPoNumber

String

This is the PO number which will be added to this customer's invoices.

billingPeriodConfigurations

String Collection

This list is populated it the billing settings at the customer level have been overridden.

acquisitionCost

Currency

This is the cost in dollars spent to acquire this customer. This factors into the Customer Profitability metric.

showZeroDollarCharges

Boolean

This defines if this customer will show or not show $0 charges on their invoices. This can be either true, which means Fusebill will show charges, or false, which means Fusebill will hide these charges, or null which means the customer is using the account level default option.

taxExempt

Boolean

This defines if this customer should be charged taxes.

taxExemptCode

String

This is the tax exemption code for this customer. If taxExempt is set to True this field must be populated.

avalaraUsageType

String

This is a string sent to Alavara for determining the application of various sales taxes.

vatIdentificationNumber

Integer

The number associated with the clients EU Vat ID

customerServiceStartOption

String

This setting allows you to specify how you would like the system to behave if a customer is automatically moved from Suspend Status back to Active status as a result of successfully auto-collecting outstanding balances.

rollUpTaxes

Boolean

This option determines if the taxes on the customer's invoices will appear 'rolled up' as one line (eg: Taxes: $4.56) or if the will be broken into multiple lines (eg: State Tax: $3.45 and Federal Tax: $1.34).

trackedItemDisplay

Collection

This option is a collection of boolean objects for invoice display options of tracked items.

Examples
curl -X PUT "https://stg-secure.fusebill.com/v1/customerbillingsetting" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{id:{customerId},invoiceDay:null,term:'Net0',interval:'Monthly',autoCollect:null,rechargeType:'',rechargeThresholdAmount:null,rechargeTargetAmount:null,statusOnThreshold:null,autoPostDraftInvoice:null,hasPaymentMethod:false,customerGracePeriod:null,gracePeriodExtension:null,standingPoNumber:null,billingPeriodConfigurations:[],acquisitionCost:0,showZeroDollarCharges:null,taxExempt:false,useCustomerBillingAddress:true,taxExemptCode:null,avalaraUsageType:null,vatIdentificationNumber:null,customerServiceStartOption:'',rollUpTaxes:null,rollUpDiscounts:null,trackedItemDisplay:null,customerBillingStatementSetting:{option:null,type:null,interval:null,day:null,month:null,trackedItemDisplay:null}}"
//Json data
string jsonData ="{id:{{customerId},invoiceDay:null,term:'Net0',interval:'Monthly',autoCollect:null,rechargeType:'',rechargeThresholdAmount:null,rechargeTargetAmount:null,statusOnThreshold:null,autoPostDraftInvoice:null,hasPaymentMethod:false,customerGracePeriod:null,gracePeriodExtension:null,standingPoNumber:null,billingPeriodConfigurations:[],acquisitionCost:0,showZeroDollarCharges:null,taxExempt:false,useCustomerBillingAddress:true,taxExemptCode:null,avalaraUsageType:null,vatIdentificationNumber:null,customerServiceStartOption:'',rollUpTaxes:null,rollUpDiscounts:null,trackedItemDisplay:null,customerBillingStatementSetting:{option:null,type:null,interval:null,day:null,month:null,trackedItemDisplay:null}}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customerbillingsetting");
//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 = {"invoiceDay": None,"term": "Net10","interval": "Monthly","autoCollect": None,"rechargeType": "","rechargeThresholdAmount": 

None,"rechargeTargetAmount": None,"statusOnThreshold": None,"autoPostDraftInvoice": None,"hasPaymentMethod": "false","customerGracePeriod": 

None,"gracePeriodExtension": None,"standingPoNumber": None,"billingPeriodConfigurations": [],"acquisitionCost": 0,"showZeroDollarCharges": None,"taxExempt": 

"false","useCustomerBillingAddress": None,"taxExemptCode": None,"avalaraUsageType": None,"vatIdentificationNumber": None,"customerServiceStartOption": 

"","rollUpTaxes": None,"rollUpDiscounts": None,"trackedItemDisplay": None,"customerBillingStatementSetting": {"option": None,"type": None,"interval": 

None,"day": None,"month": None,"trackedItemDisplay": None},"defaultPaymentMethodId": None,"id": {id},"uri": None}
#Pass in your URI, Payload and Headers
r = requests.put('https://stg-secure.fusebill.com/v1/customerBillingSetting/{id}', data=json.dumps(payload), headers=headers)
print(r.content)
Response
{
    "invoiceDay": null,
    "term": "Net30",
    "interval": "Monthly",
    "autoCollect": null,
    "rechargeType": "",
    "rechargeThresholdAmount": null,
    "rechargeTargetAmount": null,
    "statusOnThreshold": null,
    "autoPostDraftInvoice": null,
    "hasPaymentMethod": true,
    "customerGracePeriod": null,
    "gracePeriodExtension": null,
    "standingPoNumber": null,
    "billingPeriodConfigurations": [
        {
            "type": "CustomerActivation",
            "rule": "OneInvoicePerDay",
            "interval": "Monthly",
            "day": null,
            "month": null
        },
        {
            "type": "FirstSubscriptionActivation",
            "rule": "OneInvoicePerDay",
            "interval": "Yearly",
            "day": null,
            "month": null
        }
    ],
    "acquisitionCost": 0,
    "showZeroDollarCharges": null,
    "taxExempt": false,
    "useCustomerBillingAddress": null,
    "taxExemptCode": null,
    "avalaraUsageType": null,
    "vatIdentificationNumber": null,
    "customerServiceStartOption": "",
    "rollUpTaxes": null,
    "rollUpDiscounts": null,
    "trackedItemDisplay": null,
    "customerBillingStatementSetting": {
        "option": null,
        "type": null,
        "interval": null,
        "day": null,
        "month": null,
        "trackedItemDisplay": null
    },
    "defaultPaymentMethodId": 142291,
    "id": 342780,
    "uri": "https://stg-secure.fusebill.com/v1/customerbillingsetting/342780"
}
Suggest Edits

Customer Address Preferences Object

The customer address preferences object acts as a link between a customer resource and their billing and (optionally) shipping addresses. The preferences resource returns both billing and shipping addresses if they exist along with other address related information like which address should be used for shipping or the optional fields for the contact name and shipping instructions.

 

Customer Address Preferences Fields

Property
Type
Description

contactName

String

This is an optional field for storing the contact name of the recipient, if different from the name included in the address itself.

[Max Length: 100]

shippingInstructions

String

This free text field allows you to add shipping instructions such as "Bring to Loading Bay #7".

[Max Length: 1000]

useBillingAddressAsShippingAddress

Boolean

This determines if this resource will have both a shipping and billing address. If TRUE the shipping Address is hidden in the UI although it would still be returned in a call to Get CustomerAddressPreferences. If FALSE the shipping address is also displayed in the UI and, if the account level settings are set to show the shipping address, both addresses will appear on all invoices. Note that shipping instructions will appear in the notes section of all invoices.

billingAddress

Address Object

[see below forAddress object definition]

shippingAddress

Address Object

[see below forAddress object definition]

id

long

The Id uniquely identifies the customer.

The Id field is always included in any response from any applicable calls on a Customer. It is also often used as part a URL parameter on GET calls.

[Read Only]

uri

String

Full path to a particular customer address preference object.

[Read Only]

Suggest Edits

Read Address Preferences

This function allows you to retrieve customer address preferences by ID.

 
gethttps://stg-secure.fusebill.com/v1/customerAddressPreferences/customerId
 

Field
Data Type
Description

customerId

Integer

This is the Fusebill ID for the customer you want to retrieve address information for.

Examples
curl -X GET "https://stg-secure.fusebill.com/v1/customerAddressPreferences/{customerId}" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//path parameter, Fusebill Id which corresponds to the Id Field Returned by Create/Update customer
int pathParameter = {customerId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customerAddressPreferences/"+pathParameter);
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI, Payload and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/customerAddressPreferences/{id}', headers=headers)
print(r.content)
Response
{
	"contactName": "Frank",
	"shippingInstructions": null,
	"useBillingAddressAsShippingAddress": true,
	"billingAddress": null,
	"shippingAddress": null,
	"id": 84072,
	"uri": "https://stg-secure.fusebill.com/v1/customerAddressPreferences/84072"
}
Suggest Edits

Update Address Preferences

This function allows you to edit a customer address preferences resource. The id field in the body is the id of the customer you wish to update the preferences for.

 
puthttps://stg-secure.fusebill.com/v1/CustomerAddressPreferences
 

Customer Address Preferences Fields

Field
Data Type
Description

id

Integer

This is the Customer ID (Fusebill ID) of the custom to whom these preferences apply.

shippingInstructions

String, Max Length: 50 characters

This free field allows you to specify instructions for shipping.

useBillingAsShipping

Boolean

This determins if this resource will have both a shipping and billing address or if it will use the billing address for both.

contactName

String, Max Length: 50 characters

This field can be used to store the contact name of the recipient, if different from the name stored in the address.

Examples
curl -X PUT "https://stg-secure.fusebill.com/v1/CustomerAddressPreferences" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{customerId:{customerId},contactname:'John',shippingInstructions:'Signature required.',useBillingAddressAsShippingAddress:true,billingAddress:null,shippingAddres:null}"
//Json data, Fusebill Id which corresponds to the customerId Field
string jsonData = "{id:{customerId},contactname:'John',shippingInstructions:'Signature required.',useBillingAddressAsShippingAddress:true,billingAddress:null,shippingAddres:null}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/CustomerAddressPreferences");
//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 = {"contactName":"John 

Doe","shippingInstructions":None,"useBillingAddressAsShippingAddress":"true","billingAddress":None,"shippingAddress":None,"id":{id},"uri":"https://stg-

secure.fusebill.com/v1/CustomerAddressPreferences/{id}"}
#Pass in your URI, Payload and Headers
r = requests.put('https://stg-secure.fusebill.com/v1/customerAddressPreferences', data=json.dumps(payload), headers=headers)
print(r.content)
Response
{
	"contactName": "Frank",
	"shippingInstructions": "signature required",
	"useBillingAddressAsShippingAddress": true,
	"billingAddress": null,
	"shippingAddress": null,
	"id": 84072,
	"uri": "https://stg-secure.fusebill.com/v1/customerAddressPreferences/84072"
}
Suggest Edits

Shipping/Billing Address Object

In Fusebill, customers can have 2 distinct addresses, one for their billing details and optionally one for shipping. The billing address is where invoices would be sent when physically mailing invoices to customers while the shipping address would be used if physical goods were to be shipped to customers.

 
Suggest Edits

Create Ship/Bill Address

This function is used to create a new address resource. The address is linked to a specific customer when it is created.

When posting a new address, Fusebill accepts a variety of values for the Country ID and State ID key-value pairs. The Country ID and State ID fields allow you to use standard ISO 3166-1 Numeric and Subdivision ISO codes. ISO standards are defined and maintained by ISO 3166/MA. For your convenience, we have included downloads of these codes here:

Country Reference List

 
posthttps://stg-secure.fusebill.com/v1/Addresses
 

Shipping and Billing Address Fields

Field
Data Type
Description

customerAddressPreferenceId

Integer

This is the customer ID (Fusebill ID).

companyName

String, Max Length: 50 characters

This is the name of the customer's company.

line1

String, Max Length: 50 characters

The address line 1.

line2

String, Max Length: 50 characters

The address line 2.

countryID

String or Integer

The Country ID and State ID fields allow you to use either Country and State full name or standard ISO 3166-1 Alpha-3, Alpha-2, Numeric and Subdivision ISO codes.

stateID

String or Integer

The Country ID and State ID fields allow you to use either Country and State full name or standard ISO 3166-1 Alpha-3, Alpha-2, Numeric and Subdivision ISO codes.

state

String

The state or province of the customer.

city

String

The city of the Customer.

postalZip

String

The postal code of the customer.

addressType

String

This can be "billing" or "shipping".

id

Integer

This is Address ID you must use in the request URL. You can get this ID by doing a List Customer Addresses call.

Examples
curl -X POST "https://stg-secure.fusebill.com/v1/Addresses" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{customerAddressPreferenceId:{customerId},companyName:'Fusebill',line1:'232 Herzberg Road',line2:'Suite 203',countryId:124,country:'Canada',stateId:9,state:'Ontario',city:'Kanata',postalZip:'K2K 2A1',addressType:'Billing'}"
//Json data, Fusebill Id which corresponds to the customerId Field
string jsonData ="{customerAddressPreferenceId:{customerId},companyName:'Fusebill',line1:'232 Herzberg Road',line2:'Suite 203',countryId:124,country:'Canada',stateId:9,state:'Ontario',city:'Kanata',postalZip:'K2K 2A1',addressType:'Billing'}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/Addresses");
//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 = {"customerAddressPreferenceId":{id},"companyName":'Fusebill',"line1":'232 Herzberg Road',"line2":'Suite 
203',"countryId":124,"country":'Canada',"stateId":9,"state":'Ontario',"city":'Kanata',"postalZip":'K2K 2A1',"addressType":'Billing'}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/addresses', data=json.dumps(payload), headers=headers)
print(r.content)
Response
{
		"customerAddressPreferenceId": 84636,
		"companyName": "DarkSide",
		"line1": "117 Waba Road",
		"line2": null,
		"countryId": 124,
		"country": "Canada",
		"stateId": 9,
		"state": "Ontario",
		"city": "Pakenham",
		"postalZip": "K0A2X0",
		"addressType": "Billing",
		"id": 63406,
		"uri": "https://stg-secure.fusebill.com/v1/addresses/63406"
}
Suggest Edits

Read Ship/Bill Address

This function is used to retrieve an address. Addresses are retrieved by their unique ID.

Our shipping and billing address calls accept a variety of values for the Country ID and State ID key-value pairs. The Country ID and State ID fields allow you to use standard ISO 3166-1 Numeric and Subdivision ISO codes. ISO standards are defined and maintained by ISO 3166/MA. For your convenience, we have included downloads of these codes here:

Country Reference List

 
gethttps://stg-secure.fusebill.com/v1/Addresses/addressId
 

Shipping and Billing Address Fields

Field
Data Type
Description

customerAddressPreferenceId

Integer

This is the customer ID (Fusebill ID).

companyName

String, Max Length: 50 characters

This is the name of the customer's company.

line1

String, Max Length: 50 characters

The address line 1.

line2

String, Max Length: 50 characters

The address line 2.

countryID

String or Integer

The Country ID and State ID fields allow you to use either Country and State full name or standard ISO 3166-1 Alpha-3, Alpha-2, Numeric and Subdivision ISO codes.

stateID

String or Integer

The Country ID and State ID fields allow you to use either Country and State full name or standard ISO 3166-1 Alpha-3, Alpha-2, Numeric and Subdivision ISO codes.

state

String

The state or province of the customer.

city

String

The city of the Customer.

postalZip

String

The postal code of the customer.

addressType

String

This can be "billing" or "shipping".

id

Integer

This is Address ID you must use in the request URL. You can get this ID by doing a List Customer Addresses call.

Examples
curl -X GET "https://stg-secure.fusebill.com/v1/Addresses/{addressId}" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//path parameter
int pathParameter = {addressId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/Addresses/"+pathParameter);
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/addresses/{id}', headers=headers)
print(r.content)
Response
{
	"customerAddressPreferenceId": 84636,
	"companyName": "DarkSide",
	"line1": "117 Waba Road",
	"line2": null,
	"countryId": 124,
	"country": "Canada",
	"stateId": 9,
	"state": "Ontario",
	"city": "Pakenham",
	"postalZip": "K0A2X0",
	"addressType": "Billing",
	"id": 63406,
	"uri": "https://stg-secure.fusebill.com/v1/addresses/63406"
}
Suggest Edits

Update Ship/Bill Address

This function is used to update an address resource. The address is linked to a specific customer when it is created.

Our shipping and billing address calls accept a variety of values for the Country ID and State ID key-value pairs. The Country ID and State ID fields allow you to use standard ISO 3166-1 Numeric and Subdivision ISO codes. ISO standards are defined and maintained by ISO 3166/MA. For your convenience, we have included downloads of these codes here:

Country Reference List

 
puthttps://stg-secure.fusebill.com/v1/Addresses
 

Shipping and Billing Address Fields

Property
Type
Description

customerId

integer

This is the Id value which uniquely identifies a Customer record in the Fusebill system. This value is unique to each customer.

cancellationOption

String

This field defines if the Customer receives a refund when Subscriptions are cancelled. Valid string are "None", "Unearned", "Full". None indicates the Customer will not receive a refund. Unearned indicates the customer will receive the Unearned revenue, this is commonly called the Prorated Amount. Full indicates the customer will receive a full refund for the current billing period. String, Valid string are "None", "Unearned", "Full".

Examples
curl -X PUT "https://stg-secure.fusebill.com/v1/Addresses" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{customerAddressPreferenceId:{customerId},id:{addressId},companyName:'Fusebill',line1:'232 Herzberg Road',line2:'Suite 203',countryId:124,country:'Canada',stateId:9,state:'Ontario',city:'Kanata',postalZip:'K2K 2A1',addressType:'Billing'}"
//Json data, Fusebill Id which corresponds to the customerId Field
string jsonData ="{customerAddressPreferenceId:{customerId},id:{addressId},companyName:'Fusebill',line1:'232 Herzberg Road',line2:'Suite 203',countryId:124,country:'Canada',stateId:9,state:'Ontario',city:'Kanata',postalZip:'K2K 2A1',addressType:'Billing'}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/Addresses");
//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 ={"customerAddressPreferenceId":{id},"companyName":None,"line1":"","line2":None,"countryId":None,"country":None,"stateId":None,"state":None,"city":"","post
alZip":"","addressType":"Billing","id":{id},"uri":"https://stg-secure.fusebill.com/v1/addresses/{id}"}
#Pass in your URI, Payload and Headers
r = requests.put('https://stg-secure.fusebill.com/v1/customerAddressPreferences', data=json.dumps(payload), headers=headers)
print(r.content)
Response
{
	"customerAddressPreferenceId": 84421,
	"companyName": "DarkSide Inc.",
	"line1": "768 Farside",
	"line2": null,
	"countryId": "124",
	"country": "Canada",
	"stateId": 9,
	"state": "Ontario",
	"city": "Ottawa",
	"postalZip": "K3Y9Y7",
	"addressType": "Billing",
	"id": 63406
}
Suggest Edits

Read Country ID

 
gethttps://stg-secure.fusebill.com/v1/Countries
 

This returns a list of Country and State IDs

curl -X PUT "https://stg-secure.fusebill.com/v1/Countries" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//path parameter
int pathParameter = {addressId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/Countries/"+pathParameter);
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/Countries', headers=headers)
print(r.content)
Suggest Edits

Subscriptions Object

 

Subscription Object Overview

Many systems use Plan and Subscription as interchangeable terms when discussing recurring billing but in Fusebill a Plan and a Subscription are very different.

Plans should be thought of as templates for a service you want to sell to your customers. A Subscription is the actual implementation of a Plan when that Plan is attached to a Customer. Changes to a Plan do not change the Subscriptions created from that Plan and changes made to a Subscription have no effect on the Plan they were created from.

In addition, Plans can have multiple frequencies (monthly, yearly, etc). Subscriptions are instances of a particular frequency of a particular Plan so a Subscription has only one frequency regardless of how many frequencies were in the Plan from which the Subscription was created.

Subscriptions, like their Plan counterparts, are complex and have multiple components that make up the full description of the Subscription. The Subscription object has the following fields:

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", "Cancelled", "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

Number

This lists the default number of intervals that remain before expiry. This is a default set at the plan level.

remainingIntervalPushOut

Number

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

Discount

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)

setupFeeDiscount

Discount

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

Discount

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

Number, generated automatically by Fusebill, cannot be changed.

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

Number

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.

amount

Number

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.

Suggest Edits

List Subscriptions

This action will return an array that contains a list of Subscriptions applied against the specified Customer Id. This call will return all Subscriptions regardless of status and will return an empty array if the Customer specified has no Subscriptions. This call supports a type of search and filter behavior using the query parameter. You can enter any field in the Subscription record as the "field" value and the call will return only those Subscription where the "queryString" provided matches the value of the field in the Subscription record. Please note, this is an exact match query and partial matches are not supported. In addition, all Subscription records which match the query will be returned as a list so this may return multiple Subscription if the queryString is not unique across your Subscription.

A common query is: /v1/customers/{id}/Subscriptions/?query=status:Active

This query searches using the status field from the Fusebill admin interface. The Status field indicates if this Subscription is Active or in Draft or Cancelled. All Subscriptions which match this status (eg: all Active Subscriptions) would be returned. Some additional filtering and sorting features are available, see the paging article for those additional parameters.

 
gethttps://stg-secure.fusebill.com/v1/customers/customerId/subscriptions
 
Property
Type
Description

customerId

Decimal

This is the Id of the Customer to whom the Subscriptions have been applied.

Examples
curl -X GET "https://stg-secure.fusebill.com/v1/customers/{customerId}/subscriptions" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//path parameter, FusebillId
int pathParameter = {customerId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/customers/"+pathParameter+"/subscriptions");
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/customers/{id}/subscriptions', headers=headers)
print(r.content)
Response
[  
   {  
      "customerId":172677,
      "planFrequency":{  
         "planRevisionId":122453,
         "numberOfIntervals":1,
         "interval":"Monthly",
         "numberOfSubscriptions":1,
         "status":"Active",
         "setupFees":[  
            {  
               "amount":10.0,
               "currency":"USD",
               "id":0,
               "uri":null
            }
         ],
         "charges":[  
            {  
               "amount":2.0,
               "currency":"USD",
               "id":0,
               "uri":null
            }
         ],
         "isProrated":false,
         "prorationGranularity":null,
         "planFrequencyUniqueId":114,
         "remainingInterval":null,
         "id":114,
         "uri":null
      },
      "planCode":"BSC2",
      "planName":"Basic",
      "planDescription":"Basic Monthly Services for Kennedy Consulting",
      "planReference":null,
      "status":"Cancelled",
      "reference":null,
      "subscriptionOverride":null,
      "hasPostedInvoice":true,
      "createdTimestamp":"2017-01-11T18:35:37",
      "activatedTimestamp":null,
      "provisionedTimestamp":"2017-01-11T19:07:57",
      "nextPeriodStartDate":null,
      "scheduledActivationTimestamp":"2017-02-01T05:00:00",
      "subscriptionProducts":[  

      ],
      "remainingInterval":null,
      "remainingIntervalPushOut":null,
      "openSubscriptionPeriodEndDate":null,
      "chargeDiscount":null,
      "setupFeeDiscount":null,
      "chargeDiscounts":[  

      ],
      "setupFeeDiscounts":[  

      ],
      "customFields":null,
      "planAutoApplyChanges":false,
      "autoApplyCatalogChanges":false,
      "monthlyRecurringRevenue":0.0000,
      "netMonthlyRecurringRevenue":0.0000,
      "amount":12.0000,
      "contractStartTimestamp":null,
      "contractEndTimestamp":null,
      "expiredTimestamp":null,
      "coupons":[  

      ],
      "subscriptionHasRecurringEndOfPeriodCharge":false,
      "id":122453,
      "uri":"https://stg-secure.fusebill.com/v1/subscriptions/122453"
   }
]
Suggest Edits

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".

 
posthttps://stg-secure.fusebill.com/v1/subscriptions
 

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

Sample JSON Payloads

//Most basic payload to create subscription with all default values
{
  "CustomerID": '310045',
  "planFrequencyID": '19384'
}
//Request that includes two coupon codes to immediately apply to the subscription
{
  "CustomerID": '310045',
  "planFrequencyID": '19384',
  "couponCodes": ["%5Off", "NextMonthFree"]
}
/**This sample payload creates a subscription while also overriding the default name, description, and price from the catalog. The subscription is also scheduled to activate at a future date. 
**/

{
  "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",
}

Request Parameters

Property
Type
Description
Required

customerID

Decimal

This is the Fusebill ID of the customer.

Yes

planFreqencyID

Collection

See planFrequency Object Fields below

Yes

subscriptionOverride

Collection

See subscriptionOverride Object Fields below

Optional

Reference

String

This will appear as the 3rd line item in the main subscription header on an invoice

Optional

scheduledActivationTimestamp

DateTime

It 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

remainingInterval

Decimal

Number of billing intervals that can iterate before the subscription status is set to "Expired".

Optional

remainingIntervalPushOut

Decimal

Number 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-Portal

Optional

contractStartTimestamp

String

This is the string of the contract start date returned in subscription reports

Optional

contractEndTimestamp

String

This is the string of the contract end date returned in subscription reports

Optional

billingPeriodID

Decimal

The unique id of an existing billing period on the customer that the subscription should be assigned to

Optional

invoiceDay

Integer (1-28)

Tells the system to create a billing period that cycles on the specified day and assign this subscription to it

Optional

invoiceMonth

Integer (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

Optional

couponCodes

Collection

Can 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 subscription

Optional

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", "Cancelled", "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.

Subscription Override Fields

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 - Minimum Payload
curl -X POST "https://stg-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://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:'310045',planFrequencyID: '19384'}"
#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"
}
Suggest Edits

Read Subscription

This action will return This action will return a Subscription response for a given Subscription ID. Note, setting the "PriceUpliftsEnabled" key-value to "False" from a previous value of "True" will delete existing, future and historical price uplifts.

 
gethttps://stg-secure.fusebill.com/v1/subscriptions/subscriptionId
 
Examples
curl -X GET "https://stg-secure.fusebill.com/v1/subscriptions/{subscriptionId}" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//query parameter
int queryParameter = {subscriptionId};
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/subscriptions/"+queryParameter);
//Add Content type
request.ContentType = "application/json";
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/subscriptions/{id}', headers=headers)
print(r.content)
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,
                "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://stg-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://stg-secure.fusebill.com/v1/subscriptions/177229"
}
Suggest Edits

Activate Subscription

The Subscription Activation call does not require a content body.

This action will set the status of a Subscription to Active, which in most cases this will generate an invoice, and depending on the customer's billing options, apply a charge and a collection attempt against the Customer's payment method.

The Subscription will activate regardless of the collection attempt failing or succeeding so you should review the invoices to ensure payment was successful. This call will return the Subscription which you have activated so you can verify that the status field is set to Active. This action can only be performed against Subscriptions which have a status value of Draft or Provisioning.

In Fusebill, each Subscription is attached to a Billing Period which defines the start and end of the billing cycle and the duration (eg: one month, starting from the 1st of January or 1 Year starting on the 4th of May). Fusebill allows a Customer to have multiple Billing Periods which means different Subscriptions can have different start and end dates (eg: one Subscription starting on the 4th of the month, one on the 9th, etc). You can define the Billing Period that the Subscription should align to when you perform this call by passing in the appropriate fields in the call body.

 
posthttps://stg-secure.fusebill.com/v1/SubscriptionActivation/subscriptionId?preview=preview&showzerodollarcharges=showzerodollarcharges&temporarilyDisableAutoPost=temporarilyDisableAutoPost
 

Request Examples

POST https://stg-secure.fusebill.com/v1/subscriptionActivation/216252 

//this example will activate the subscription with the ID 216252. No body is required. 
POST https://stg-secure.fusebill.com/v1/subscriptionActivation/7680461?Preview=true&showzerodollarcharges=true

//This example will return a preview of the subscription activation. 
//The subscription will remain in draft state after this request has completed
POST https://stg-secure.fusebill.com/v1/subscriptionActivation/7680461?view=sideeffects

//This example will post the customer
//The resulting invoice created by the activation will be included in the response. 
POST https://stg-secure.fusebill.com/v1/subscriptionActivation

{
  "invoiceDay": 20,
}

//This example includes a payload with an invoice month. 
//This subscription will be activated, and billing will run on the 20th of the month. 

Request Parameters

Property
Type
Description
Required

invoiceMonth

Integer (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

Optional

invoiceDay

Integer (1-28)

Can 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 subscription

Optional

URL Parameters

Property
Type
Description
Required

subscriptionID

Decimal

ID of the Subscription to be activated

Yes

preview

Boolean

If the Preview url parameter is set to True the subscription is not activated, the call will simple simulate the activation and calculate the mock invoice

Optional

showzerodollarcharges

Boolean

If set to true, zero dollar charges will be included on invoices.

Optional

temporarilyDisableAutoPost

Boolean

This will specify whether or not the resulting invoice from this call will post the related invoice or not

Optional

Property
Type
Description

subscriptionId

Int

The id of the subscription to activate.

Examples
curl -X POST "https://stg-secure.fusebill.com/v1/SubscriptionActivation/{subscriptionId}?preview=true" \
	-H "Content-Type: application/json" \
	-H "Content-Length: 0" \
	-H "Authorization: Basic {APIKey}" \
//Json Payload
string jsonData = "{invoiceDay:20}";
//path parameter, subscriptionId
int pathParameter = {subscriptionId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/SubscriptionActivation/"+pathParameter);
//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 = {"invoiceDay":20}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/subscriptionActivation/{id}?preview=true', data=json.dumps(payload), headers=headers)
print(r.content)
Response
[  
   {  
      "customerId":172677,
      "planFrequency":{  
         "planRevisionId":122453,
         "numberOfIntervals":1,
         "interval":"Monthly",
         "numberOfSubscriptions":1,
         "status":"Active",
         "setupFees":[  
            {  
               "amount":10.0,
               "currency":"USD",
               "id":0,
               "uri":null
            }
         ],
         "charges":[  
            {  
               "amount":2.0,
               "currency":"USD",
               "id":0,
               "uri":null
            }
         ],
         "isProrated":false,
         "prorationGranularity":null,
         "planFrequencyUniqueId":114,
         "remainingInterval":null,
         "id":114,
         "uri":null
      },
      "planCode":"BSC2",
      "planName":"Basic",
      "planDescription":"Basic Monthly Services for Kennedy Consulting",
      "planReference":null,
      "status":"Cancelled",
      "reference":null,
      "subscriptionOverride":null,
      "hasPostedInvoice":true,
      "createdTimestamp":"2017-01-11T18:35:37",
      "activatedTimestamp":null,
      "provisionedTimestamp":"2017-01-11T19:07:57",
      "nextPeriodStartDate":null,
      "scheduledActivationTimestamp":"2017-02-01T05:00:00",
      "subscriptionProducts":[  

      ],
      "remainingInterval":null,
      "remainingIntervalPushOut":null,
      "openSubscriptionPeriodEndDate":null,
      "chargeDiscount":null,
      "setupFeeDiscount":null,
      "chargeDiscounts":[  

      ],
      "setupFeeDiscounts":[  

      ],
      "customFields":null,
      "planAutoApplyChanges":false,
      "autoApplyCatalogChanges":false,
      "monthlyRecurringRevenue":0.0000,
      "netMonthlyRecurringRevenue":0.0000,
      "amount":12.0000,
      "contractStartTimestamp":null,
      "contractEndTimestamp":null,
      "expiredTimestamp":null,
      "coupons":[  

      ],
      "subscriptionHasRecurringEndOfPeriodCharge":false,
      "id":122453,
      "uri":"https://stg-secure.fusebill.com/v1/subscriptions/122453"
   }
]
Suggest Edits

Provision Subscription

This action will set the status of a Subscription to Provisioning. This status is in between Draft and Active and is used to represent services that have been turned on for the Customer but billing has not started. Commonly this is used to facilitate a 'free trial' period. Products in the Subscription can be configured to Charge at Provisioning in which case there may be Invoice and payment activities as a result of this call.

This call will return the Subscription that you have provisioned so you can verify the status field is set to Provisioning.

This action can only be performed against Subscriptions in Draft status.

 
posthttps://stg-secure.fusebill.com/v1/SubscriptionProvision/subscriptionID
 
Property
Type
Description

subscriptionId

Int

This is the Subscription Id of the Subscription you want to provision.

Examples
curl -X POST "https://stg-secure.fusebill.com/v1/SubscriptionProvision/{subscriptionId}" \
	-H "Content-Type: application/json" \
	-H "Content-Length: 0" \
	-H "Authorization: Basic {APIKey}"
//path parameter
int pathParameter = {subscriptionId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/SubscriptionProvision/"+pathParameter);
//Set Content Length
request.ContentLength = 0;
//Add Content type
request.ContentType = "application/json";
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "POST";
//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":'plan-2',"name":"Plan-2"}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/subscriptionProvision/{id}', data=json.dumps(payload), headers=headers)
print(r.content)
Response
[ 
   { 
      "customerId":84636,
      "planFrequency":{ 
         "planRevisionId":75244,
         "numberOfIntervals":1,
         "interval":"Monthly",
         "numberOfSubscriptions":1,
         "status":"Active",
         "setupFees":[ 

         ],
         "charges":[ 

         ],
         "isProrated":false,
         "prorationGranularity":null,
         "planFrequencyUniqueId":4362,
         "remainingInterval":null,
         "id":4362,
         "uri":null
      },
      "planCode":"plan1",
      "planName":"Plan1",
      "planDescription":null,
      "planReference":null,
      "status":"Provisioning",
      "reference":null,
      "subscriptionOverride":null,
      "hasPostedInvoice":true,
      "createdTimestamp":"2016-05-23T13:27:26",
      "activatedTimestamp":null,
      "provisionedTimestamp":"2016-05-23T17:53:48.0004354Z",
      "nextPeriodStartDate":null,
      "scheduledActivationTimestamp":"2016-05-25T04:00:00",
      "subscriptionProducts":[ 
         { 
            "subscriptionId":75244,
            "planProduct":{ 
               "status":"Active",
               "productId":15862,
               
            },
            { 
               "subscriptionId":75244,
               "planProduct":{ 
                  "status":"Active",
                  "productId":15864,
                  
               }
            ],
            "remainingInterval":null,
            "remainingIntervalPushOut":null,
            "openSubscriptionPeriodEndDate":null,
            "chargeDiscount":null,
            "setupFeeDiscount":null,
            "chargeDiscounts":null,
            "setupFeeDiscounts":null,
            "customFields":null,
            "planAutoApplyChanges":false,
            "autoApplyCatalogChanges":false,
            "monthlyRecurringRevenue":0,
            "netMonthlyRecurringRevenue":0,
            "amount":500,
            "contractStartTimestamp":null,
            "contractEndTimestamp":null,
            "expiredTimestamp":null,
            "coupons":[ 

            ],
            "subscriptionHasRecurringEndOfPeriodCharge":false,
            "id":75244,
            "uri":"Subscriptions/75244"
         }
      ]
Suggest Edits

Update Subscription

This action allows you to edit a Subscription. Editing a Subscription will return the updated Subscription object so you can verify your changes.

 
puthttps://stg-secure.fusebill.com/v1/subscriptions/subscriptionId
 

Special Considerations

Request considerations: Due to the complex nature of the subscription DTO we recommend using a get/put methodology when modifying a subscription.

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

Example

stg-secure.fusebill.com/v1/subscriptions/{subscription_id}?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.

Property
Type
Description

subscriptionId

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", "Cancelled", "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. "Migrated" if the Subscription was migrated to another.

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

Number

This lists the default number of intervals that remain before expiry. This is a default set at the plan level.

remainingIntervalPushOut

Number

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

Discount

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)

setupFeeDiscount

Discount

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

Discount

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

Number, generated automatically by Fusebill, cannot be changed.

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

Number

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.

Plan Frequency 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.

Plan Products 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.

amount

Decimal

This is the dollar amount to apply against the above invoice.

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".

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.

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 PUT "https://stg-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://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 = "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://stg-secure.fusebill.com/v1/subscriptions', data=json.dumps(payload), headers=headers)
print(r.content)
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,
                "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",
            "id": 970993,
            "uri": "https://stg-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://stg-secure.fusebill.com/v1/subscriptions/177229"
}
Suggest Edits

Delete Subscription

This action deletes a Subscription. You can only delete a Subscription that has a status value of Draft. Deleted Subscriptions are unrecoverable and no longer appear in the Customer's Subscriptions following the delete action.

 
deletehttps://stg-secure.fusebill.com/v1/subscriptions/Delete/subscriptionId
 
Property
Type
Description

subscriptionId

Int

This is the Subscription Id of the Subscription you want to Delete. Passing an incorrect Id may delete another Subscription.

Examples
curl -X DELETE "https://stg-secure.fusebill.com/v1/subscriptions/Delete/{subscriptionId}" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//Subscription id
int pathParameter = {subscriptionId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/Subscriptions/Delete/"+pathParameter);
//Add Content type
request.ContentLength = 0;
request.ContentType = "application/json";
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "DELETE";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI and Headers
r = requests.delete('https://stg-secure.fusebill.com/v1/subscriptions/Delete/{id}', headers=headers)
print(r.content)
Response
Returns a 204 No Content Response
Suggest Edits

Cancel Subscription

This action cancels an active Subscription, (only Subscriptions in Active status can be cancelled.) This call returns the cancelled Subscription so you can inspect the status field to ensure it was cancelled as expected.

 
posthttps://stg-secure.fusebill.com/v1/subscriptionCancellation
 
Property
Type
Description

subscriptionId

Int

This is the Subscription Id for the Subscription you want to cancel. Passing the incorrect Id can potentially cancel a different Subscription.

cancellationOption

String

This field defines if the Customer receives a refund when the Subscription is cancelled. Valid string are "None", "Unearned", "Full". None indicates the Customer will not receive a refund. Unearned indicates the customer will receive the Unearned revenue or Prorated Amount. Full indicates the customer will receive a full refund for the current billing period

Examples
curl -X POST "https://stg-secure.fusebill.com/v1/subscriptionCancellation" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{subscriptionId:{subscriptionId},cancellationOption:'None'}"
//Json Payload
string jsonData = "{subscriptionId:{subscriptionId},cancellationOption:'None'}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/subscriptionCancellation/");
//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 = {'subscriptionId':{id},'cancellationOption':'None'}
#Pass in your URI, Payload and Headers
r = requests.post('https://stg-secure.fusebill.com/v1/subscriptionCancellation/{id}', data=json.dumps(payload), headers=headers)
print(r.content)
Response
[  
   {  
      "customerId":172677,
      "planFrequency":{  
         "planRevisionId":122453,
         "numberOfIntervals":1,
         "interval":"Monthly",
         "numberOfSubscriptions":1,
         "status":"Active",
         "setupFees":[  
            {  
               "amount":10.0,
               "currency":"USD",
               "id":0,
               "uri":null
            }
         ],
         "charges":[  
            {  
               "amount":2.0,
               "currency":"USD",
               "id":0,
               "uri":null
            }a
         ],
         "isProrated":false,
         "prorationGranularity":null,
         "planFrequencyUniqueId":114,
         "remainingInterval":null,
         "id":114,
         "uri":null
      },
      "planCode":"BSC2",
      "planName":"Basic",
      "planDescription":"Basic Monthly Services for Kennedy Consulting",
      "planReference":null,
      "status":"Cancelled",
      "reference":null,
      "subscriptionOverride":null,
      "hasPostedInvoice":true,
      "createdTimestamp":"2017-01-11T18:35:37",
      "activatedTimestamp":null,
      "provisionedTimestamp":"2017-01-11T19:07:57",
      "nextPeriodStartDate":null,
      "scheduledActivationTimestamp":"2017-02-01T05:00:00",
      "subscriptionProducts":[  

      ],
      "remainingInterval":null,
      "remainingIntervalPushOut":null,
      "openSubscriptionPeriodEndDate":null,
      "chargeDiscount":null,
      "setupFeeDiscount":null,
      "chargeDiscounts":[  

      ],
      "setupFeeDiscounts":[  

      ],
      "customFields":null,
      "planAutoApplyChanges":false,
      "autoApplyCatalogChanges":false,
      "monthlyRecurringRevenue":0.0000,
      "netMonthlyRecurringRevenue":0.0000,
      "amount":12.0000,
      "contractStartTimestamp":null,
      "contractEndTimestamp":null,
      "expiredTimestamp":null,
      "coupons":[  

      ],
      "subscriptionHasRecurringEndOfPeriodCharge":false,
      "id":122453,
      "uri":"https://stg-secure.fusebill.com/v1/subscriptions/122453"
   }
]
Suggest Edits

List Subscription Summary

This action will retrieve a list of subscriptions which match a specified set of simple to advanced search parameters. The subscriptions returned will be on the account level opposed to the customer level. For example, a call can be made to retrieve a list of all active subscriptions for all customers on a given Fusebill account.

 
gethttps://stg-secure.fusebill.com/v1/subscriptionSummary
 

You can combine multiple query parameters via the following example:

Example

stg-secure.fusebill.com/v1/subscriptionsummary?pageNumber=0&pageSize=100&query=reference:{123*};subscriptionStatus:Active

Supported Filters

The following supported filters can also be appended to your URI allowing you to refine your search query. Please refer to the above example of appending multiple query parameters to your URI for reference.

Filter Type
Query
Notes

Reference

?query=reference:{123qwe}

Filters will only return Subscriptions that have a Reference matching the submitted value

Can use a * symbol to filter for a partial string search

subscriptionStatus

?query=subscriptionStatus:Draft

Filter will only return subscriptions in the Status(es) specified

Valid strings are “Draft”,”Active”,”Suspended”,”Provisioning”, and ”Cancelled”

Can submit multiple strings using syntax subscriptionStatus:{Active,Draft}

planCode

?query=planCode:Basic Plan 001

Filter to only return subscriptions to a Plan with the specified Plan Code

Can use a * symbol to filter for partial string search

Name

?query=name:Enterprise Service Plan

Filter to only return subscriptions with specified name

Can use a * symbol to filter for partial string search

Description

?query=Description:*License#455956890

Filter to only return subscriptions with specified description

Can use a * symbol to filter for partial string search

numberOfInterval

?query= numberOfInterval:3

Filter to only return subscriptions with specified number of interval

Interval

?query=interval:Yearly

Filter to only return subscriptions in the Interval(s) specified

Valid strings are “Monthly”,”Yearly”

Can submit multiple strings using syntax interval:{Monthly,Yearly}

Supported timestamp filters

Need to revise your search to a specific time interval? The following timestamp filters can be appended to your URI to search within a specific time window. An example of how you might use these filters is provided below.

Example

stg-secure.fusebill.com/v1/subscriptionsummary/Search?CreatedDateRangeStartDate=2017-06-08&CreatedDateRangeEndDate=2017-09-10

Timestamp Type
"From" Query Parameter
"To" Query Parameter

createdTimestamp

CreatedDateRangeStartDate

CreatedDateRangeEndDate

activatedTimestamp

ActivatedDateRangeStartDate

ActivatedDateRangeEndDate

provisionedTimestamp

ProvisionedDateRangeStartDate

ProvisionedDateRangeEndDate

nextPeriodStartDate

NextPeriodStartDateRangeStartDate

NextPeriodStartDateRangeEndDate

scheduledActivationTimestamp

ScheduledActivationDateRangeStartDate

ScheduledActivationDateRangeEndDate

expiryDate

ExpiryDateRangeStartDate

ExpiryDateRangeEndDate

contractStartTimestamp

ContractStartDateRangeStartDate

ContractStartDateRangeEndDate

contractEndTimestamp

ContractEndDateRangeStartDate

ContractEndDateRangeEndDate

lastBillingDate

LastBillingDateRangeStartDate

LastBillingDateRangeEndDate

nextBillingDate

NextBillingDateRangeStartDate

NextBillingDateRangeEndDate

cancellationtimestamp

CancellationDateRangeStartDate

CancellationDateRangeEndDate

suspendedTimestamp

SuspendedDateRangeStartDate

SuspendedDateRangeEndDate

Examples
curl -X GET "https://stg-secure.fusebill.com/v1/subscriptionSummary" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
 //Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/subscriptionSummary");
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/subscriptionSummary', headers=headers)
print(r.content)
Response
[ 
   { 
      "customerId":129076,
      "planCode":"onlineaccessplan",
      "name":"Online Access Plan",
      "description":null,
      "reference":"1236",
      "interval":"Monthly",
      "numberOfInterval":1,
      "subscriptionStatus":"Active",
      "monthlyRecurringRevenue":0,
      "netMonthlyRecurringRevenue":0,
      "lastBillingDate":"2016-07-09T17:00:24",
      "nextBillingDate":"2016-08-09T04:00:00",
      "expiryDate":null,
      "scheduledActivationTimestamp":null,
      "cancellationTimestamp":null,
      "suspendedTimestamp":null,
      "createdTimestamp":"2016-07-09T17:00:11",
      "activatedTimestamp":"2016-07-09T17:00:24",
      "provisionedTimestamp":null,
      "nextPeriodStartDate":"2016-08-09T04:00:00",
      "contractStartTimestamp":null,
      "contractEndTimestamp":null,
      "remainingInterval":null,
      "id":83907,
      "uri":"https://stg-secure.fusebill.com/v1/subscriptionsummary/83907/"
   }
]
Suggest Edits

Subscription Products Object

 

The products available in a subscription are referred to as the subscription products. These products can be mandatory, included by default or optional. Subscription products make up the billable entities of a subscription and together the sum of the charges for each included subscription product makes up the total amount charged for the subscription.

At the subscription product level you can make many changes applicable only to the customer who owns the subscription. For example, subscription product pricing can be overridden, names and descriptions can be added/overridden, quantities can be added/removed, subscription products can be included and un-included, subscription products can be scheduled for activation and can be expired.

Suggest Edits

Read Subscription Product

This action will return a Subscription Product by ID.

Note, setting the "PriceUpliftsEnabled" key-value to "False" from a previous value of "True" will delete existing, future and historical price uplifts.

 
gethttps://stg-secure.fusebill.com/v1/SubscriptionProducts/subscriptionProductId
 
Examples
curl -X GET "https://stg-secure.fusebill.com/v1/subscriptionproducts/{subscriptionProductId}" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}"
//path parameter
int pathParameter = {subscriptionProductId}; 
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/subscriptionproducts/"+pathParameter);
//Add Content type
request.ContentType = "application/json";
request.ContentLength = 0;
//Add Api key authorization
request.Headers.Add(HttpRequestHeader.Authorization, "Basic "+apiKey);
//Set request method
request.Method = "GET";
//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 Requests
import requests
#Pass in a dictionary to the Headers parameter
headers = {'Authorization' : 'Basic {APIKey}', 'Content-Type' : 'application/json'}
#Pass in your URI and Headers
r = requests.get('https://stg-secure.fusebill.com/v1/subscriptionProducts/{id}', headers=headers)
print(r.content)
Response
{  
   "subscriptionId":123061,
   "planProduct":{  
      "status":"Active",
      "productId":14934,
      "planId":3273,
      "productCode":"monthlycharge",
      "productName":"Monthly Charge",
      "productStatus":"Active",
      "productDescription":null,
      "productType":"RecurringService",
      "productGLCode":"",
      "quantity":1.0,
      "maxQuantity":null,
      "isRecurring":true,
      "isFixed":false,
      "isOptional":false,
      "isIncludedByDefault":true,
      "isTrackingItems":true,
      "chargeAtSubscriptionActivation":true,
      "orderToCashCycles":[  
         {  
            "planFrequencyId":5500,
            "planProductId":22140,
            "numberOfIntervals":1,
            "interval":"Monthly",
            "chargeModels":[  
               {  
                  "chargeModelType":"Signup",
                  "chargeTimingType":"StartOfPeriod",
                  "prorationGranularity":"Daily",
                  "prorateOnPositiveQuantity":false,
                  "prorateOnNegativeQuantity":false,
                  "reverseChargeOnNegativeQuantity":false,
                  "id":653431,
                  "uri":null
               },
               {  
                  "chargeModelType":"Lifetime",
                  "chargeTimingType":"Immediate",
                  "prorationGranularity":"Daily",
                  "prorateOnPositiveQuantity":false,
                  "prorateOnNegativeQuantity":false,
                  "reverseChargeOnNegativeQuantity":false,
                  "id":653431,
                  "uri":null
               }
            ],
            "remainingInterval":null,
            "groupQuantityChangeCharges":false,
            "planProductPriceUplifts":null,
            "earningInterval":"Monthly",
            "earningNumberOfIntervals":1,
            "earningTimingInterval":"Daily",
            "earningTimingType":"StartOfInterval",
            "pricingModel":{  
               "pricingModelType":"Standard",
               "quantityRanges":[  
                  {  
                     "min":0.0,
                     "max":null,
                     "prices":[  
                        {  
                           "amount":15.99,
                           "currency":"USD",
                           "id":653431,
                           "uri":null
                        }
                     ],
                     "id":0,
                     "uri":null
                  }
               ],
               "id":653431,
               "uri":null
            },
            "id":653431,
            "uri":null
         }
      ],
      "resetType":"Never",
      "planProductUniqueId":21874,
      "id":22140,
      "uri":""
   },
   "quantity":1.0,
   "isIncluded":true,
   "startDate":null,
   "subscriptionProductOverride":null,
   "subscriptionProductPriceOverride":null,
   "chargeAtSubscriptionActivation":true,
   "isCharged":true,
   "subscriptionProductDiscount":null,
   "subscriptionProductDiscounts":[  

   ],
   "customFields":null,
   "monthlyRecurringRevenue":0.0,
   "netMonthlyRecurringRevenue":0.0,
   "amount":15.99,
   "status":"Active",
   "lastPurchaseDate":"2017-01-13T22:00:06",
   "earningSettings":{  
      "earningTimingInterval":"Daily",
      "earningTimingType":"StartOfInterval"
   },
   "remainingInterval":null,
   "groupQuantityChangeCharges":false,
   "priceUpliftsEnabled":false,
   "priceUplifts":[  

   ],
   "historicalPriceUplifts":[  

   ],
   "id":653431,
   "uri":"https://stg-secure.fusebill.com/v1/subscriptionproducts/653431"
}
Suggest Edits

Update Subscription Product

This function will allow you to edit a Subscription Product Item in a specific Subscription Product in a specific Subscription for a Customer.

 
puthttps://stg-secure.fusebill.com/v1/SubscriptionProducts/subscriptionProductId
 
Property
Type
Description

subscriptionId

Integer

This is the Id of the Subscription.

status

String

This is the status of the subscription.

productId

Integer

This is the unique ID of the product.

planId

Integer

This is the unique ID of the plan.

productCode

String

This is the product code assigned to the subscription product.

productName

String

This is the name assigned to the product on product creation.

productStatus

String

This is the status of the product.

productDescription

String

This is the assigned description for the given product.

productType

String

This can be "RecurringService", "OneTimeCharge", or "PhysicalGood".

productGLCode

String

This indicates the assigned GL code for this given product, if one was created.

quantity

Integer

This indicated the set unit quantity, this subscriber has purchased.

maxQuantity

Integer

This is a celing value that can be set to limit product quantity for a given subscription.

isRecurring

Boolean

This is a flag, which specifies the type of product (i.e. "RecurringService", "OneTimeCharge", or "PhysicalGood")

isFixed

Boolean

Setting a product quantity to "Fixed" says that quantity cannot be changed after the subscription has been activated.

isOptional

Boolean

Setting this product to "Optional" means that the product can be added or removed from the customer subscription at any time after subscription activation.

isIncludedByDefault

Boolean

Setting this value to "Is Included by Default" mean the product is included by default, but still optional.

chargeAtSubscriptionActivation

Boolean

With this setting set to true, the Fusebill system will attempt to charge the customer when the subscription is activated, unless billing settings state otherwise.

id

Decimal

This is the Subscription Id which uniquely identifies this individual Subscription. This Id is used to refer to this Subscription specifically.

Examples
curl -X PUT "https://stg-secure.fusebill.com/v1/SubscriptionProducts?preview=true" \
	-H "Content-Type: application/json" \
	-H "Authorization: Basic {APIKey}" \
	-d "{subscriptionId:{subscriptionId},planProduct:{status:'Active',productId:14934,planId:3273,productCode:'monthlycharge',productName:'Monthly Charge',productStatus:'Active',productDescription:null,productType:'RecurringService',productGLCode:'',quantity:1.0,maxQuantity:null,isRecurring:true,isFixed:false,isOptional:false,isIncludedByDefault:true,isTrackingItems:true,chargeAtSubscriptionActivation:true,orderToCashCycles:[{planFrequencyId:5500,planProductId:22140,numberOfIntervals:1,interval:'Monthly',chargeModels:[{chargeModelType:'Signup',chargeTimingType:'StartOfPeriod',prorationGranularity:'Daily',prorateOnPositiveQuantity:false,prorateOnNegativeQuantity:false,reverseChargeOnNegativeQuantity:false,id:653431,uri:null},{chargeModelType:'Lifetime',chargeTimingType:'Immediate',prorationGranularity:'Daily',prorateOnPositiveQuantity:false,prorateOnNegativeQuantity:false,reverseChargeOnNegativeQuantity:false,id:653431,uri:null}],remainingInterval:null,groupQuantityChangeCharges:false,planProductPriceUplifts:null,earningInterval:'Monthly',earningNumberOfIntervals:1,earningTimingInterval:'Daily',earningTimingType:'StartOfInterval',pricingModel:{pricingModelType:'Standard',quantityRanges:[{min:0.0,max:null,prices:[{amount:15.99,currency:'USD',id:653431,uri:null}],id:0,uri:null}],id:653431,uri:null},id:653431,uri:null}],resetType:'Never',planProductUniqueId:21874,id:22140,uri:''},quantity:1.0,isIncluded:true,startDate:null,subscriptionProductOverride:null,subscriptionProductPriceOverride:null,chargeAtSubscriptionActivation:true,isCharged:true,subscriptionProductDiscount:null,subscriptionProductDiscounts:[],customFields:null,monthlyRecurringRevenue:15.99,netMonthlyRecurringRevenue:15.99,amount:15.99,status:'Active',lastPurchaseDate:'2017-01-24T20:06:48',earningSettings:{earningTimingInterval:'Daily',earningTimingType:'StartOfInterval'},remainingInterval:null,groupQuantityChangeCharges:false,priceUpliftsEnabled:false,priceUplifts:[],historicalPriceUplifts:[],id:653431}"
//True to see a preview of your changes, false to apply the changes
bool preview = false;
//Json Payload
//This Json payload should be retrieved by using the Read Subscription Product endpoint
string jsonData ="{'subscriptionId':{subscriptionProduct},'planProduct':{'status':'Active','productId':16730,'planId':2788,'productCode':'netflix','productName':'Netflix','productStatus':'Active','productDescription':'tv package updated','productType':'RecurringService','productGLCode':'recurring1','quantity':1.0,'maxQuantity':null,'isRecurring':true,'isFixed':false,'isOptional':true,'isIncludedByDefault':false,'isTrackingItems':false,'chargeAtSubscriptionActivation':true,'orderToCashCycles':[{'planFrequencyId':4766,'planProductId':18336,'numberOfIntervals':1,'interval':'Monthly','chargeModels':[{'chargeModelType':'Signup','chargeTimingType':'StartOfPeriod','prorationGranularity':'Daily','prorateOnPositiveQuantity':false,'prorateOnNegativeQuantity':false,'reverseChargeOnNegativeQuantity':false,'id':654096,'uri':null},{'chargeModelType':'Lifetime','chargeTimingType':'Immediate','prorationGranularity':'Daily','prorateOnPositiveQuantity':false,'prorateOnNegativeQuantity':false,'reverseChargeOnNegativeQuantity':false,'id':654096,'uri':null}],'remainingInterval':null,'groupQuantityChangeCharges':false,'planProductPriceUplifts':null,'earningInterval':'Monthly','earningNumberOfIntervals':1,'earningTimingInterval':'Monthly','earningTimingType':'StartOfInterval','pricingModel':{'pricingModelType':'Standard','quantityRanges':[{'min':0.0,'max':null,'prices':[{'amount':10.0,'currency':'USD','id':654096,'uri':null}],'id':0,'uri':null}],'id':654096,'uri':null},'id':654096,'uri':null}],'resetType':'Never','planProductUniqueId':18070,'id':18336,'uri':''},'quantity':1.0,'isIncluded':false,'startDate':null,'subscriptionProductOverride':null,'subscriptionProductPriceOverride':null,'chargeAtSubscriptionActivation':true,'isCharged':false,'subscriptionProductDiscount':null,'subscriptionProductDiscounts':[],'customFields':null,'monthlyRecurringRevenue':0.0,'netMonthlyRecurringRevenue':0.0,'amount':0.0,'status':'Active','lastPurchaseDate':null,'earningSettings':{'earningTimingInterval':'Monthly','earningTimingType':'StartOfInterval'},'remainingInterval':null,'groupQuantityChangeCharges':false,'priceUpliftsEnabled':false,'priceUplifts':[],'historicalPriceUplifts':[],'id':654096,'uri':'https://stg-secure.fusebill.com/v1/subscriptionproducts/654096'}";
//Setup API key
string apiKey = "{APIKey}";
//Configure URI
WebRequest request = WebRequest.Create("HTTPS://stg-secure.fusebill.com/v1/SubscriptionProducts?preview="+preview);
//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 = {"subscriptionId":{id},"planProduct":

{"status":"Active","productId":{id},"planId":{id},"productCode":"subscriptionproduct","productName":"subscriptionProduct","productStatus":"Active","product
Description":None,"productType":"RecurringService","productGLCode":"","quantity":0.0,"maxQuantity":None,"isRecurring":"true","isFixed":"false","isOptional":
"true","isIncludedByDefault":"false","isTrackingItems":"true","chargeAtSubscriptionActivation":"true","orderToCashCycles":
[{"planFrequencyId":{id},"planProductId":{id},"numberOfIntervals":1,"interval":"Monthly","chargeModels":
[{"chargeModelType":"Signup","chargeTimingType":"StartOfPeriod","prorationGranularity":"Daily","prorate