New Bills & Bill Items API clarification


I’m hoping for some clarification on the new Bill API rollout.

The original topic (Bill Changes and Deprecations, Bills with Multiple Line Items) seems to imply that we’re now on stage 2.

It’s been 3 months since deprecation was initiated.

Could someone please give very clear dates to explain where the API is at just now? Are we on the first stage? Is stage 2 delayed? Have we moved to stage 2 now? I got an email about 1st September - this doesn’t align with the original post.

Perhaps the original post could be updated with specific dates and current status?

Many thanks.

1 Like

Hi @ptgnet

Thanks for getting in touch! My apologies that we haven’t updated the original post and timelines, I’ll make sure to get those updated today.

We’ve found some hidden complexity in our build which has meant we’ve had to adjust our timescale on completing the deprecation.

After September 1st:

  • We will no longer guarantee functionality of the old endpoints - these could be switched off at any time after this date.

  • We will still only accept a single line item at this time.

  • Once the old endpoints have been removed, we’ll post to the forum to let you all know and existing integrators can stop sending the FreeAgent-Feature header and we will only accept the new schema.

What’s next on the engineering side

  • Behind the scenes, we have some engineering work to complete once all our users have switched to our new endpoints to build the multiple line items onto Bills.

Multi-item Bill Feature Release (Q1 2022)

  • Restrictions on number of line items will be removed, enabling creation of bills with multiple line items. When this happens, we’ll post to the API forum to let everyone know and there’ll be a pre-release note to let you all know when it is available on our Sandbox environment for testing.

I hope this is clearer, please let me know if you have any further questions!

All the best,

1 Like

Thanks for the clarification, this helps.

There is one other part that’s unclear.


Are you saying after 1st September we’ll still need to supply the FreeAgent-Feature header?

As I see it there are 2 stages for api deprecation for legacy api implementations:

  1. can use original bills api, AND require FreeAgent-Feature header to use newer bills api
  2. no longer require FreeAgent-Feature header

These are mutually exclusive and can’t live at the same time. The wording you us above is confusing:

could be switched of at any time” and “once the old endpoints have been removed”. So is there a point after 1st September, “at any time” where you’ll make the switch? Or is it 1st September?

I think having a clear, unambiguous cut-off point is required. Basically I don’t plan to use the feature header… I just need to know when it’s live.

We’re working with our integrators and developers to get as many apps as possible using the new header before switching it off and causing any widespread issues. In order to do this, we’re using the header to help us identify any users who have yet to switch and may need some assistance and we expect that come 1st September, we still may have some users in this position.

As such we don’t have an exact date for switching over, but we’d appreciate your help by using the new version before 1st September if at all possible.

However, I’ll make sure that we post to the API forum with a more specific date roughly a week before the switch.

If there’s anything else I can help with, please let me know!


thanks for the awesome information.

Hi Anna, any update on Multi-Item BILL support in the sandbox or going live? It was originally penned for 1Q22. Thanks. Greg

Sorry, I missed this! We’re hoping to enable the multi-item support on the sandbox in the next week and then to go live within 1-2 months. Look out for another announcement shortly with details about sandbox testing.

Kind regards,

Please see Multi-item bills now available for Sandbox testing for more details about testing in the Sandbox.


All good. I’ve run the smoke tests and it’s ok. I haven’t tested every permutation of fields, but for what 99% of users will do, it’s working. I’ve tried creating single line, multi-line, with various sales taxes, beyond limits with 44 items, and "GET"ing an empty bill.

1 Like

Thanks for taking the time to check, I’m happy to hear it works well!