Quaderno API (current version 20241028)

Quaderno uses an API key to authorize all requests, allowing access to the API in combination with the account name in the endpoint URL. You can find your API keys in quadernoapp.com/users/api-keys.

Quaderno expects the API key to be included via HTTP Basic Auth in all API requests to the server. When using curl, it looks like the following:

-u <YOUR_API_KEY>:x

Note that x is just a placeholder, only the API key will be taken into consideration.

Using that modifier on curl will send a request with an HTTP header like Authorization: Basic xxxx.

This would be a simple example of an authenticated GET request:

curl https://ACCOUNT_NAME.quadernoapp.com/api/invoices.json \
  -u <YOUR_API_KEY>:x

You can also /ping to check if the service is up, your credentials are correct, or to know your remaining requests without doing an actual request:

curl https://quadernoapp.com/api/ping \
  -u <YOUR_API_KEY>:x

Remember that anyone who has your private key can see and change everything that you have access to. Make sure to keep it, and your password, safe.

To learn the ACCOUNT_NAME for your target account, you can get it with the /authorization API call.

This returns the following as a JSON payload:

Parameter	Description
id	An identity, which is not used for determining who this user is within Quaderno. The id field should therefore not be used for submitting data within Quaderno's API.
name	The user's full name.
email	The user's email address.
publishable_key	The users's publishable key (to use on frontend development).
href	The custom API endpoint URL for the user, providing the sought-after ACCOUNT_NAME between https:// and .quadernoapp....

So, this curl call:

curl https://quadernoapp.com/api/authorization \
  -u <YOUR_API_KEY>:x

Returns JSON structured like this:

{
  "identity": {
    "id": "999",
    "name": "Sheldon Cooper",
    "email": "s.cooperphd@yahoo.com",
    "publishable_key":"pk_1111111111111111",
    "href": "https://nippur-999.quadernoapp.com/api/"
  }
}

Note that in all cases, if the user does not have permission to do something, you'll get a 401 Unauthorized error.

To make it easier to determine if your application is being rate-limited, or is approaching that level, we have the following HTTP headers on our successful responses:

• X-RateLimit-Reset: The remaining window before the rate limit resets in UTC epoch seconds.
• X-RateLimit-Remaining: The number of requests left for the time window.
• X-RateLimit-Limit: Request limit per time window.

The current limits are 100 API calls per 15 seconds.

We reserve the right to tune the limitations, but we promise to keep them high enough to allow a well-behaving interactive app to do it's job.

When you exceed the limit you will receive a HTTP 429 (Too Many Requests).

Pagination is performed with a created_before parameter. This parameter takes an existing object ID value and returns objects listed after the named object, in reverse chronological order.

The HTTP header X-Pages-HasMore indicates whether more records can be fetched by using the same query with a lower created_before.

The HTTP header X-Pages-NextPage contains the URL that should be used to fetch the next page of records. It is only present if more records exist.

Bear in mind that Quaderno paginates GET index results.

You can change the number of objects to be returned with the limit parameter, defaulting to 25. This value is capped at 100 objects.

Example of API call with the created_before parameter set:

curl https://ACCOUNT_NAME.quadernoapp.com/api/contacts?created_before=42 \
  -u <YOUR_API_KEY>:x

We don't usually have any trouble on our end, but when we do we'll let you know!

The Quaderno API uses the following error codes:

Code	Text	Description
400	Bad Request	Your request may be malformed
401	Unauthorized	Your API key is wrong, or your user does not have access to this resource
403	Forbidden	The record requested is hidden for administrators only
404	Not Found	The specified record could not be found
405	Method Not Allowed	You tried to access a record with an invalid method
406	Not Acceptable	You requested a format that isn't JSON
410	Gone	The record requested has been removed from our servers
422	Unprocessable Entity	The requested method cannot process for the record in question
429	Too Many Requests	You're requesting too many records! Slow down!
500	Internal Server Error	We had a problem with our server. Try again later.
502	Bad Gateway	We had a different problem with our server. Try again later.
503	Service Unavailable	We're temporarily offline for maintenance, or you've exceeded the rate limit. Please try again later.
504	Gateway Timeout	Yep, you guessed it. We'll be back soon!

Note that when API errors occur, it is up to you to retry your request - Quaderno does not keep track of failed calls.

The Quaderno API is versioned. Our API versions are named for the date the version is released, like 20220325.

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.

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.

Backwards-incompatible (also called breaking changes) example:

// 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

Make sure you upgrade to the latest API version to take advantage of new functionality and streamlined responses. All changes are published on the API Changelog.

Upgrading to an API version with breaking changes 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.

You can also 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'

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, as well as for hotfixes needed to adapt to 3rd parties changes. This is the case of the removal of the DELETE /invoices/INVOICE_ID endpoint during 2021 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 with a valid email to their account, so that our API announcements reach its audience.

For being informed of new features and improvements added to the app you can also check quaderno.io/blog/changelog.

Safely upgrading to API version 20220325

In order to avoid manually comparing the explanations of the notice field in the /tax_rates/calculate response, we've revamped the endpoint's reponse to get the calculation reasoning as a status code:

• taxable: the transaction is taxable and the calculator will return a non-zero rate.
• non_taxable: The transaction is non taxable if either the particular product is not taxable (ie. a digital product in California) or if the region for a particular territory within the registred jurisdiction is exempted (for example if you're registered in France selling to a customer from New Caledonia)
• not_registered: You're trying to calculate taxes in a jurisdiction you're not registered in.
• reverse_charge: The transaction is reverse charge so VAT won't be calculated

In case you were using the notice response field in your API automations, you'll need to swap to the status field, as notice is no longer returned.

Safely upgrading to API version 20210701

In our goal to make Quaderno compliant with tax rules worldwide, we limited the edition of invoices and credit notes via API as of 1st July, 2021.

From that date, an invoice is final (not editable) when any of the following occur:

• The invoice has been sent to the customer. All sent invoices are final and cannot be edited.
• The invoice has been paid. All paid invoices are final and cannot be edited.
• The invoice has been manually marked as final in the dashboard.

If you need to make any changes to invoice's items, taxes, issue date or tax ID, you'll need to issue a credit note and create a new invoice.

You will still be allowed to edit the customer's billing address, PO number, tags, payment details, additional notes, and custom metadata.

What this breaking change implies:

• DELETE /invoices/INVOICE_ID will cease to exist and return a 410 Gone.
• PUT /invoices/INVOICE_ID will only allow modification of the parameters po_number, tag_list, payment_details, notes, custom_metadata and all those related to the billing address: street_line_1,street_line_2,city,region,and postal_code.

Note that on 1 July the transition period for 20210316 ends as well, and the legacy endpoints for taxes and pagination will also respond 410 Gone.

If you're using these endpoints, you'll have to include extra logic in your code to issue a credit note and create a new invoice.

However, given your use case is one that automatically issues paid invoices (for instance, your customer's pays and then your system issues the invoice, not the other way around) and you're up for a challenge, our recommendation to face this change is to migrate to the Transactions API.

Why? Because you can create the contact (if doesn't exists yet), create the invoice, and insert the payment information, all in only one performant API call 🎉!

Safely upgrading to API version 20210316

Most changes simply add functionality, thus maintaining backwards compatibility. Occasionally, we release a version with breaking changes, such as 20210316.

Do not fret, the transition to 20210316 is as easy as pie 🥧.

Example of the new Tax Rates endpoint:

curl https://ACCOUNT_NAME.quadernoapp.com/api/tax_rates/calculate?to_country=US&to_postal_code=90210&tax_code=standard&amount=10 \
  -u <YOUR_API_KEY>:x

For calculating tax rates, altough the new endpoint accepts many more parameters, just changing the URL from /taxes/calculate to /tax_rates/calculate will do. Well, not so fast. It may seem it worked quickly, but you're probably getting a 0% tax rate. That's because now you can only collect taxes on Tax Jurisdictions where you're registered. So don't be tempted to create a new custom Tax Rate, just head to your Quaderno Account and update the tax jurisdictions where your business is registered in. Now we're talking! Quaderno will always provide updated worldwide tax rates seamlessly for you.

For paginating objects, we switched to a faster cursor based pagination approach and you'll need to change the page parameter for created_before, which references the ID of the object instead of the page number. You'll get a maximum of 100 objects in reverse chronological order (lower IDs means older objects). Note the response headers changed from X-Pages-CurrentPage and X-Pages-TotalPages to X-Pages-HasMore and X-Pages-NextPage.

You can test all this changes in our Sandbox. There are two approaches:

• Simply change the API version globally in Profile → API Keys. Note once you change it you cannot change it back, but you can override a concrete call sending the Accept HTTP header with: Accept: application/json; api_version=20170914
• Sending the Accept HTTP header with: Accept: application/json; api_version=20210316 on every call.

And that's basically it 🎉! Now you can go focus on your business while we deal with your taxes.

• We now return a 406 Not Acceptable HTTP response when the tax_code in the tax object on any item of the Transactions API is not valid. Valid values, humanized names and explanations can be obtained via the /tax_codes endpoint. Before this API version, any invalid value would be ignored and the account's default would be applied.
• Fixes a bug where the country param from the tax object on any item of the Transactions API was not required, even if it was documented as so.

• Pagination is now sorted by descending ID. This ensures the last item on each page matches the X-Pages-NextPage header, clarifying navigation without changing existing functionalities.
• Added the ability to set and read the permanent_establishment and import_scheme values when dealing with your business's registered jurisdictions on the /tax_ids endpoints. This change has been backported to all API versions.
• Information regarding invoices and credits deliveries to external systems like TicketBAI is now accessible via the deliveries object. You can learn more with our TicketBAI guide.

• From API version 20231201 onwards, the Transactions API will automatically dispatch invoices and credit notes if the option "Autosend all automatic invoices and credit notes" is selected in your account settings.
• The long-time deprecated /taxes/validate has been finally removed in favor of /tax_ids/validate. If you were still using it, just make sure your URLs are updated, and that you are sending the tax_id parameter (and not the old vat_number parameter).

Please consider upgrading your API version.

• Backwards-compatible change: API listing endpoints /invoices, /credits and /contacts now accept processor_id as filter parameter.
• Backwards-compatible change: Transactions API now returns the exchange_rate used when the transaction currency differs from the account's default currency.
• Backwards-compatible change: Billing API now accepts items and evidence objects as Transactions API does. Arrays of items_attributes and evidence_attributes are deprecated but still work.
• Backwards-compatible change: Expenses API now returns processor and processor_id on the payments objects of payed expenses.
• Breaking change: /tax_rates/calculate no longer returns a notice explanation text with the tax calculation reason.
• Backwards-compatible change: /tax_rates/calculate now always show a status on the response indicating a code for the calculation scenario.
• Backwards-compatible change: Added recurring_period and recurring_frequency to recurring documents.
• Backwards-compatible change: Added postal_code and web to accounts.

• Backwards-compatible change: Added verification_code and verification_permalink to invoices and credits.
• Backported breaking change: Maximum items per document are now limited up to 200. Before, this was a soft limit per API request, which could be workarounded with subsequent PUT calls.
• Backwards-compatible change: Billing API now supports partial refunds with the parameter credited_amount for invoices with one single item.
• Backwards-compatible change: passing none as the region parameter to the GET /jurisdictions endpoint returns jurisdictions that do not have a specific region.
• Backwards-compatible change: new threshold.eu.100k webhook for the Annual turnover report, to warn whenever sales of digital services within the EU (exclusive of VAT) reach €100,000. Applies only to EU-based sellers.
• Backported breaking change: abandoned checkout sessions are automatically removed after seven days of inactivity (this is, no updates or not submission attempts from the customer).
• Backwards-compatible change: we're adding new webhooks for the new Annual turnover report: threshold.warning and threshold.exceeded.
• Backported breaking change: we're removing the ability to edit coupons linked to Stripe coupons, as they won't allow edition and led to inconsistent states.
• Backported breaking change: to comply with tax rules worldwide, DELETE /invoices/INVOICE_ID and DELETE /credits/CREDIT_ID endpoints no longer exists and return 404 Not Found. Instead deleting invoices you should associate them to credit notes using POST /credits with the invoice id, which will change its state to paid instead the refunded state. To correct errors creating credits we also provide a PUT /credits/CREDIT_ID/void to void credit notes. Note the webhooks invoice.deleted and credit.deleted are also gone.
• Backported breaking change: to comply with tax rules worldwide, PUT /invoices/INVOICE_ID and PUT /credits/CREDIT_ID only allow modification of the parameters notes, tag_list, custom_metadata and all those related to the customer's address: street_line_1,street_line_2,city,region,postal_code and country. This change applies to ALL versions.
• Backwards-compatible change: /tax_rates/calculate now always show a product_type on the response. When you specified the product_type explicitly on the request, we've been showing it in the response. However when you didn't, we used the account's default for tax calculation, and did not return that field. Now we always return the field used for the tax calculation in the response, whether you made it explicit on the request, or the account's default is used. It's a more consistent and informative behaviour.
• Backwards-compatible change: creating and updating Connect custom accounts (POST and PUT to /accounts endpoint) now accepts specifying the default_product_type and default_tax_code. Before, defaults of service and eservice were applied.

• Breaking change: record pagination is no longer performed with a page parameter, but with a created_before parameter. See the pagination documentation for more details.
• Breaking change: the old /taxes/calculate endpoint is deprecated in favour of the /tax_rates/calculate endpoint.
• Adds a Deprecation: true header (as per draft-ietf-httpapi-deprecation-header-01) to responses using deprecated pagination, with a Link header linking to the updated documentation. After the deprecation dates, those endpoints will return a 410 Gone.

• Added the accounts API
• Added the related_document to the credit object.
• Added tax_1_transaction_type and tax_2_transaction_type fields to the taxes attributes in the credit object.
• Added transaction_type fields to the document items attributes in the credit object.
• Added kind, stripe_plan_id, paypal_interval_unit, paypal_interval_frequency and paypal_interval_duration fields in the item object.
• Changed number field limit to 20 characters for invoices, credits and estimates.

• Return 429 (too many requests) instead of 503 (service unavailable) on rate limits.

• Added custom_metadata as an editable field.

• country is now returned as an attribute for invoices, expenses, credits and estimates.

• Amounts are now returned as cents instead being formatted as amount with currency symbol.
• Versions are no longer passed as part of the URL, instead they can be passed as an accept header.

• First version.
• Amounts are returned formatted as amount with currency symbol.

Registered jurisdictions refer to the locations where your business is registered to collect taxes and has a local tax id. This registration is independent of the countries or states where you sell your products or services.