Quaderno API (20241028)

This section covers the conventions that apply across all Quaderno API endpoints: authentication, rate limits, pagination, error codes, and versioning.

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

The API key is passed via HTTP Basic Auth. Set the key as the username and leave the password blank:

-u <YOUR_API_KEY>:

Using that modifier with curl sends a request with an Authorization: Basic … header. Example authenticated request:

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

You can also call /ping to verify your credentials and check your remaining requests without consuming a real API call:

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

Keep your API key secret. Anyone who has it can read and modify everything your account has access to.

To discover the ACCOUNT_NAME for your target account, call the /authorization endpoint:

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

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

Response fields:

Parameter	Description
id	An internal identifier. Do not use this to reference users in API requests.
name	The user's full name.
email	The user's email address.
publishable_key	The user's publishable key, for use in frontend integrations.
href	The custom API endpoint URL for this account. The ACCOUNT_NAME appears between https:// and .quadernoapp.

If the user does not have permission to perform an action, the API returns 401 Unauthorized.

The current limit is 100 API calls per 15 seconds.

Every successful API response includes the following headers to help you track usage:

• X-RateLimit-Limit: Maximum requests allowed per time window.
• X-RateLimit-Remaining: Requests remaining in the current window.
• X-RateLimit-Reset: UTC epoch timestamp when the window resets.

When you exceed the limit, the API returns 429 Too Many Requests. We reserve the right to adjust these limits, but will keep them high enough for well-behaved applications.

List endpoints are paginated using a created_before parameter. Pass an object ID to retrieve objects created before that ID, in reverse chronological order (newest first).

Response headers:

• X-Pages-HasMore: true if additional records can be fetched.
• X-Pages-NextPage: The URL to fetch the next page. Only present when more records exist.

The default page size is 25 objects, configurable with the limit parameter up to a maximum of 100.

Example paginated request:

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

The Quaderno API uses standard HTTP status codes:

Code	Text	Description
400	Bad Request	The request is malformed or missing required parameters.
401	Unauthorized	Invalid API key or insufficient permissions.
403	Forbidden	The requested resource is restricted.
404	Not Found	The requested resource does not exist.
405	Method Not Allowed	The HTTP method is not supported for this endpoint.
406	Not Acceptable	The request contains invalid parameter values (e.g. an unrecognized tax code).
410	Gone	The resource has been permanently removed.
422	Unprocessable Entity	The request is well-formed but cannot be processed for the given resource state.
429	Too Many Requests	You have exceeded the rate limit. See Rate Limiting.
500	Internal Server Error	An unexpected error occurred on our end. Please try again later.
502	Bad Gateway	A gateway error occurred on our end. Please try again later.
503	Service Unavailable	The API is temporarily offline for maintenance. Please try again later.
504	Gateway Timeout	The request timed out on our end. Please try again later.

When an API error occurs, Quaderno does not retry or track the failed call. Retry logic is the responsibility of your integration.

The Quaderno API is versioned using the release date as the version name (e.g. 20241028).

A new version is released only when a breaking change is introduced — such as renaming a field, changing a field type, or removing an endpoint.

Non-breaking additions (new endpoints, new optional parameters, new response fields) are applied directly to your current API version without requiring an upgrade.

Quaderno considers the following to be backwards-compatible changes:

• Adding new API resources.
• Adding new optional request parameters to existing 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 (object IDs, error messages, etc.).
• Adding new webhook event types.

Your integration should handle backwards-compatible changes gracefully, ignoring unexpected fields rather than failing.

Example of a breaking change:

// Before version 20210316:
GET /taxes/calculate?country=US&postal_code=94010

// From version 20210316:
GET /tax_rates/calculate?to_country=US&to_postal_code=90210&tax_code=standard&amount=10

Upgrade to the latest API version to benefit from new functionality. All changes are documented in the API Changelog.

Because upgrades to versions with breaking changes may affect your integration, we recommend testing in Quaderno Sandbox before upgrading production.

To upgrade or view your current version, go to Profile → API Keys.

You can also override the API version programmatically on a per-request basis using the Accept header:

curl https://ACCOUNT_NAME.quadernoapp.com/api/contacts \
  -u <YOUR_API_KEY>: \
  -H 'Accept: application/json; api_version: 20160602'

Version sunsetting and backported changes

We periodically sunset old API versions. Affected accounts are notified at least one month in advance, and our Engineering team provides full support during the transition.

In exceptional cases, we may backport breaking changes to all API versions for legal, security, or compliance reasons. These changes are communicated with the same advance notice as sunsetting.

Stay informed

To receive announcements about version sunsetting, backported changes, and new releases, ask your account admin to add a developer role with a valid email address.

For new features and product updates, see quaderno.io/blog/changelog.

Safely upgrading to API version 20220325

Version 20220325 replaces the freeform notice field in /tax_rates/calculate responses with a structured status code:

• taxable: The transaction is taxable and the calculator returns a non-zero rate.
• non_taxable: The transaction is exempt — either the product is not taxable in that jurisdiction (e.g. digital goods in California), or the customer's region is exempt within a registered jurisdiction.
• not_registered: You are not registered to collect tax in the customer's jurisdiction.
• reverse_charge: The transaction is subject to reverse charge; no VAT is calculated.

If your integration reads the notice field, switch to the status field. The notice field is no longer returned.

Safely upgrading to API version 20210701

From 1 July 2021, invoices and credit notes become final (non-editable) when any of the following occur:

• The document has been sent to the customer.
• The document has been paid.
• The document has been manually marked as final in the dashboard.

To correct a finalized invoice, issue a credit note against it and create a new invoice.

Fields that remain editable on finalized documents: po_number, tag_list, payment_details, notes, custom_metadata, and billing address fields (street_line_1, street_line_2, city, region, postal_code).

API changes introduced:

• DELETE /invoices/INVOICE_ID returns 410 Gone.
• PUT /invoices/INVOICE_ID only accepts the fields listed above.

If your use case issues invoices automatically at the point of payment, consider migrating to the Transactions API, which creates the contact, invoice, and payment record in a single API call.

Safely upgrading to API version 20210316

Version 20210316 introduces two breaking changes:

Tax calculation endpoint

The /taxes/calculate endpoint is replaced by /tax_rates/calculate:

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

The new endpoint only returns tax rates for jurisdictions where your account is registered. If you are getting a 0% rate, check your registered tax jurisdictions.

Pagination

Cursor-based pagination replaces page-based pagination. Replace the page parameter with created_before, passing the ID of the last object from the previous response. Response headers changed:

Old header	New header
X-Pages-CurrentPage	X-Pages-HasMore
X-Pages-TotalPages	X-Pages-NextPage

The maximum page size remains 100 objects, returned in reverse chronological order.

To test before committing, override the version on individual requests:

curl https://ACCOUNT_NAME.quadernoapp.com/api/contacts \
  -u <YOUR_API_KEY>: \
  -H 'Accept: application/json; api_version: 20210316'

Transactions create billing documents from payment processor events. Pass a sale, refund, or other event from Stripe, PayPal, or another processor and Quaderno will generate the correct invoice, receipt, or credit note, calculate the applicable taxes, and optionally deliver the document to your customer.

Contacts represent the customers and vendors who appear on your invoices, credit notes, and expenses. Each contact stores the billing information and tax identification data Quaderno uses to determine the correct tax treatment for every transaction.

Products describe the goods and services you sell. Attaching a product to an invoice line item ensures consistent tax classification across all documents.

The Tax Rates endpoint calculates the applicable tax rates for a given customer address and product type. Use it at checkout to show customers the correct tax before charging them, or to validate your own tax logic against Quaderno's engine.

Registrations represent your tax IDs — the numbers issued by tax authorities in each jurisdiction where your business is registered to collect tax. Use the validate endpoint to check whether a customer's tax ID is active before applying B2B exemptions such as EU reverse charge.

Tax jurisdictions are the geographic areas where specific tax rules apply — countries, states, and provinces. Use this endpoint to retrieve supported jurisdictions along with their applicable tax rates and registration requirements.

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

Tax codes classify your products and services for tax purposes. Different jurisdictions apply different rules depending on whether an item is a physical good, a digital service, a SaaS subscription, or an ebook. Assigning the right tax code ensures Quaderno applies the correct rate — and the correct exemption — for every sale.

Evidence records the customer location signals — IP address, billing country, bank country — that you have collected for a sale. For EU VAT on digital services, you must store at least two non-conflicting pieces of evidence per transaction to comply with the rules-of-origin requirements.