Quaderno API(current version 20241028)

Download OpenAPI specification:Download

API features

Authentication

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 inquadernoapp.com/users/api-keys.

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

-u <YOUR_API_KEY>:x

Note thatx 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 likeAuthorization: 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.

Authorization

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

This returns the following as a JSON payload:

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":"[email protected]","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.

Rate Limiting

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 are100 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 aHTTP 429 (Too Many Requests).

Pagination

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

The HTTP headerX-Pages-HasMore indicates whether more records can be fetched by using the same query with a lowercreated_before.

The HTTP headerX-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 paginatesGET index results.

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

Example of API call with thecreated_before parameter set:

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

Errors

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:

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

Versioning

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

A new API version is released when we introduce abackwards-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'readding 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 followingchanges to bebackwards-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

Upgrading your API version

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 onQuaderno Sandbox first.

To make the API upgrade definitive or see what version you’re running, visit yourProfile → API Keys.

You can also programatically override the account's default API version with anAccept: 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'

Versionsunsetting and backported changes

From time to time, we willsunset 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 tobackportbackwards-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 theDELETE /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 toadd 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 checkquaderno.io/blog/changelog.

Safely upgrading to API version 20220325

In order to avoid manually comparing the explanations of thenotice field in the/tax_rates/calculate response, we've revamped the endpoint's reponse to get the calculation reasoning as astatus 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 thenotice response field in your API automations, you'll need to swap to thestatus field, asnotice 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 a410 Gone.
• PUT /invoices/INVOICE_ID will only allow modification of the parameterspo_number,tag_list,payment_details,notes,custom_metadata and all those related to the billing address:street_line_1,street_line_2,city,region,andpostal_code.

Note that on 1 July the transition period for20210316 ends as well, and the legacy endpoints for taxes and pagination will also respond410 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 theTransactions 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

Forcalculating 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 thetax jurisdictions where your business is registered in. Now we're talking! Quaderno will always provide updated worldwide tax rates seamlessly for you.

Forpaginating objects, we switched to a faster cursor based pagination approach and you'll need to change thepage parameter forcreated_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 fromX-Pages-CurrentPage andX-Pages-TotalPages toX-Pages-HasMore andX-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 theAccept HTTP header with:Accept: application/json; api_version=20170914
• Sending theAccept 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.

Changelog

20241028

• Backported breaking change: Due to legal requirements, thenumber andissue_date parameters will be ignored when creating documents from Spanish accounts using the Verifactu electronic invoicing system. The Quaderno Templates system won't be available for these accounts either. Please note that backported breaking changes apply to all API versions.
• We now return a 406 Not Acceptable HTTP response when thetax_code in thetax object on anyitem of theTransactions 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 theaccount's default would be applied.
• Fixes a bug where thecountry param from thetax object on anyitem of theTransactions API was not required, even if it was documented as so.

20240705

• Pagination is now sorted by descending ID. This ensures the last item on each page matches theX-Pages-NextPage header, clarifying navigation without changing existing functionalities.
• Added the ability to set and read thepermanent_establishment andimport_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 regardinginvoices andcredits deliveries to external systems like TicketBAI is now accessible via thedeliveries object. You can learn more with ourTicketBAI guide.

20231201

• From API version20231201 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 thetax_id parameter (and not the oldvat_number parameter).

Please considerupgrading your API version.

20220325

• Backwards-compatible change: API listing endpoints/invoices,/credits and/contacts now acceptprocessor_id as filter parameter.
• Backwards-compatible change: Transactions API now returns theexchange_rate used when the transaction currency differs from the account's default currency.
• Backwards-compatible change: Billing API now acceptsitems andevidence objects as Transactions API does. Arrays ofitems_attributes andevidence_attributes are deprecated but still work.
• Backwards-compatible change: Expenses API now returnsprocessor andprocessor_id on thepayments objects of payed expenses.
• Breaking change:/tax_rates/calculate no longer returns anotice explanation text with the tax calculation reason.
• Backwards-compatible change:/tax_rates/calculate now always show astatus on the response indicating a code for the calculation scenario.
• Backwards-compatible change: Addedrecurring_period andrecurring_frequency to recurring documents.
• Backwards-compatible change: Addedpostal_code andweb to accounts.

20210701

• Backwards-compatible change: Addedverification_code andverification_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 parametercredited_amount for invoices with one single item.
• Backwards-compatible change: passingnone as theregion parameter to theGET /jurisdictions endpoint returns jurisdictions that do not have a specific region.
• Backwards-compatible change: newthreshold.eu.100k webhook for theAnnual 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 newAnnual turnover report:threshold.warning andthreshold.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 andDELETE /credits/CREDIT_ID endpoints no longer exists and return404 Not Found. Instead deleting invoices you should associate them to credit notes usingPOST /credits with the invoice id, which will change its state topaid instead therefunded state. To correct errors creating credits we also provide aPUT /credits/CREDIT_ID/void to void credit notes. Note the webhooksinvoice.deleted andcredit.deleted are also gone.
• Backported breaking change: to comply with tax rules worldwide,PUT /invoices/INVOICE_ID andPUT /credits/CREDIT_ID only allow modification of the parametersnotes,tag_list,custom_metadata and all those related to the customer's address:street_line_1,street_line_2,city,region,postal_code andcountry. This change applies to ALL versions.
• Backwards-compatible change:/tax_rates/calculate now always show aproduct_type on the response. When you specified theproduct_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 thedefault_product_type anddefault_tax_code. Before, defaults ofservice andeservice were applied.

20210316

• Breaking change: record pagination is no longer performed with apage parameter, but with acreated_before parameter. See thepagination documentation for more details.
• Breaking change: the old/taxes/calculate endpoint is deprecated in favour of the/tax_rates/calculate endpoint.
• Adds aDeprecation: true header (as perdraft-ietf-httpapi-deprecation-header-01) to responses using deprecated pagination, with aLink header linking to the updated documentation. After the deprecation dates, those endpoints will return a410 Gone.

20170914

• Added the accounts API
• Added therelated_document to the credit object.
• Addedtax_1_transaction_type andtax_2_transaction_type fields to the taxes attributes in the credit object.
• Addedtransaction_type fields to the document items attributes in the credit object.
• Addedkind,stripe_plan_id,paypal_interval_unit,paypal_interval_frequency andpaypal_interval_duration fields in the item object.
• Changednumber field limit to 20 characters forinvoices,credits andestimates.

20170628

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

20170418

• Addedcustom_metadata as an editable field.

20161108

• country is now returned as an attribute forinvoices,expenses,credits andestimates.

20160614

• 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.

20160602

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

Transactions

Create a transaction

Request Body schema:application/json

Contacts

List contacts

Create a contact

Request Body schema:application/json

Retrieve a contact

Update a contact

Request Body schema:application/json

Delete a contact

Products

List products

Create a product

Request Body schema:application/json

Retrieve a product

Update a product

Request Body schema:application/json

Delete a product

Tax Rates

Calculate a tax rate

Tax IDs

Validate a tax id

Tax Jurisdictions

Retrieve a jurisdiction

List all jurisdiction

Registered Jurisdictions

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.

List tax IDs

Create a tax ID

Request Body schema:application/json

Retrieve a tax ID

Update a tax ID

Request Body schema:application/json

Delete a tax ID

Tax Codes

Retrieve a tax code

List all tax codes

Evidence

List all evidence objects