Multi-item bills now available

Announcements
1

Hello,

We’re preparing to release new Bills API functionality to enable bills with multiple items, and would like to invite you to test your API integrations early to check compatibility before the end of June.

Our Sandbox API at https://api.sandbox.freeagent.com now has the multi-item bills feature enabled, which will allow you to create a bill with zero, one or multiple items in any number of accounting categories.

If you don’t fetch, create or update bills, then you’ll be unaffected by this change and don’t need to re-test anything. Please note that this is not yet available in production (api.freeagent.com); only one bill item will be supported there until release, around the end of June/early July. We’ll announce again when this is available.

Multi-item bill APIs

The API structure is unchanged (since the introduction of bill_items last year) however the bill_items array will now support zero to multiple items.

  • When getting a bill, the bill_items array may now be empty, contain one item (current behaviour) or multiple items. If you are parsing bill_items then you will need to test that you can handle all three possibilities and not assume it always contains one item. This is particularly important if fetching all bills, as a user or third party integration could have created a zero/multi-item bill.

  • When creating a bill over the API, you can now supply up to 40 bill items in the array. If you had been creating many separate bills, then consider combining it into a single bill when this feature becomes generally-available.

  • When updating a bill over the API, you can add new items by specifying "url": "", delete existing items by providing the url and "_destroy": 1, or update existing items by specifying the url and any attributes of the bill item you want to change. See the “Example Multi-Item Request Body” sample here for examples of each. It’s important to always specify the bill item’s url when updating existing bill items to ensure we know which line item you’re intending to change.

Sample data

We’ve added a temporary sandbox-only API that can generate sample multi-item bills in your sandbox account, which could be useful to test your integration’s ability to read existing bills in a customer’s account. If you don’t already have a sandbox account, follow the Quick Start steps.

Call POST https://api.sandbox.freeagent.com/v2/sandbox/bills/generate using your app’s regular OAuth2 credentials (curl example).

This will start generating bills over a three month period by default, and three bills per month. To change the period, pass the number of months in the request body ({"months": 9}) and set the Content-Type: application/json header.

You will then be able to view these multi-item bills using the list all bills with nested bill items API. Note that bills won’t be generated in any of the account’s locked periods.

Help available

If you have any questions about the feature or how the API works, please ask on this forum or email mcb-support@freeagent.com, and I’ll do my best to help out. If you have tested and are happy that it’s working well, please do let us know.

Kind regards,

Dominic
FreeAgent

2

Support for multi-item bills available is now available and part of the live FreeAgent API (changelog). If your integration is accessing customers bills, please expect zero, one, or multiple items to start being returned - all with the same bill item format as before.

If you want to start creating bills with multiple items, this is possible on the Bills API simply by adding all of the line items to the bill_items array (create bill API docs). The update bill API also supports adding, deleting and updating any of the items on a bill.

If you have any trouble with this new functionality, please post to this API Discussion forum for help.

1 Like