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 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, companyName, and primaryEmail as a bare minimum.

🚧

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://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": "[email protected]"
}
POST https://secure.fusebill.com/v1/customers
// This example will post a customer, and override some accounts level billing settings

{
  "firstName": "Bob",
  "companyName": "Fusebill",
  "billingSetting": [
    {
      "term": "Net30",
      "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://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":"[email protected]",
   "primaryPhone":"123-456-7890",
   "secondaryEmail":"[email protected]",
   "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://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":"[email protected]",
   "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"
   }
}

Request Parameters

PropertyTypeDescriptionRequired
usernameStringThe username of the customer if they have login credentials [Read Only After Set; Max Length: 50 characters]Optional
firstNameStringThe first name of the customer.

[Max Length: 50 characters]
Optional
middleNameStringThe middle name of the customer.

[Max Length: 50 characters]
Optional
lastNameStringThe last name of the customer.

[Max Length: 50 characters]
Optional
companyNameStringThe company name associated with this customer.

[Max Length: 50 characters]
Optional
suffixStringThe name suffix of the customer, for example Jr. or Sr.

[Max Length: 50 characters]
Optional
primaryEmailStringThe primary contact email for the customer. Allows multiple entries in the format "[email protected]; [email protected]; [email protected]". Invoices and other email communications will be sent to this address(s).

[Max Length: 255 characters]
Optional
primaryPhoneStringThe primary contact number for the Customer.

[Max Length: 50 characters]
Optional
secondaryEmailStringThe secondary contact email for the customer. Allows multiple entries in the format "[email protected]; [email protected]; [email protected]". No communications are sent to this address

[Max Length: 255 characters]
Optional
secondaryPhoneStringThe secondary contact number for the customer.

[Max Length: 50 characters]
Optional
titleEnum:{Mr, Mrs, Ms, Miss, Dr}The prefix-title of the customer.Optional
referenceStringThis 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]
Optional
currency3 Character ISO Currency codeThe Currency configured for this Customer. If nothing is specified the account default is usedOptional
customerReferenceObject (defined below)This is a collection of key-value pairs. Each can be used to store additional data related to this Customer including sales tracking codes.Optional
customerAcquisitionObject (defined below)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.Optional
billingSettingObject (defined below)Customer billing settings.Optional
shippingObject (defined below)Customer shipping address.Optional
billingObject (defined below)Customer billing address.Optional
addressPreferenceObject (defined below)Set address preferencesOptional
monthlyBillingPeriodConfigurationObject (defined below)Monthly billing period definition for the customer.Optional
yearlyBillingPeriodConfigurationObject (defined below)Annual billing period definition for the customer.Optional
salesforceIdStringThe Salesforce Account Id associated with this Customer.Optional
salesforceAccountTypeEnum:{Company, Person}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 (Fusebill) account level default will be used
Optional
salesforceSynchStatusEnum: {Enabled, Disabled}This setting controls if the account will synchronize the Fusebill customer with Salesforce.Optional
netsuiteIdStringIf you are using a Netsuite integration this is the number which uniquely identifies the customer in Netsuite.Optional
netsuiteSynchStatusEnum:{Enabled, Disabled}This setting controls if the account will synchronize the Fusebill customer with NetSuite.Optional
parentIdIntegerThe Parent ID relates to the Fusebill hierarchy feature. If hierarchy is enabled, this is the id of the parent customer.​Optional
quickBooksIdIntegerThe name ID of this customer in QuickBooks Online. For the QuickBooks Online plugin.Optional
quickBooksLatchTypeEnum:{CreateNew, LatchExisting, DoNothing}Indicates how Fusebill is handling latching for this customer object and the possible corresponding customer in QuickBooks Online. This is for the QuickBooks Online plugin.Optional
hubSpotIdIntegerThe ID of this customer in HubSpotOptional
hubSpotCompanyIdIntegerThe ID of this customer in HubSpot if it represents a companyOptional
geotabIdStringThe Geotab Reseller Customer ID to be associated with this Fusebill customer entity

[Max Length: 255 characters]
Optional
lifetimeValueDecimalThe lifetime value of the customer. Typically set to a negative number representing the on-boarding cost of the customer. As the customer pays charges over time, this will increase and thus show how much the customer has contributed to revenue.Optional

Customer Billing/Shipping Address

PropertyTypeDescription
companyNameStringThe company name if applicable.
[Max Length: 255 characters]
line1Stringstandard line 1 of an address.
[Max Length: 60 characters]
line2Stringstandard line 2 of an address.
[Max Length: 60 characters]
cityStringThe city name.
[Max Length: 50]
postalZipStringThe postal code or zip code.
[Max Length: 10]
countryStringCountry using 2-character ISO code
stateStringState using 2-character ISO code

Customer Reference Fields

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

[Max Length: 255 characters]
reference2StringAn optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]
reference3StringAn optional open field to hold any alpha-numeric value on the customer.

[Max Length: 255 characters]
salesTrackingCodesObject (defined below)A collection of up to 5 SalesTrackingCode objects

SalesTracking Code Fields

PropertyTypeDescription
typeStringThe category name this code falls under. Fusebill supports 5 distinct categories. By default the names are "Sales Tracking Code 1", "Sales Tracking Code 2",..."Sales Tracking Code 5" but they can be customized.

If you rename your Sales Tracking code, those names or the default names can be used.
codeStringThe specific sales tracking code value. The code must exist under the appropriate sales tracking code type being referenced

Customer Acquisition Fields

PropertyTypeDescription
adContentStringTypically 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]
campaignStringThis 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]
keywordStringThese 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]
landingPageStringThe first page a visitor views during a session; also known as the entrance page.

[Max Length: 255 characters]
mediumStringTypically 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]
sourceStringThe 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

PropertyTypeDescription
termEnum:{Net0, Net5, Net7, Net10, Net15, Net21, Net30, Net45, Net60, Net75, Net90, MFI1, DayOfMonth1, DayOfMonth2, DayOfMonth3, ... DayOfMonth29, DayOfMonth30, DayOfMonth31}This defines the Payment Terms for this Customer.
autocollectBooleanThis defines whether the billing system will attempt to collect from the customer's payment method on file.

The global auto collect 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 default 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 auto collect setting.
dunningExemptBooleanControls whether this customer is exempt from your account's Dunning management settings. Dunning management settings control how and when Fusebill will automatically try to collect the outstanding balance of customers in poor standing. Relevant only for customers subject to auto collect.
rechargeTypeStringThis value should be set to "BringBalanceBackTo" in any case where you want to use the threshold billing feature.
rechargeThresholdAmountDecimalThis 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.
rechargeTargetAmountDecimalThis 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.
statusOnThresholdBooleanThis 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.
autoPostDraftInvoiceBooleanControls whether ready draft invoices should be posted automatically or remain in draft to be posted manually. Null means to follow account defaults
customerGracePeriodIntegerThe number of days a customer can be in poor standing before suspension occurs.
gracePeriodExtensionIntegerThe default number of days a grace period can be manually extended
standingPoNumberStringThis is the PO number which will be added to this customer's invoices. [Max Length: 255 characters]
acquisitionCostIntegerThis is the cost in dollars spent to acquire this customer. This factors into the customer profitability metric.
showZeroDollarChargesBooleanThis 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.
taxExemptBooleanThis defines if this customer should be charged taxes.
taxExemptCodeStringThis is the tax exemption code for this customer. If taxExempt is set to True this field must be populated. [Max Length: 255 characters]
useCustomerBillingAddressBooleanIf true, billing address is used as shipping address.
avalaraUsageTypeStringThis is a string sent to Alavara for determining the application of various sales taxes. [Max Length: 4 characters]
vatIdentificationNumberIntegerThe number associated with the client's EU Vat ID.
customerServiceStartOptionEnum: { ChargeForAllMissedPeriods, ChargeForLastMIssedPeriods, NoChargesForMissedPeriods, ChargeForCurrentFullPeriod}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. Null means to follow the account defaults.
rollUpTaxesBooleanThis 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).
rollUpDiscountsBooleanIf true, all of the discounts for all products and plans on the invoices for this customer will be rolled up into a single line item at the bottom of the invoice. Null follows the default of the Fusebill account.
trackedItemDisplayObject (defined below)Controls the appearance of tracked items on invoices for the customer.
customerAutoCancelIntegerThe number of days after suspension before the customer is cancelled by the system.
DefaultCancelOptionEnum:{Full, None, Unearned}Controls revenue recognition in the event of customer automatic cancellation. "Full" means to reverse all charges fully. "None" means earn all charges. "Unearned" means to reverse unearned amounts for all charges. Null means to follow the default of the Fusebill account.
postReadyChargesOnRenewBooleanControls whether draft ready charges are posted on renewal. This includes new ready draft charges from renewals and any existing ready draft charges from subscriptions and purchases. Null means to follow the Fusebill account default.

trackedItemDisplayFormat Object

PropertyTypeDescription
trackedItemDisplayFormatEnum:{Inline, SeperatePage}Controls where the tracked items are displayed.
showTrackedItemNameBooleanThis controls if the tracked items names are displayed.
showTrackedItemReferenceBooleanThis controls if the tracked items' reference are displayed.
showTrackedItemDescriptionBooleanThis controls if the tracked items' description are displayed.
showTrackedItemCreatedDateBooleanThis controls if tracked items' created dates are displayed.

Address Preference Object

PropertyTypeDescription
contactNameStringThis 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]
shippingInstructionsStringThis free text field allows you to add shipping instructions such as "Bring to Loading Bay #7".

[Max Length: 1000]
useBillingAddressAsShippingAddressBooleanIf true, billing address is used as the shipping address.

Monthly Billing Period Object

PropertyTypeDescription
typeEnum: {CustomerActivation,
FirstSubscriptionActivation, SpecifiedDate}
Default billing period types for this customer's monthly subscriptions.
ruleEnum: {SingleInvoice, MultipleInvoices, Prompt, OneInvoicePerDay}The invoicing rule for monthly billing periods. Single Invoice compiles subscriptions of the given interval on one invoice. Multiple Invoices separates them as one invoice per subscription. One Invoice Per Day posts an invoice every day. Prompt requires an agent to approve it each time.
dayInteger (1-28)The day of the month to begin invoicing.

Annual Billing Period Object

PropertyTypeDescription
typeEnum: {CustomerActivation,
FirstSubscriptionActivation, SpecifiedDate}
Default billing period types for this customer's yearly subscriptions.
ruleEnum: {SingleInvoice, MultipleInvoices, Prompt, OneInvoicePerDay}The invoicing rule for yearly billing periods. Single Invoice compiles subscriptions of the given interval on one invoice. Multiple Invoices separates them as one invoice per subscription. One Invoice Per Day posts an invoice every day. Prompt requires an agent to approve it each time.
monthInteger (1-12)Month to begin annual invoicing.
dayInteger (1-28)Day of the month to begin invoicing.
Examples
curl -X POST "https://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)
{
  "username": "Bob78",
  "firstName": "Robert",
  "middleName": "James",
  "lastName": "Smith",
  "companyName": "Fusebill",
  "suffix": "jr",
  "primaryEmail": "[email protected]",
  "primaryPhone": 5551115555,
  "secondaryEmail": "[email protected]",
  "secondaryPhone": 1115551111,
  "title": "Dr",
  "reference": "CR12345",
  "currency": "USD",
  "customerReference": {
    "reference1": "custom value 1",
    "reference2": "custom value 2",
    "reference3": "custom value 3",
    "salesTrackingCodes": [
      {
        "type": "Sales Tracking Code 2",
        "code": "BravoCode"
      }
    ]
  },
  "customerAcquisition": {
    "adContent": "sample string 1",
    "campaign": "sample string 2",
    "keyword": "sample string 3",
    "landingPage": "sample string 4",
    "medium": "sample string 5",
    "source": "sample string 6"
  },
  "billingSetting": {
    "term": "Net0",
    "autoCollect": true,
    "rechargeType": "BringBalanceBackTo",
    "rechargeThresholdAmount": 100,
    "rechargeTargetAmount": 150,
    "statusOnThreshold": true,
    "autoPostDraftInvoice": true,
    "customerGracePeriod": 1,
    "gracePeriodExtension": 1,
    "showZeroDollarCharges": true,
    "taxExempt": false
  },
  "billing": {
    "companyName": "Fusebill",
    "line1": "38 Main St",
    "city": "Brisbane",
    "postalZip": 12345,
    "country": "USA",
    "state": "NM"
  },
  "Shipping": {
    "companyName": "Fusebill",
    "line1": "39 Main St",
    "city": "Brisbane",
    "postalZip": 12345,
    "country": "USA",
    "state": "NM"
  },
  "addressPreference": {
    "useBillingAddressAsShippingAddress": true
  },
  "monthlyBillingPeriodConfiguration": {
    "type": "CustomerActivation",
    "rule": "SingleInvoice",
    "day": 10
  }
}
Response
{
  "firstName": "Shields",
  "middleName": "Payne",
  "lastName": "Gillespie",
  "companyName": "Cuizine",
  "suffix": "Jr.",
  "primaryEmail": "[email protected]",
  "primaryPhone": 8784473067,
  "secondaryEmail": "[email protected]",
  "secondaryPhone": 8955793436,
  "title": "Dr",
  "reference": 100986,
  "status": "Draft",
  "customerAccountStatus": "Good",
  "currency": "USD",
  "customerReference": {
    "reference1": null,
    "reference2": "customValue",
    "reference3": null,
    "salesTrackingCodes": [],
    "id": 12000750,
    "uri": "https://secure.fusebill.com/v1/customers/12000750"
  },
  "customerAcquisition": {
    "adContent": null,
    "campaign": null,
    "keyword": null,
    "landingPage": null,
    "medium": null,
    "source": null,
    "id": 12000750,
    "uri": "https://secure.fusebill.com/v1/customers/12000750"
  },
  "monthlyRecurringRevenue": 250,
  "netMonthlyRecurringRevenue": 220,
  "salesforceId": 12345678,
  "salesforceAccountType": null,
  "salesforceSynchStatus": "Enabled",
  "netsuiteId": 12345678,
  "netsuiteSynchStatus": "Enabled",
  "netsuiteCustomerType": "Individual",
  "portalUserName": "Shields1974",
  "parentId": 12000749,
  "quickBooksLatchType": null,
  "quickBooksId": null,
  "quickBooksSyncToken": null,
  "hubSpotId": null,
  "hubSpotCompanyId":null,
  "geotabId": "7813",
  "modifiedTimestamp": "2019-11-07T15:51:11.1915461Z",
  "createdTimestamp": "2018-01-01T03:33:33.02",
  "id": 12000750,
  "uri": "https://secure.fusebill.com/v1/customers/12000750"
}
{
    "ErrorId": 0,
    "HttpStatusCode": 400,
    "Errors": [
        {
            "Key": "customer.PrimaryEmail",
            "Value": "Please enter valid email addresses"
        }
    ]
}
Language
Authorization