Quaderno API (20260309)

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:

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:

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:

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'

Tax transactions record every sale and refund that flows through your platform. Quaderno processes each transaction asynchronously — calculating the applicable taxes, determining the supply type, and flagging any discrepancies between the tax you collected and what was owed. Use transactions as the source of truth for tax reporting and compliance.

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 Calculations endpoint computes the applicable taxes for one or more line items in real time, without creating any records. 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 business's tax presence in a specific jurisdiction. Each registration pairs a tax jurisdiction with the local tax ID issued by that authority (for example, a VAT number in Germany or a GST registration in Australia). Quaderno uses your registrations to determine where you are obligated to collect tax and to apply the correct rules for each sale.