Getting started

You've signed up to our service, you've activated your account and you have received an email with the API keys to your sandbox and live environments, so now what?

This tutorial will see you through the various steps required in order to get your customers onto Billingbooth and getting some charges being applied to them.

Your example organisation

Your organisation rents office space in a building with three different sized office units. The rent you are charging for each size of office is the same for all your customers, except for one who has a special arrangement with you as they have taken out a short-lease contract out. Your customers get invoiced on a monthly basis, typically on the last working day of every month.

You want to automate your invoicing so that all your customers receive your invoices via email on a regular basis.

1. Create your products

You have three different sized office units, each one of which has a fixed monthly price, so you create three products with the cost of each office unit:

POST https://api.billingbooth.com/v1/products

{
   "name": "Small Office",
   "reference": "small-office",
   "type": "Recurring",
   "frequency": "Monthly",
   "cost": [
      {
         "tariff": "default",
         "amount": 99.99
      }
   ]
}
POST https://api.billingbooth.com/v1/products

{
   "name": "Medium Office",
   "reference": "medium-office",
   "type": "Recurring",
   "frequency": "Monthly",
   "cost": [
      {
         "tariff": "default",
         "amount": 249.99
      }
   ]
}
POST https://api.billingbooth.com/v1/products

{
   "name": "Large Office",
   "reference": "large-office",
   "type": "Recurring",
   "frequency": "Monthly",
   "cost": [
      {
         "tariff": "default",
         "amount": 999.99
      }
   ]
}

The above creates the three different products matching the three different office sizes, and prices them at 99.99, 249.99 and 999.99 a month respectively. The products can then be used when applying charges to our customers in step 3 by using the reference property.

2. Create your customers

You have over a dozen customers currently renting office space from you, so you create each customer in Billingbooth with a full set of their invoicing address details:

POST https://api.billingbooth.com/v1/customers

{
   "name": "My Customer Ltd",
   "reference": "CUSTOMER001",
   "billed_directly": true,
   "billing_address": {
      "line1": "The Old Warehouse",
      "line2": "2 Michael Road",
      "town": "London",
      "county": "Greater London",
      "postcode": "SW6 2AD",
      "country": "United Kingdom"
   }
}

For each customer, the above request is made with the appropriate details. The reference CUSTOMER001 is the internal reference you have for the customer within your existing CRM system, so you use this reference match information between your CRM system and Billingbooth.

3. Create your charges

The last step involves you creating some recurring charges against your customers. You will use the products create in step 1 as a basis for the charge. The advantage of using the product, rather than a direct charge, is that if you decide to increase the rent on a particular office size, by changing the cost of the product, it will automatically apply the new cost to all customers from the next invoicing cycle.

You create the charge using the CUSTOMER001 customer reference, and the small-office product reference:

POST https://api.billingbooth.com/v1/customers/CUSTOMER001/charges

{
    "quantity": 1,
    "product": "small-office"
}

You do this for all your customers, and this adds a recurring charge to each one which gets applied on a monthly basis.

You now just have the matter of the customer with the special arrangements for rent. Because they are leasing your office space for a short period of time, the price you are setting for that office space is tailored specifically for this customer.

Because of the unique nature of the office space cost on this customer, it's not worth creating a product to try and encompass the charge, as it will only ever be used once. For this reason, you directly create a recurring charge:

POST https://api.billingbooth.com/v1/customers/CUSTOMER012/charges

{
   "quantity": 1,
   "description": "Office Space Hire",
   "type": "Recurring",
   "frequency": "Monthly",
   "amount": 599.99
}

The above request creates a new recurring charge with a description of Office Space Hire, and you set the recurring payment to charge 599.99 on every frequency interval.

Well that was easy, what now?

If you followed the tutorial steps on this page, you will now have a working set of charges against a group of customers with pre-defined products. By default, they will be invoiced on the first of every month via email.

You may now want to change the invoicing schedule, or create new products or tariffs. For detailed information on all the functionality available on Billingbooth, please read our API documentation.