API Versioning

The Quaderno API is versioned. Our API versions are named for the date the version is released, like 20210701.
A new API version is released when we introduce a backwards-incompatible change to the API. For example, changing a field type or name, or deprecating endpoints.
// Prior to version 20210316 the tax calculation endpoint was called like:
/taxes/calculate?country=US&postal_code=94010

// From version 20210316 taxes are calculated with:
/tax_rates/calculate?to_country=US&to_postal_code=90210&tax_code=standard&amount=10
Backwards-incompatible (also called breaking changes) example.
 
The worldwide tax panorama changes fast, and so we adapt. While we're adding functionality to our API, we won't release a new API version. You'll be able to take advantage of this non-breaking backwards-compatible changes directly on the API version you're currently using.
 
Quaderno considers the following changes to be backwards-compatible:
  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
  • Adding new event types.
Your integration should gracefully handle backwards-compatible changes.
 

Upgrading your API version

If you’re running an older version of the API, upgrade to the latest version to take advantage of new functionality or to streamline responses so the API is faster for you.
All changes are published on the API Changelog.
You programatically override the account's default API version with an Accept: api_version=version_number header.
curl https://ACCOUNT_NAME.quadernoapp.com/api/contacts.json?created_before=2048 \
  -u YOUR_API_KEY:x \
  -H 'Accept: application/json; api_version=20160602'
Programmatically overriding API version example. You can select a default API version on the App, under Profile → API Keys.
Upgrading your API version might break your current integration so we recommend testing on Quaderno Sandbox first.
To make the API upgrade definitive or see what version you’re running, visit your Profile → API Keys.
 

Version sunsetting and backported changes

From time to time, we will sunset old API versions. All Quaderno accounts using that version will be notified with at least one month in advance. Our own Engineering team will provide full support during transition.
Exceptionally, we might be forced to backport backwards-incompatible changes to all API versions for legal or security reasons. This is the case of the removal of the DELETE /invoices/INVOICE_ID endpoint last summer. These changes receive the same treatment as sunsetting API versions.
 

Stay informed

To get important announcements regarding version sunsetting, backported changes, and new API versions, please ask you account admin to add a developer role to their account with a valid email so that API announcements reach its audience.
You can also check our What's New for being informed of new features and improvements added to the app, and developer and integrations news.