Why waste time building your own billing system when you can use FreshBooks and get back to what you’d rather be doing? You can add FreshBooks recurring billing to your applications very easily through the FreshBooks API. Set up subscriptions, accept credit cards, and monitor payments with a few lines of code.
Managing subscriptions to FreshBooks centers around creating recurring profiles. The same functionality available in the web application found on the Invoice tab under the Recurring subtab is available through the FreshBooks API.
FreshBooks recurring profiles create and send invoices automatically for you so you don’t have to manage them yourself. FreshBooks recurring profiles do some interesting tricks:
- Automatically send recurring invoices monthly, yearly, or as little or often as you would like.
- Automatically charge your client’s credit card whenever you generate an invoice.
- Rack up charges. Add or remove line items or a subscription at any time.
- Send invoices by email or through the post.
Setting up a basic subscription
The foundation of all application billing in FreshBooks relies on setting up a basic subscription. Follow these simple steps to get started.
Create a client through Client.create. Store the client_id in the response code.
Create a recurring profile using Recurring.create for the client_id. If you do not specify a date, the first invoice will be sent immediately.
Store the client_id and recurring_id with the client record in your own database to make them easy to reference in future API calls.
Letting FreshBooks capture credit cards
If you want to accept credit card payments but you do not want to take on the burden and liability of having credit cards pass through your system, you can use FreshBooks to capture credit cards for you. Make sure you have one of our auto-bill capable payment gateways.
When creating a subscription, do not specify the date. A new invoice will be created immediately. The invoice_id will be sent in the response.
Note: You may want to set a return_uri on the recurring profile so your customers will be returned back to your application after they pay your invoice.
Then, get the invoice details for the invoice_id using Invoice.get. Redirect your customer’s user agent to the Invoice.links.client_view URL. Your customers can then pay the invoice from there with your credit card.
If your customers choose to, they can set themselves up to be automatically charged for all future invoices from there.
Capturing credit cards on your website or application
If you feel comfortable with the security implications of taking credit cards in your application, you can pass them to FreshBooks when creating a recurring profile. Just provide the
After you pass the credit card information to FreshBooks, we recommend you destroy the data. FreshBooks will store the credit card information on our secure servers so you are not burdened with the liability of managing credit card information. If you are capturing credit cards on your website, we strongly recommend you do so over HTTPS, an encrypted protocol. Here are instructions on how to set up HTTPS in Apache and IIS.
Make sure you have one of our auto-bill capable payment gateways.
Charging your customer’s credit card for a one-time invoice
If you want to charge your customer’s credit card just for one transaction, follow the instructions above but create a subscription for today with only 1 occurrences and provide the
Only one invoice will be created and their credit card will be charged only once. If you don’t specify a date on the recurring profile, the invoice will be created immediately and their credit card will be charged immediately.
Getting notified of payment
You can be notified when a payment arrives by registering a Webhook for the Payment.create event. Then using the Webhook’s object_id as the payment_id, call Payment.get to get the invoice_id and client_id.
Checking if a client should be suspended
You can determine if a client is in arrears by calling Invoice.list with their client_id and with the special ‘unpaid’ status filter. If you have a policy of letting clients pay late, you can limit the list to only old unpaid invoices with the date_to filter.
You can also automatically be notified when an account is past due by subscribing to the invoice.pastdue.1, invoice.pastdue.2, and invoice.pastdue.3 series of Webhooks.
Suspending and cancelling a subscription
You can suspend a subscription by calling Recurring.update and setting the stopped field to 1. To resume the subscription, update it and set the stopped field to 0.
To cancel a subscription, delete the recurring profile using Recurring.delete.
You can fulfill coupons on subscriptions by either
- Adding a discount to the recurring profile to give a percentage discount
- Adding a negative value line item to the recurring profile to give a cash discount (e.g. -$10.00)
Because you can modify a recurring profile at any time, you can remove the discount later and future invoices and payments will be for the full amount.
In fact it’s easy to manage one-time discounts. First, create a recurring profile that starts immediately by not providing a date on the recurring profile, and put the discount on that profile. An invoice will immediately be generated with the discount. Then immediately update the recurring profile with Recurring.update to remove the discount from future invoices.
Racking up charges
You can modify a FreshBooks recurring profile at any time. The next invoice generated will reflect the profile as of the moment it is generated.
If your customers rack up charges throughout the billing period, you can keep track of charges to date on the FreshBooks recurring profile. First, get the existing profile with Recurring.get. Add a line item to the XML you get and submit it back to Recurring.update.
Don’t forget to empty the recurring profile at the start of a billing period. You can either set a scheduled event (e.g. a cron job) on your own server to do this, or you can be notified when each invoice is created and empty the invoice then.
To be notified, create a Webhook for the Invoice.create event. When you get the Webhook notification, call Invoice.get using the Webhook object_id as the invoice_id. You can then get the recurring_id from the invoice. We recommend for robustness using both a scheduled job and a Webhook notification. If for any reason your server is down and does not receive the Webhook notification, the scheduled task can run at a predictable time and empty the recurring profile.