openapi: '3.1' info: title: Quaderno API version: '20260309' description: > Quaderno helps you scale your business without stressing about taxes. Our powerful REST API solves all your tax compliance needs: - Accurate tax calculation on every sale, worldwide. - Billing with automatic invoices and credit notes. - Alerts for new tax obligations and registrations. - Tax reports by country or state. Here you can check our OpenAPI reference. Don't miss our developer [tools](/tools) and [guides](/guides) too! tags: - name: API features description: > This section covers the conventions that apply across all Quaderno API endpoints: authentication, rate limits, pagination, error codes, and versioning. ## Authentication 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](https://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 :` Using that modifier with curl sends a request with an `Authorization: Basic …` header. Example authenticated request: ```shell curl https://ACCOUNT_NAME.quadernoapp.com/api/invoices \ -u : ``` You can also call `/ping` to verify your credentials and check your remaining requests without consuming a real API call: ```shell curl https://quadernoapp.com/api/ping \ -u : ``` > **Keep your API key secret.** Anyone who has it can read and modify everything your account has access to. ## Authorization To discover the `ACCOUNT_NAME` for your target account, call the `/authorization` endpoint: ```shell curl https://quadernoapp.com/api/authorization \ -u : ``` Returns JSON structured like this: ```json { "identity": { "id": "999", "name": "Sheldon Cooper", "email": "s.cooperphd@yahoo.com", "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`. ## Rate Limiting 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. ## Pagination 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: ```shell curl https://ACCOUNT_NAME.quadernoapp.com/api/contacts?created_before=42 \ -u : ``` ## Errors 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](#tag/API-features/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. # Versioning 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 ``` ## Upgrading your API version Upgrade to the latest API version to benefit from new functionality. All changes are documented in the [API Changelog](/api-changelog). Because upgrades to versions with breaking changes may affect your integration, we recommend testing in [Quaderno Sandbox](/tools/sandbox/) before upgrading production. To upgrade or view your current version, go to **[Profile → API Keys](https://quadernoapp.com/users/api-keys)**. You can also override the API version programmatically on a per-request basis using the `Accept` header: ```shell curl https://ACCOUNT_NAME.quadernoapp.com/api/contacts \ -u : \ -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](https://support.quaderno.io/article/491-managing-your-team) with a valid email address. For new features and product updates, see [quaderno.io/blog/changelog](https://www.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](/api#tag/Transactions), 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`: ```shell curl https://ACCOUNT_NAME.quadernoapp.com/api/tax_rates/calculate?to_country=US&to_postal_code=90210&tax_code=standard&amount=10 \ -u : ``` 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](https://quadernoapp.com/settings/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: ```shell curl https://ACCOUNT_NAME.quadernoapp.com/api/contacts \ -u : \ -H 'Accept: application/json; api_version: 20210316' ``` x-traitTag: true - name: Transactions description: >- 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. - name: Contacts description: >- 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. - name: Products description: >- Products describe the goods and services you sell. Attaching a product to an invoice line item ensures consistent tax classification across all documents. - name: Calculations description: >- 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. - name: Registrations description: >- 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. - name: Jurisdictions description: >- Jurisdictions are the geographic areas that define their own tax rules — a country, a state, a province, or a territory. Quaderno maintains a curated list of all supported jurisdictions. Use this endpoint to look up jurisdiction IDs when creating or updating registrations. - name: Tax Codes description: >- 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. - name: Invoices description: >- Invoices are formal payment requests that document amounts owed by customers for goods or services. Once issued, invoices are legally immutable in most jurisdictions — only administrative fields can be changed. Use the void endpoint to correct a finalized invoice. - name: Receipts description: >- Receipts document completed transactions. Unlike invoices, receipts are always paid by definition — a payment method is required at creation. They are immutable after creation; use the void endpoint if a correction is needed. - name: Credits description: >- Credit notes reduce or cancel amounts owed by customers. They are used for refunds, order cancellations, and pricing corrections. Tax law prohibits deleting credit notes — voiding is the only way to reverse one. - name: Proformas description: >- Proformas are preliminary documents sent to customers before a sale is confirmed. They outline the expected cost and can be accepted, declined, or converted into a full invoice once the customer agrees. - name: Expenses description: >- Expenses record the costs your business incurs from vendors and suppliers. They appear in your financial reports and can be used to track deductible business expenditures. - name: Recurring Documents description: >- Recurring documents automatically generate invoices or expenses on a defined schedule — daily, weekly, monthly, or yearly. Use them to automate subscription billing and regular vendor payments without manual intervention. - name: Accounts description: >- Quaderno Connect accounts are sub-accounts that belong to your platform. Each account has its own invoices, contacts, and tax settings. Use this API to create and manage accounts on behalf of your users. - name: Addresses description: >- Addresses store the location history of a Quaderno Connect account. Each address has a validity period, allowing Quaderno to apply the correct tax rules based on where the business was located at any given point in time. - name: Reporting description: >- Reporting requests generate downloadable tax and billing reports asynchronously. Submit a request, then poll or wait for the report URL to become available once processing is complete. - name: Webhooks description: >- Webhooks notify your server in real time when events happen in a Quaderno account — such as an invoice being created, a payment being recorded, or a tax transaction being processed. Each webhook delivers a signed payload to a URL you control. x-tagGroups: - name: Quaderno API tags: - API features - name: Core tags: - Transactions - Contacts - Products - name: Taxes tags: - Calculations - Registrations - Jurisdictions - Tax Codes - name: Billing tags: - Invoices - Receipts - Credits - Proformas - Expenses - Recurring Documents - name: Connect tags: - Accounts - Addresses - name: Reporting tags: - Reporting - name: Webhooks tags: - Webhooks paths: /accounts/{id}: get: summary: Retrieve a custom account tags: - Accounts operationId: retrieveCustomAccount description: Retrieves the details of an existing Quaderno Connect custom account. parameters: - name: id in: path description: The ID of the custom account to retrieve. example: 41 required: true schema: type: integer responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/account' put: summary: Update a custom account tags: - Accounts operationId: updateCustomAccount description: Updates the details of an existing Quaderno Connect custom account. parameters: - name: id in: path description: The ID of the custom account to update. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/account' requestBody: content: application/json: schema: $ref: '#/components/schemas/account_update' required: true /accounts: post: summary: Create a custom account tags: - Accounts operationId: createCustomAccount description: Creates a new Quaderno Connect custom account. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/account' requestBody: content: application/json: schema: $ref: '#/components/schemas/account_create' required: true get: summary: List all accounts tags: - Accounts operationId: listCustomAccounts description: Retrieves a list of all Quaderno Connect accounts. responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/account' /addresses: get: summary: List addresses tags: - Addresses operationId: listAddresses description: >- Lists all addresses from a Quaderno Connect custom account, paginated and sorted by creation date (newest first). security: - Bearer token: {} responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/address' post: summary: Create an address tags: - Addresses operationId: createAddress description: Creates a new address to be used on a Quaderno Connect custom account. security: - Bearer token: {} parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/address' requestBody: content: application/json: schema: $ref: '#/components/schemas/address' /addresses/{id}: get: summary: Retrieve an address tags: - Addresses operationId: retrieveAddress description: Retrieves the details of an existing address. security: - Bearer token: {} parameters: - name: id in: path description: ID of the desired address. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/address' put: summary: Update an address tags: - Addresses operationId: updateAddress description: Updates a address. Any parameters not provided will be left unchanged. security: - Bearer token: {} parameters: - name: id in: path description: ID of the address to be updated. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/address' requestBody: content: application/json: schema: $ref: '#/components/schemas/address' /calculations: post: summary: Calculate tax tags: - Calculations operationId: calculateTax description: > Calculates the applicable taxes for one or more line items based on the seller's origin, the customer's address, and the product type. Pass `customer_tax_id` when selling to a business — Quaderno will determine whether the transaction qualifies for a reverse charge or zero-rate exemption. Use `tax_behavior` to control whether the returned amounts are tax-exclusive (the default) or tax-inclusive. When `inclusive`, the tax is extracted from the line item amount rather than added on top. security: - basicAuth: [] parameters: - name: Authorization in: header required: true schema: type: string responses: '200': description: Calculation result content: application/json: schema: $ref: '#/components/schemas/calculation' '400': description: validation error requestBody: content: application/json: schema: type: object properties: origin_address: type: object description: >- Physical location of the seller. Required for origin-based tax states (e.g. US states like Texas). Defaults to the account's registered address when omitted. properties: country: type: string description: Two-letter ISO 3166-1 country code. example: US postal_code: type: string description: Postal or ZIP code. example: '78701' state: type: string description: State or province code. Required for US and Canada. example: TX city: type: string description: City name. example: Austin customer_address: type: object description: >- Delivery or billing address of the customer. Used to determine the tax jurisdiction. required: - country properties: country: type: string description: Two-letter ISO 3166-1 country code. example: DE postal_code: type: string description: >- Postal or ZIP code. Required for accurate sub-national rates (US, Canada, Australia). example: '10115' state: type: string description: State or province code. example: TX city: type: string description: City name. example: Berlin customer_tax_id: type: string description: >- Business tax ID of the customer (e.g. a VAT number). When provided and valid, Quaderno applies B2B rules such as reverse charge or zero-rating. example: FR32123456789 currency: type: string description: >- Three-letter ISO 4217 currency code for the transaction. Defaults to the account's default currency. example: EUR tax_date: type: integer description: >- Unix timestamp for the tax point date. Defaults to the current date when omitted. Use this to apply the correct rates for past or future transactions. example: 1700000000 tax_behavior: type: string enum: - exclusive - inclusive description: >- Whether the line item amounts already include tax (`inclusive`) or tax is added on top (`exclusive`). Defaults to `exclusive`. example: exclusive line_items: type: array description: >- One or more items to calculate tax for. Each item must include a unique reference and the amount in the transaction currency. items: type: object required: - reference - amount properties: reference: type: string description: Your unique identifier for this line item. example: item_1 amount: type: string description: >- Item amount as a decimal string, excluding tax when `tax_behavior` is `exclusive`. example: '100.00' product_type: type: string enum: - good - service description: >- Whether the item is a physical `good` or a `service`. Affects which tax rules apply in many jurisdictions. example: service tax_code: type: string description: >- Quaderno tax code for the item (e.g. `ebook`, `saas`, `standard`). Overrides the product type when a more specific classification is available. example: saas required: - customer_address - line_items /contacts: get: summary: List contacts tags: - Contacts operationId: listContacts description: Lists contacts, paginated and sorted by creation date (newest first). parameters: - name: q in: query required: false description: >- Filters the contact list based on the contact's full name, email or tax id. Case-sensitive. schema: type: string - name: processor_id in: query required: false description: Filters the contact list based on its `processor_id`. schema: type: string responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/contact' post: summary: Create a contact tags: - Contacts operationId: createContact description: >- Creates a new contact, representing a customer or vendor who appears on invoices, credit notes, and expenses. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/contact' requestBody: content: application/json: schema: $ref: '#/components/schemas/contact' /contacts/{id}: get: summary: Retrieve a contact tags: - Contacts operationId: retrieveContact description: Retrieves the details of an existing contact. parameters: - name: id in: path description: ID of the desired contact. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/contact' put: summary: Update a contact tags: - Contacts operationId: updateContact description: Updates a contact. Any parameters not provided will be left unchanged. parameters: - name: id in: path description: ID of the contact to be updated. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/contact' requestBody: content: application/json: schema: $ref: '#/components/schemas/contact' delete: summary: Delete a contact tags: - Contacts operationId: deleteContact description: Permanently deletes a contact. This action cannot be undone. parameters: - name: id in: path description: ID of the contact to be deleted. required: true schema: type: string responses: '204': description: delete /credits: get: summary: List all credit notes tags: - Credits operationId: listCredits description: >- Lists all credit notes, paginated and sorted by creation date (newest first). Credit notes are used to cancel or partially refund an invoice. parameters: - name: q in: query required: false description: >- Filters a credit notes list based on the credit number, customer name or PO number. schema: type: string - name: date in: query required: false description: >- Filters a credit notes list based on the issue date. A date range must be entered. Allowed formats are `2019-01-01,2019-12-31` and `2019/01/01,2019/12/31`. schema: type: string - name: state in: query required: false schema: type: string enum: - outstanding - late - paid description: Filters a credit notes list based on the credit state. - name: processor_id in: query required: false description: Filters a credit notes list based on its `processor_id`. schema: type: string responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/credit' post: summary: Create a credit note tags: - Credits operationId: createCredit description: >- Creates a credit note against an existing invoice. The credit note offsets the invoice amount — fully or partially — and automatically records the refund. **Credit notes are immutable after creation** and cannot be updated or deleted. Use the void endpoint if a correction is needed. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/credit' requestBody: content: application/json: schema: type: object properties: invoice_id: type: integer description: The ID of the refunded invoice. example: 139331 payment_method: type: string enum: - credit_card - cash - wire_transfer - direct_debit - check - iou - paypal - other description: Payment method used to refund the credited amount. credited_amount: type: number description: >- Total amount to be credited, equal or lower than the total amount of the related invoice. Only works for refunds of invoices with one single item. When empty, defaults to the total amount of the related invoice. required: - invoice_id examples: basic: summary: Canceling out an invoice value: invoice_id: 139331 partial: summary: Partial credit example value: invoice_id: 139331 payment_method: credit_card credited_amount: 10.1 /credits/{id}: get: summary: Retrieve a credit note tags: - Credits operationId: retrieveCredit description: >- Retrieves the details of an existing credit note. You need only supply the unique identifier returned upon creation. parameters: - name: id in: path description: The ID of the desired credit. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/credit' put: summary: Update a credit note tags: - Credits operationId: updateCredit description: >- Updates an existing credit note. **Once finalized, credit notes are legally immutable** — tax law prohibits altering amounts, line items, or customer details. Only administrative fields (`tag_list`, `payment_details`, `notes`, `custom_metadata`) can still be modified. If a correction is needed, void the credit note and issue a new one. parameters: - name: id in: path description: The ID of the credit to be updated. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/credit' requestBody: content: application/json: schema: $ref: '#/components/schemas/final_document' /credits/{id}/payments: post: summary: Record a payment tags: - Credits operationId: recordCreditPayment description: >- Records a payment against a credit note. When the total payments reach the credit note amount, it is automatically marked as paid. parameters: - name: id in: path description: The ID of the credit note. required: true schema: type: string responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/payment' requestBody: content: application/json: schema: $ref: '#/components/schemas/payment' /credits/{id}/void: put: summary: Void a credit note tags: - Credits operationId: voidCredit description: >- Voids a credit note, effectively canceling it. Tax law prohibits deleting credit notes — voiding is the only way to reverse one. A `void_reason` is required for audit purposes. Voiding reopens the original invoice if it was closed by this credit note. parameters: - name: id in: path description: The ID of the credit to be voided. required: true schema: type: integer responses: '200': description: void content: application/json: schema: $ref: '#/components/schemas/credit' '422': description: void reason missing requestBody: content: application/json: schema: type: object properties: void_reason: type: string required: - void_reason /credits/{id}/deliver: get: summary: Deliver a credit tags: - Credits operationId: deliverCredit description: >- Sends the credit note to the customer via email using the account's configured template and language. The contact must have a valid email address. Delivery history is recorded and accessible via the `deliveries` field. parameters: - name: id in: path description: The ID of the desired credit. required: true schema: type: string responses: '200': description: deliver /expenses: get: summary: List all expenses tags: - Expenses operationId: listExpenses description: >- Lists all expenses, paginated and sorted by creation date (newest first). parameters: - name: q in: query required: false description: >- Filters an expenses list based on the expense number, customer name or PO number. schema: type: string - name: date in: query required: false description: >- Filters an expenses list based on the issue date. A date range must be entered. Allowed formats are `2019-01-01,2019-12-31` and `2019/01/01,2019/12/31`. schema: type: string - name: state in: query required: false description: >- Filters an expenses list based on the expense state: `outstanding`, `late` and `paid`. schema: type: string enum: - outstanding - late - paid - name: contact in: query required: false description: Filters an expenses list based on the customer ID. schema: type: integer responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/expense' post: summary: Create an expense tags: - Expenses operationId: createExpense description: Creates a new expense. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/expense' requestBody: content: application/json: schema: $ref: '#/components/schemas/expense' /expenses/{id}: get: summary: Retrieve an expense tags: - Expenses operationId: retrieveExpense description: Retrieves the details of an existing expense. parameters: - name: id in: path description: The ID of the desired expense. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/expense' put: summary: Update an expense tags: - Expenses operationId: updateExpense description: Updates an expense. parameters: - name: id in: path description: The ID of the expense to be updated. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/expense' requestBody: content: application/json: schema: $ref: '#/components/schemas/expense' delete: summary: Delete an expense tags: - Expenses operationId: deleteExpense description: Deletes an existing expense. parameters: - name: id in: path description: The ID of the expense to be deleted. required: true schema: type: string responses: '204': description: delete /invoices: get: summary: List all invoices tags: - Invoices operationId: listInvoices description: >- Lists all invoices, paginated and sorted by creation date (newest first). parameters: - name: q in: query required: false description: >- Filters an invoices list based on the invoice number, customer name or PO number. schema: type: string - name: date in: query required: false description: >- Filters an invoices list based on the issue date. A date range must be entered. Allowed formats are `2019-01-01,2019-12-31` and `2019/01/01,2019/12/31`. schema: type: string - name: state in: query required: false schema: type: string enum: - outstanding - late - uncollectible - paid description: Filters an invoices list based on the invoice state. - name: processor_id in: query required: false description: Filters an invoices list based on its `processor_id`. schema: type: string - name: contact in: query required: false description: Filters an invoices list based on the customer ID. schema: type: integer responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/invoice' post: summary: Create an invoice tags: - Invoices operationId: createInvoice description: >- Creates a new invoice. If a `payment_method` is provided, a payment for the full amount is automatically recorded and the invoice is immediately marked as paid. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/invoice' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/invoice' - type: object properties: payment_method: type: string enum: - credit_card - cash - wire_transfer - direct_debit - check - iou - paypal - offset - other description: >- If provided, a payment for the full invoice amount is automatically recorded using this method, marking the invoice as paid immediately upon creation. /invoices/{id}: get: summary: Retrieve an invoice tags: - Invoices operationId: retrieveInvoice description: >- Retrieves the details of an existing invoice. You need only supply the unique invoice identifier that was returned upon invoice creation. parameters: - name: id in: path description: The ID of the desired invoice. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/invoice' put: summary: Update an invoice tags: - Invoices operationId: updateInvoice description: >- Updates an existing invoice. **Once finalized, invoices are legally immutable** — tax law prohibits altering amounts, line items, dates, or customer details on issued invoices. Only administrative fields (`tag_list`, `payment_details`, `notes`, `custom_metadata`) can still be modified. If a correction is needed, void the invoice and issue a new one. parameters: - name: id in: path description: The ID of the invoice to be updated. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/invoice' requestBody: content: application/json: schema: $ref: '#/components/schemas/final_document' /invoices/{id}/mark_uncollectible: put: summary: Mark an invoice as uncollectible tags: - Invoices operationId: markInvoiceUncollectible description: >- Marks an invoice as uncollectible. This is useful for tracking invoices that you have determined will not be paid. parameters: - name: id in: path description: The ID of the desired invoice. required: true schema: type: string responses: '200': description: mark_uncollectible content: application/json: schema: $ref: '#/components/schemas/invoice' '422': description: invoice already uncollectible /invoices/{id}/void: put: summary: Void an invoice tags: - Invoices operationId: voidInvoice description: >- Voids an invoice by creating a credit note with the given reason. If the invoice is pending, it will be marked as paid via an offset payment. parameters: - name: id in: path description: The ID of the invoice to void. required: true schema: type: string responses: '200': description: void content: application/json: schema: $ref: '#/components/schemas/invoice' '422': description: void reason missing requestBody: content: application/json: schema: type: object properties: void_reason: type: string required: - void_reason /invoices/{id}/payments: post: summary: Record a payment tags: - Invoices operationId: recordInvoicePayment description: >- Records a payment against an invoice. When the total payments reach the invoice amount, the invoice is automatically marked as paid. parameters: - name: id in: path description: The ID of the invoice. required: true schema: type: string responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/payment' requestBody: content: application/json: schema: $ref: '#/components/schemas/payment' /invoices/{id}/deliver: get: summary: Deliver an invoice tags: - Invoices operationId: deliverInvoice description: >- Sends the invoice to the customer via email using the account's configured invoice template and language. The contact must have a valid email address. Delivery history is recorded and accessible via the `deliveries` field. parameters: - name: id in: path description: The ID of the desired invoice. required: true schema: type: string responses: '200': description: deliver /jurisdictions/{id}: get: summary: Retrieve a jurisdiction tags: - Jurisdictions operationId: retrieveTaxJurisdiction description: >- Retrieves a single tax jurisdiction by ID. Use this to look up the details of a jurisdiction before creating a registration. parameters: - name: id in: path description: ID of the jurisdiction to retrieve. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: type: object properties: id: type: number description: Unique identifier for the jurisdiction. name: type: string description: Human-readable name of the jurisdiction. example: Canada - British Columbia country: type: string description: Two-letter ISO 3166-1 country code. example: CA region: type: string nullable: true description: >- Two-letter region code (state, province, or territory). `null` for country-level jurisdictions. example: BC example: id: 94 name: Canada - British Columbia country: CA region: BC /jurisdictions: get: summary: List all jurisdictions tags: - Jurisdictions operationId: listTaxJurisdictions description: > Returns the list of all tax jurisdictions supported by Quaderno. A jurisdiction is a geographic area with its own tax rules — it can be a country, a state, a province, or a territory. Use the `country` and `region` filters to narrow results. To look up the jurisdiction ID needed to create a registration, filter by country and region code. Pass `region=none` to return only country-level jurisdictions (those with no region). parameters: - name: country in: query required: false example: CA description: >- Filter by country. Two-letter ISO 3166-1 country code. Case-sensitive. schema: type: string - name: region in: query required: false description: >- Filter by region (state, province, or territory code). Case-sensitive. Pass `none` to return only country-level jurisdictions. schema: type: string responses: '200': description: list content: application/json: schema: type: array items: type: object properties: id: type: number description: Unique identifier for the jurisdiction. name: type: string description: Human-readable name of the jurisdiction. example: Canada - British Columbia country: type: string description: Two-letter ISO 3166-1 country code. example: CA region: type: string nullable: true description: >- Two-letter region code. `null` for country-level jurisdictions. example: BC /ping: get: summary: /ping tags: - Tools operationId: ping responses: '200': description: status ok content: application/json: schema: type: object properties: status: type: string /items: get: summary: List products tags: - Products operationId: listProducts description: >- Lists all products, paginated and sorted by creation date (newest first). parameters: - name: q in: query required: false description: >- Filters a product list based on the product's name or code. Case-sensitive. schema: type: string responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/product' post: summary: Create a product tags: - Products operationId: createProduct description: >- Creates a new product, which could be used as line item on invoices, credit notes and expenses. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/product' requestBody: content: application/json: schema: $ref: '#/components/schemas/product' /items/{id}: get: summary: Retrieve a product tags: - Products operationId: retrieveProduct description: Retrieves the details of an existing product. parameters: - name: id in: path description: ID of the desired product. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/product' put: summary: Update a product tags: - Products operationId: updateProduct description: Updates a product. Any parameters not provided will be left unchanged. parameters: - name: id in: path description: ID of the product to be updated. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/product' requestBody: content: application/json: schema: $ref: '#/components/schemas/product' delete: summary: Delete a product tags: - Products operationId: deleteProduct description: Permanently deletes a product. This action cannot be undone. parameters: - name: id in: path description: ID of the product to be deleted. required: true schema: type: string responses: '204': description: delete /proformas: get: summary: List all proformas tags: - Proformas operationId: listProformas description: >- Lists all proformas, paginated and sorted by creation date (newest first). parameters: - name: q in: query required: false description: >- Filters a proformas list based on the proforma number, customer name or PO number. schema: type: string - name: date in: query required: false description: >- Filters a proformas list based on the issue date. A date range must be entered. Allowed formats are `2019-01-01,2019-12-31` and `2019/01/01,2019/12/31`. schema: type: string - name: state in: query required: false schema: type: string enum: - outstanding - accepted - declined - invoiced - late description: Filters a proformas list based on the proforma state. - name: contact in: query required: false description: Filters a proformas list based on the customer ID. schema: type: integer responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/proforma' post: summary: Create a proforma tags: - Proformas operationId: createProforma description: Creates a new proforma object. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/proforma' requestBody: content: application/json: schema: $ref: '#/components/schemas/proforma' /proformas/{id}: get: summary: Retrieve a proforma tags: - Proformas operationId: retrieveProforma description: Retrieves the details of an existing proforma. parameters: - name: id in: path description: The ID of the desired proforma. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/proforma' put: summary: Update a proforma tags: - Proformas operationId: updateProforma description: >- Updates an existing proforma. Accepted and invoiced proformas cannot be modified. parameters: - name: id in: path description: The ID of the proforma to be updated. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/proforma' '422': description: proforma cannot be updated requestBody: content: application/json: schema: $ref: '#/components/schemas/proforma' /proformas/{id}/accept: put: summary: Accept a proforma tags: - Proformas operationId: acceptProforma description: >- Marks a proforma as accepted by the customer. Only proformas in "outstanding" or "late" state can be accepted. parameters: - name: id in: path description: The ID of the proforma to accept. required: true schema: type: string responses: '200': description: accept content: application/json: schema: $ref: '#/components/schemas/proforma' '422': description: proforma cannot be accepted /proformas/{id}/decline: put: summary: Decline a proforma tags: - Proformas operationId: declineProforma description: >- Marks a proforma as declined by the customer. Only proformas in "outstanding" or "late" state can be declined. parameters: - name: id in: path description: The ID of the proforma to decline. required: true schema: type: string responses: '200': description: decline content: application/json: schema: $ref: '#/components/schemas/proforma' '422': description: proforma cannot be declined /proformas/{id}/revert: put: summary: Revert a proforma tags: - Proformas operationId: revertProforma description: >- Reverts a proforma back to "outstanding" from "accepted" or "declined". Invoiced proformas cannot be reverted. parameters: - name: id in: path description: The ID of the proforma to revert. required: true schema: type: string responses: '200': description: revert content: application/json: schema: $ref: '#/components/schemas/proforma' '422': description: proforma cannot be reverted /proformas/{id}/convert: put: summary: Convert a proforma into an invoice tags: - Proformas operationId: convertProforma description: >- Converts an accepted proforma into an invoice. The proforma state transitions to "invoiced" and a new invoice is returned. Only proformas in the "accepted" state can be converted. parameters: - name: id in: path description: The ID of the proforma to convert. required: true schema: type: string responses: '201': description: convert content: application/json: schema: $ref: '#/components/schemas/invoice' '422': description: proforma cannot be converted /proformas/{id}/deliver: get: summary: Deliver a proforma tags: - Proformas operationId: deliverProforma description: Delivers a proforma to your customer via email. parameters: - name: id in: path description: The ID of the desired proforma. required: true schema: type: string responses: '200': description: deliver /receipts: get: summary: List all receipts tags: - Receipts operationId: listReceipts description: >- Lists all receipts, paginated and sorted by creation date (newest first). All receipts are paid by definition. parameters: - name: q in: query required: false description: >- Filters an receipts list based on the receipt number, customer name or PO number. schema: type: string - name: date in: query required: false description: >- Filters an receipts list based on the issue date. A date range must be entered. Allowed formats are `2019-01-01,2019-12-31` and `2019/01/01,2019/12/31`. schema: type: string - name: processor_id in: query required: false description: Filters an receipts list based on its `processor_id`. schema: type: string - name: contact in: query required: false description: Filters an receipts list based on the customer ID. schema: type: integer responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/receipt' post: summary: Create a receipt tags: - Receipts operationId: createReceipt description: >- Creates a new receipt documenting a completed transaction. Unlike invoices, receipts are always paid — a `payment_method` is required. **Receipts are immutable after creation** and cannot be updated or deleted. Use the void endpoint if a correction is needed. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/receipt' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/receipt' - type: object properties: payment_method: type: string enum: - credit_card - cash - wire_transfer - direct_debit - check - iou - paypal - offset - other description: >- How the customer paid. Required — receipts document completed transactions and must always record the payment method used. required: - payment_method /receipts/{id}: get: summary: Retrieve an receipt tags: - Receipts operationId: retrieveReceipt description: Retrieves the details of an existing receipt. parameters: - name: id in: path description: The ID of the desired receipt. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/receipt' /receipts/{id}/void: put: summary: Void a receipt tags: - Receipts operationId: voidReceipt description: >- Voids a receipt by automatically issuing an offsetting credit note. Tax law prohibits deleting receipts — voiding is the only way to reverse a completed transaction. A `void_reason` is required for audit purposes. parameters: - name: id in: path description: The ID of the receipt to void. required: true schema: type: string responses: '200': description: void content: application/json: schema: $ref: '#/components/schemas/receipt' '422': description: void reason missing requestBody: content: application/json: schema: type: object properties: void_reason: type: string required: - void_reason /receipts/{id}/deliver: get: summary: Deliver an receipt tags: - Receipts operationId: deliverReceipt description: >- Sends the receipt to the customer via email using the account's configured invoice template and language. The contact must have a valid email address. Delivery history is recorded and accessible via the `deliveries` field. parameters: - name: id in: path description: The ID of the desired receipt. required: true schema: type: string responses: '200': description: deliver /recurring: get: summary: List all recurring tags: - Recurring Documents operationId: listRecurrings description: >- Lists all recurring, paginated and sorted by creation date (newest first). parameters: - name: q in: query required: false description: >- Filters a recurring list based on the recurring number, customer name or PO number. schema: type: string - name: date in: query required: false description: >- Filters a recurring list based on the issue date. A date range must be entered. Allowed formats are `2019-01-01,2019-12-31` and `2019/01/01,2019/12/31`. schema: type: string - name: state in: query required: false schema: type: string enum: - active - archived description: Filters a recurring list based on the recurring state. - name: contact in: query required: false description: Filters a recurring list based on the customer ID. schema: type: integer responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/recurring' post: summary: Create a recurring tags: - Recurring Documents operationId: createRecurring description: Creates a new recurring. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/recurring' requestBody: content: application/json: schema: $ref: '#/components/schemas/recurring' /recurring/{id}: get: summary: Retrieve a recurring tags: - Recurring Documents operationId: retrieveRecurring description: Retrieves the details of an existing recurring. parameters: - name: id in: path description: The ID of the desired recurring. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/recurring' put: summary: Update a recurring tags: - Recurring Documents operationId: updateRecurring description: Updates a recurring. parameters: - name: id in: path description: The ID of the recurring to be updated. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/recurring' requestBody: content: application/json: schema: $ref: '#/components/schemas/recurring' delete: summary: Delete a recurring tags: - Recurring Documents operationId: deleteRecurring description: Deletes an existing recurring. parameters: - name: id in: path description: The ID of the recurring to be deleted. required: true schema: type: string responses: '204': description: delete /registrations: get: summary: List registrations tags: - Registrations operationId: listRegistrations description: >- Returns a list of all your tax registrations. A registration represents your business's tax presence in a specific jurisdiction along with its local tax ID. responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/tax_id' post: summary: Create a registration tags: - Registrations operationId: createRegistration description: >- Creates a new tax registration, associating your business with a tax jurisdiction and its corresponding local tax ID. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/tax_id' requestBody: content: application/json: schema: type: object properties: jurisdiction_id: type: integer description: >- ID of the tax jurisdiction where your business is registered. example: 94 value: type: string description: >- The local tax ID issued by the jurisdiction (e.g. a VAT number). example: 123456789BW0001 valid_from: type: string required: false description: >- Date from which the registration is valid. Defaults to the beginning of the current year. example: '2023-01-01' valid_until: type: string required: false description: >- Expiration date of the registration. Omit or leave blank if the registration has no expiration. example: '' permanent_establishment: type: boolean description: >- Whether your business has a physical presence (office, warehouse, etc.) in the jurisdiction. default: false example: true import_scheme: type: boolean description: >- Whether the business is enrolled in the EU import scheme for foreign sellers of physical goods. default: false example: true required: - jurisdiction_id - value /registrations/{id}: get: summary: Retrieve a registration tags: - Registrations operationId: retrieveRegistration description: Retrieves the details of an existing registration. parameters: - name: id in: path description: ID of the registration. required: true schema: type: integer responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/tax_id' put: summary: Update a registration tags: - Registrations operationId: updateRegistration description: >- Updates an existing registration. Any parameters not provided will be left unchanged. parameters: - name: id in: path description: ID of the registration to update. required: true responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/tax_id' requestBody: content: application/json: schema: type: object properties: value: type: string required: false description: The local tax ID value. example: 123456789BW0001 valid_from: type: string required: false description: Date from which the registration is valid. example: '2023-01-01' valid_until: type: string required: false description: >- Expiration date of the registration, or blank if it has no expiration. example: '2024-12-31' permanent_establishment: type: boolean description: >- Whether your business has a physical presence in the jurisdiction. default: false example: true import_scheme: type: boolean description: >- Whether the business is enrolled in the EU import scheme for foreign sellers of physical goods. default: false example: true delete: summary: Delete a registration tags: - Registrations operationId: deleteRegistration description: Permanently deletes a registration. This action cannot be undone. parameters: - name: id in: path description: ID of the registration to delete. required: true schema: type: string responses: '204': description: delete /reporting/requests: get: summary: List all reporting requests tags: - Reporting operationId: listReportRequests description: Retrieves the list of reporting requests. responses: '200': description: list content: application/json: schema: type: array items: type: object properties: id: type: integer report_type: type: string enum: - tax_summary - invoices_list - credits_list description: The type of report. report_url: type: url nullable: true description: >- This will contain the download URL when `state` transitions to suceeded. state: type: string enum: - pending - suceeded - failed example: succeeded parameters: type: object description: Parameters specifying report details. properties: from_date: type: string example: '2022-10-10' description: Starting date of data to be included in the report. to_date: type: string example: '2022-11-11' description: Ending date of data to be included in the report. completed_at: type: integer description: >- Time at which the report was generated. Measured in seconds since the Unix epoch. example: 1632985500 created_at: type: integer description: >- Time at which the report was requested. Measured in seconds since the Unix epoch. example: 1632985500 post: summary: Requests a report tags: - Reporting operationId: createReportRequest description: >- Creates a new reporting request. The report file will be ready some minutes after creating a new request. parameters: [] responses: '201': description: create content: application/json: schema: type: object properties: id: type: integer report_type: type: string enum: - tax_summary - invoices_list - credits_list description: The type of report. report_url: type: url nullable: true description: >- This will contain the download URL when `state` transitions to suceeded. state: type: string enum: - pending - suceeded - failed example: pending parameters: type: object description: Parameters specifying report details. properties: from_date: type: string example: '2022-10-10' to_date: type: string example: '2022-11-11' completed_at: type: integer description: >- Time at which the report was generated. Measured in seconds since the Unix epoch. example: 1632985500 created_at: type: integer description: >- Time at which the report was requested. Measured in seconds since the Unix epoch. example: 1632985500 requestBody: content: application/json: schema: type: object properties: report_type: type: string enum: - tax_summary - invoices_list - credits_list description: The type of report. parameters: type: object description: Parameters specifying report details. properties: from_date: type: string example: '2022-10-10' description: Starting date of data to be included in the report. to_date: type: string example: '2022-11-11' description: Ending date of data to be included in the report. /reporting/requests/{id}: get: summary: Retrieve a reporting request tags: - Reporting operationId: retrieveReportRequest description: Retrieves updated info from the reporting request. parameters: - name: id in: path description: The ID of the reporting request to retrieve. example: 41 required: true schema: type: integer responses: '200': description: retrieve content: application/json: schema: type: object properties: id: type: integer report_type: type: string enum: - tax_summary - invoices_list - credits_list description: The type of report. report_url: type: url nullable: true description: >- This will contain the download URL when `state` transitions to suceeded. state: type: string enum: - pending - suceeded - failed example: pending parameters: type: object description: Parameters specifying report details. properties: from_date: type: string example: '2022-10-10' to_date: type: string example: '2022-11-11' completed_at: type: integer description: >- Time at which the report was generated. Measured in seconds since the Unix epoch. example: 1632985500 created_at: type: integer description: >- Time at which the report was requested. Measured in seconds since the Unix epoch. example: 1632985500 /tax_codes/{id}: get: summary: Retrieve a tax code tags: - Tax Codes operationId: retrieveTaxCode description: >- Retrieves a tax code, which classify goods and services for tax purposes. parameters: - name: id in: path required: true schema: type: string enum: - consulting - ebook - eservice - exempt - reduced - saas - standard description: The ID of the tax code to retrieve. example: eservice responses: '200': description: retrieve content: application/json: schema: type: object properties: id: type: string description: ID of the tax code. enum: - consulting - ebook - eservice - exempt - reduced - saas - standard example: eservice description: type: string description: Explanation of the tax code. example: >- Service that is delivered over the internet. It is essentially automated, involves minimal human intervention and in the absence of information technology does not have viability. name: type: string description: Full name of the tax code. example: Electronically supplied services /tax_codes: get: summary: List all tax codes tags: - Tax Codes operationId: listTaxCodes description: Retrieves the list of supported tax codes. responses: '200': description: list content: application/json: schema: type: array items: type: object properties: id: type: string description: ID of the tax code. example: eservice description: type: string description: Explanation of the tax code. example: >- Service that is delivered over the internet. It is essentially automated, involves minimal human intervention and in the absence of information technology does not have viability. name: type: string description: Full name of the tax code. example: Electronically supplied services example: - id: consulting description: >- Any consulting and professional service (e.g., lawyers, designers, engineers, tax advisors, etc.). name: Consulting - id: ebook description: An electronic book that is sold with unlimited use. name: eBook - id: eservice description: >- Service that is delivered over the internet. It is essentially automated, involves minimal human intervention and in the absence of information technology does not have viability. name: Electronically supplied services - id: exempt description: >- Any nontaxable good or service. No tax is applied for jurisdictions that impose a tax. name: Non-taxable - id: reduced description: Specific goods and services with a reduced tax rate. name: Reduced tax rate - id: saas description: >- Cloud services software delivered over the internet. The software is not customized for the specific buyer. Assumes no software is downloaded by the buyer. name: Software as a service (SaaS) - id: standard description: >- Any taxable good or service. For jurisdictions that impose a tax, the standard rate is applied. name: Generally taxable /transactions: post: summary: Create a transaction tags: - Transactions operationId: createTaxTransaction description: > Creates a new sale or refund tax transaction. Tax calculation is performed synchronously. The response will always have `status: taxed` — Quaderno calculates the applicable taxes inline and returns the final result in the same request. Use `transaction_type: "refund"` to record a refund. The `refund_of_processor_id` must reference the `processor_id` of the original sale. parameters: [] responses: '201': description: Refund created content: application/json: schema: $ref: '#/components/schemas/tax_transaction' '422': description: Validation error requestBody: content: application/json: schema: $ref: '#/components/schemas/tax_transaction_create' get: summary: List transactions tags: - Transactions operationId: listTaxTransactions description: >- Returns a paginated list of tax transactions for the account, ordered by date descending. parameters: - name: status in: query schema: type: string enum: - pending - taxed - errored - draft description: Filter by processing status. required: false - name: date_from in: query schema: type: string format: date description: Return transactions on or after this date. required: false - name: date_to in: query schema: type: string format: date description: Return transactions on or before this date. required: false - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 description: Number of transactions to return per page. required: false - name: page in: query schema: type: integer minimum: 1 description: Page number for pagination. required: false responses: '200': description: List of transactions content: application/json: schema: type: array items: $ref: '#/components/schemas/tax_transaction' /transactions/batches: post: summary: Create transactions in batch tags: - Transactions operationId: createTaxTransactionBatch description: > Creates multiple sale transactions in a single request. Use this endpoint to import historical transactions or sync large volumes of sales data efficiently. All amounts are treated as tax-inclusive — the tax is extracted from each item amount rather than added on top. This behavior is enforced automatically and cannot be overridden. **Batches only support sale transactions.** To record a refund, use `POST /transactions` with `transaction_type: "refund"`. A batch can contain up to **500 transactions**. If the limit is exceeded the entire request is rejected. Each transaction in the batch is validated before any are stored. If any transaction fails validation, the entire batch is rejected and no records are created. parameters: [] responses: '202': description: Batch accepted content: application/json: schema: type: object properties: accepted: type: integer description: Number of transactions successfully created. example: 2 transactions: type: array items: type: object properties: id: type: integer description: Quaderno transaction ID. example: 92732431 processor_id: type: string example: ch_1234567890 status: type: string example: pending '400': description: Validation error content: application/json: schema: type: object properties: errors: type: array description: One entry per invalid transaction. items: type: object properties: processor_id: type: string description: Identifies which transaction failed. example: transaction_0 errors: type: object description: Field-level validation errors. additionalProperties: type: array items: type: string requestBody: content: application/json: schema: type: object required: - batch properties: batch: type: object required: - transactions properties: transactions: type: array description: List of sale transactions to create. items: type: object required: - processor - processor_id - date - currency - customer - items properties: processor: type: string description: >- The payment processor that handled the transaction. example: stripe processor_id: type: string description: >- The transaction ID in the payment processor. Must be unique per processor. example: ch_1234567890 date: type: string format: date description: Date of the transaction. example: '2024-01-15' currency: type: string description: Three-letter ISO 4217 currency code. example: USD total: type: string description: >- Total transaction amount as a decimal string, tax-inclusive. example: '108.75' total_tax: type: string description: >- Total tax amount as a decimal string. When provided, Quaderno uses this value directly instead of recalculating. example: '8.75' customer: type: object required: - billing_address properties: tax_id: type: string nullable: true description: >- Customer's business tax ID (e.g. a VAT number). Triggers B2B exemption rules when valid. example: FR32123456789 billing_address: type: object required: - country properties: country: type: string description: Two-letter ISO 3166-1 country code. example: US postal_code: type: string nullable: true example: '94102' region: type: string nullable: true description: State, province, or region. example: CA city: type: string nullable: true example: San Francisco street_line_1: type: string nullable: true street_line_2: type: string nullable: true shipping_address: type: object nullable: true description: >- Required when the order contains physical goods. properties: country: type: string example: US postal_code: type: string nullable: true example: '10001' region: type: string nullable: true example: NY city: type: string nullable: true street_line_1: type: string nullable: true street_line_2: type: string nullable: true origin_address: type: object nullable: true description: >- Seller origin address. Defaults to the account address when omitted. properties: country: type: string example: ES postal_code: type: string nullable: true example: '08001' region: type: string nullable: true city: type: string nullable: true street_line_1: type: string nullable: true street_line_2: type: string nullable: true items: type: array items: type: object required: - amount properties: description: type: string description: Description of the product or service. example: Ruby Essentials sku: type: string nullable: true description: Stock keeping unit. example: SKU-001 quantity: type: number format: float description: Quantity of units. Defaults to 1. example: 1 amount: type: string description: >- Item total amount (tax-inclusive) as a decimal string. example: '108.75' product_type: type: string enum: - good - service description: >- Whether the item is a physical good or a service. example: service tax_code: type: string description: >- Quaderno tax code (e.g. `eservice`, `saas`, `standard`). example: eservice /transactions/{id}: parameters: - name: id in: path schema: type: integer description: Transaction ID. required: true get: summary: Retrieve a transaction tags: - Transactions operationId: getTaxTransaction description: Retrieves an existing tax transaction by its ID. responses: '200': description: Transaction found content: application/json: schema: $ref: '#/components/schemas/tax_transaction' '404': description: Transaction not found /transactions/{id}/reprocess: parameters: - name: id in: path schema: type: integer description: Transaction ID. required: true post: summary: Reprocess a transaction tags: - Transactions operationId: reprocessTaxTransaction description: > Triggers a new tax calculation for an existing transaction. Useful when a transaction is in `errored` status. Returns `202 Accepted` immediately. The transaction status is reset to `pending` and recalculated asynchronously. responses: '202': description: Reprocess accepted '409': description: Transaction cannot be reprocessed content: application/json: schema: type: object properties: error: type: string /webhooks: get: summary: List all webhooks tags: - Webhooks operationId: listWebhooks description: Lists all webhooks, sorted by creation date (newest first). responses: '200': description: list content: application/json: schema: type: array items: $ref: '#/components/schemas/webhook' post: summary: Create a webhook tags: - Webhooks operationId: createWebhook description: >- Creates a new webhook object. The `url` provided needs to respond with `200 OK` to `HEAD` requests in order to validate the callback endpoint. parameters: [] responses: '201': description: create content: application/json: schema: $ref: '#/components/schemas/webhook' requestBody: content: application/json: schema: $ref: '#/components/schemas/webhook' /webhooks/{id}: get: summary: Retrieve a webhook tags: - Webhooks operationId: retrieveWebhook description: Retrieves the details of an existing webhook. parameters: - name: id in: path description: The ID of the desired webhook. required: true schema: type: string responses: '200': description: retrieve content: application/json: schema: $ref: '#/components/schemas/webhook' put: summary: Update a webhook tags: - Webhooks operationId: updateWebhook description: Updates the specified webhook. parameters: - name: id in: path description: The ID of the webhook to be updated. required: true schema: type: integer responses: '200': description: update content: application/json: schema: $ref: '#/components/schemas/webhook' requestBody: content: application/json: schema: $ref: '#/components/schemas/webhook' delete: summary: Delete a webhook tags: - Webhooks operationId: deleteWebhook description: Deletes a webhook. This action cannot be undone. parameters: - name: id in: path description: The ID of the webhook to be deleted. required: true schema: type: string responses: '204': description: delete servers: - url: https://{account_url}.quadernoapp.com/api description: Production server (uses live data) variables: account_url: default: production description: Your Quaderno account subdomain - url: https://{account_url}.sandbox-quadernoapp.com/api description: Sandbox server (uses test data) variables: account_url: default: sandbox description: Your Quaderno Sandbox account subdomain components: schemas: calculation: type: object description: >- Result of a tax calculation request. Amounts are decimal strings with two decimal places. properties: subtotal: type: string description: >- Sum of all line item amounts before tax (tax-exclusive) or after tax extraction (tax-inclusive). example: '100.00' total_tax: type: string description: Total tax amount across all line items. example: '19.00' total: type: string description: >- Grand total (subtotal + total_tax for exclusive; same as subtotal for inclusive). example: '119.00' currency: type: string description: Three-letter ISO 4217 currency code. example: EUR tax_behavior: type: string enum: - exclusive - inclusive description: >- Whether the amounts are tax-exclusive (tax added on top) or tax-inclusive (tax extracted from amount). example: exclusive tax_context: type: object description: >- Tax determination context — describes the nature of the transaction and its tax treatment. properties: transaction_type: type: string enum: - domestic - interstate - export description: >- `domestic` when seller and buyer are in the same tax zone; `interstate` for cross-border sales within a union (e.g. EU); `export` for sales leaving the tax zone entirely. example: domestic supply_place: type: string enum: - seller - buyer description: >- The location that determines which jurisdiction's rules apply. `seller` for origin-based states; `buyer` for destination-based jurisdictions and digital services. example: buyer tax_status: type: string enum: - taxable - exempt - reverse_charged - not_subject description: >- `taxable` — standard tax applies. `exempt` — the product or customer is exempt. `reverse_charged` — B2B cross-border; buyer accounts for VAT. `not_subject` — no tax obligation exists for this product type in this jurisdiction. example: taxable line_items: type: array description: Per-line-item tax results, in the same order as the request. items: type: object properties: reference: type: string description: The line item identifier passed in the request. example: item_1 amount: type: string description: >- Base amount of the line item (before tax for exclusive; inclusive of tax for inclusive). example: '100.00' tax_amount: type: string description: Tax amount for this line item. example: '19.00' total_amount: type: string description: >- Total charged for this line item (amount + tax_amount for exclusive; same as amount for inclusive). example: '119.00' tax_breakdown: type: array description: >- Simplified tax breakdown for this line item. US multi-jurisdiction taxes are combined into a single entry. items: type: object properties: country: type: string description: >- Two-letter ISO 3166-1 country code of the taxing jurisdiction. example: DE state: type: string nullable: true description: State or province code, when applicable. example: TX tax_name: type: string nullable: true description: Name of the tax (e.g. "VAT", "Sales Tax", "GST"). example: VAT tax_rate: type: string nullable: true description: Tax rate as a decimal string (e.g. "0.19" for 19%). example: '0.19' taxable_amount: type: string description: The portion of the line item amount subject to this tax. example: '100.00' taxable_part: type: number nullable: true description: >- Percentage of the amount that is taxable, when partial taxability applies (e.g. 80.0 for 80%). example: 100 tax_amount: type: string description: Tax amount for this jurisdiction entry. example: '19.00' tax_breakdown: type: array description: >- Document-level tax breakdown aggregated by jurisdiction. Each entry represents a distinct tax across all line items. items: type: object properties: jurisdiction: type: object properties: id: type: integer nullable: true description: Quaderno jurisdiction ID. example: 42 country: type: string description: Two-letter ISO 3166-1 country code. example: DE state: type: string nullable: true description: State or province code. example: null level: type: string description: Jurisdiction level. example: country tax_name: type: string nullable: true description: Name of the tax. example: VAT tax_rate: type: string nullable: true description: Tax rate as a decimal string. example: '0.19' tax_amount: type: string description: Total tax amount for this jurisdiction. example: '19.00' taxable_amount: type: string description: Total taxable amount for this jurisdiction. example: '100.00' sourcing: type: string nullable: true description: Tax sourcing rule applied (`origin` or `destination`). example: destination tax_id_validation: type: object nullable: true description: >- Result of validating the `customer_tax_id` against the relevant tax authority. Only present when `customer_tax_id` was included in the request. properties: valid: type: boolean nullable: true description: >- `true` if the tax ID is registered and active; `false` if invalid; `null` if the registry was temporarily unavailable. tax_id: type: string description: The tax ID that was validated. example: FR32123456789 country: type: string description: Country of the validated tax ID. example: FR product: type: object description: >- Products describe the specific goods or services you offer to your customers. You can use them in your invoices and checkout links. properties: id: type: integer description: Unique identifier for the object. readOnly: true example: 92732431 code: type: string description: >- The product’s SKU (Stock Keeping Unit) describe specific product variations, taking into account any combination of: attributes, currency, and cost. example: 012345678901-MFN country: type: string nullable: true description: >- 2-letter [ISO country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). Required if `tax_based_on` is `country`. example: US created_at: type: integer readOnly: true description: >- Time at which the object was created. Measured in seconds since the Unix epoch. example: '1593260908' currency: type: string nullable: true description: >- Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217), in uppercase. Must be a supported currency in your payment processors. example: USD description: type: string nullable: true description: >- The product’s description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes. paypal_interval_duration: type: integer nullable: true description: Only for `subscriptions`. Number of times the charge should recur. example: 1 paypal_interval_frequency: type: integer nullable: true description: >- Only for PayPal `subscriptions`. The number of intervals between subscription billings. paypal_interval_unit: type: string enum: - daily - weekly - monthly - yearly default: monthly description: Only for PayPal `subscriptions`. Specifies billing frequency. example: monthly kind: type: string enum: - one_off - subscription default: one_off description: 'The type of transaction: one-off purchase or subscription.' name: type: string description: The product’s name, meant to be displayable to the customer. example: Ruby Essentials product_type: type: string enum: - good - service default: service description: >- The type of the product. The product is either a tangible `good` or a `service`. stripe_plan_id: type: string nullable: true description: >- Only for Stripe `subscriptions`. ID of the Stripe price related to the subscription. example: price_1GtYUvKYlo3Dy5yXgrQS tax_based_on: type: string enum: - customer_country - country default: customer_country description: >- How taxes are going to be calculated: based on the customer country or a particular country. tax_class: type: string enum: - consulting - eservice - ebook - saas - standard - reduced default: eservice description: The tax class that applies to the product. tax_type: type: string enum: - excluded - included default: included description: Specify if taxes are included or excluded in the `unit_cost`. unit_cost: type: string description: The unit amount to be charged example: '9.99' url: type: string format: uri description: URI of the object readOnly: true example: https://quadernoapp.com/api/products/92732431 stock: type: string nullable: true description: The stock of the physical product. example: '10' required: - id - code - description - name - product_type - unit_cost - stock - tax_class - kind - tax_type - tax_based_on contact: type: object description: >- Any customer or vendor who appears on your invoices, credit notes, and expenses. properties: id: type: integer description: Unique identifier for the object. readOnly: true example: 92732431 city: type: string nullable: true description: City/District/Suburb/Town/Village. example: Pasadena contact_person: type: string nullable: true description: If the contact is a `company`, this is its contact person. country: type: string description: >- 2-letter [ISO country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). example: US created_at: type: integer readOnly: true description: >- Time at which the object was created. Measured in seconds since the Unix epoch. example: 1648037653 department: type: string nullable: true description: If the contact is a `company`, this is the deparment. discount: oneOf: - type: number format: float - type: 'null' description: Default discount for this contact. example: 0 email: type: string format: email nullable: true description: The contact's email address example: leonard@gmail.com first_name: type: string description: The contact's first name. Only if the contact is a `person`. example: Leonard kind: type: string enum: - company - person default: company description: The type of contact. example: person language: type: string description: >- The contact's preferred language. 2-letter [ISO language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). Should be included in the account's translations list. example: EN last_name: type: string nullable: true description: The contact's last name. Only if the contact is a `person`. example: Hofstadter notes: type: string nullable: true description: Internal notes about the contact. example: Some private notes about the contact. phone_1: type: string nullable: true description: The contact's phone number. example: 202-555-0104 postal_code: type: string nullable: true description: ZIP or postal code. example: '91104' processor: type: string nullable: true description: >- The external platform where the contact was imported from, if applicable. example: stripe processor_id: type: string nullable: true description: The ID the `payment_processor` assigned to the contact. example: cus_999999999999 permalink: type: string format: uri description: >- The URL for the hosted billing area, where customers can download their invoices and update their billing details. readOnly: true example: https://quadernoapp.com/billing/123345abcdef67890 region: type: string nullable: true description: State/Province/Region. example: CA street_line_1: type: string nullable: true description: Address line 1 (Street address/PO Box). example: 2311 North Los Robles Av. street_line_2: type: string nullable: true description: Address line 2 (Apartment/Suite/Unit/Building). example: Apartment C tax_id: type: string nullable: true description: >- The contact's tax identification number. Quaderno can validate EU VAT numbers, ABN, and NZBN. tax_status: type: string enum: - taxable - exempt - reverse description: Specifies the tax status of the contact. default: taxable web: type: string nullable: true format: uri description: The contact's website example: https://theelevatorisbroken.com url: type: string format: uri description: URI of the object readOnly: true example: https://quadernoapp.com/api/contacts/92732431 required: - first_name tax_id: type: object description: A tax ID identifies a business in a certain tax juristiction. properties: id: type: number description: Unique identifier for the object. example: 23546 import_scheme: type: boolean description: >- Whether the business is registered or not in the EU import scheme for foreign sellers of physical goods. default: false example: true jurisdiction: type: object description: Tax jurisdiction where the tax ID is registered. properties: id: type: number description: The ID of the tax jurisdiction. example: 94 name: type: string description: The name of the tax jurisdiction. example: Canada - British Columbia country: type: string description: Tax jurisdiction's country. 2-letter ISO 3166-1 code example: Canada - British Columbia region: type: string nullable: true description: Tax jurisdiction's region, if any. 2-letter ISO 3166-1 code example: BC permanent_establishment: type: boolean description: >- Whether your business has physical presence (office, warehouse, etc) in the given jurisdiction. default: false example: true state: type: string enum: - verified - unverified - unavailable description: The verification status of the tax ID in the related tax agency. valid_from: type: string description: The tax ID's validity date. Defaults to the beginning of the year. example: '2023-01-01' valid_until: type: string nullable: true description: >- The tax ID's expiration date, or null if the tax ID has no expiration date. example: '2024-12-31' value: type: string description: Value of the tax ID. For instance, a VAT number. example: 123456789BW0001 created_at: type: integer description: >- Time at which the object was created. Measured in seconds since the Unix epoch. example: 1681199310 evidence: type: object description: >- Evidence are proofs of customers' location that must be stored to comply with tax rules. properties: id: type: integer description: Unique identifier for the object. readOnly: true example: 92732431 additional_evidence: type: string nullable: true description: >- Additional evidence used to proof the customer's location. Required if there's a `additional_evidence_country'. example: Phone bill additional_evidence_country: type: string nullable: true description: 2-letter ISO 3166-1 code. example: DE bank_country: type: string nullable: true description: 2-letter ISO 3166-1 code. example: DE billing_country: type: string nullable: true description: 2-letter ISO 3166-1 code. example: DE created_at: type: integer readOnly: true description: >- Time at which the object was created. Measured in seconds since the Unix epoch. example: '1593260908' document_id: type: integer description: Unique identifier for the related invoice. example: 43123 ip_address: type: string nullable: true description: The customer's IP address example: 127.0.0.1 ip_country: type: string nullable: true readOnly: true description: 2-letter ISO 3166-1 code. example: DE notes: type: string nullable: true description: Internal notes about the evidence. example: Some private notes about the evidence. state: type: string enum: - unsettled - conflicting - confirmed default: unsettled description: State of the evidence url: type: string format: uri description: URI of the object readOnly: true example: https://quadernoapp.com/api/evidence/92732431 required: - document_id account: type: object description: Represents a Custom Quaderno Connect account with all its properties. properties: id: type: integer description: Unique identifier for the account. readOnly: true business_name: type: string description: Legal or trade name of the business. created_at: type: integer description: Unix timestamp when the account was created. readOnly: true currency: type: string description: >- Three-letter ISO 4217 currency code for invoicing and tax calculations. default_product_type: type: string enum: - good - service description: >- Fallback product type for documents and tax calculations. Defaults to "service". nullable: true default_tax_code: type: string enum: - eservice - ebook - saas - consulting - standard - reduced - retention description: >- Fallback tax code for items and tax calculations. Defaults to "eservice". nullable: true email: type: string description: Primary contact email for account notifications. state: type: string description: 'Account status. Values: "active", "inactive".' subdomain: type: string description: Unique identifier used in URLs and API authentication. readOnly: true web: type: string description: Business website URL. registration_number: type: string description: >- Official government-issued number that identifies the business entity (e.g., EIN in the US, SIREN in France, W-IdNr. in Germany, ABN in Australia). nullable: true authentication: type: object description: OAuth 2.0 credentials to act on behalf of the account. readOnly: true properties: access_token: type: string example: bDFVtZRvVK9vg_H9RJFD7Oq6Oi_NMzDMiw_xxx description: Bearer token for API authentication. Expires after 25 days. token_type: type: string example: Bearer description: Token type, always "Bearer". account_create: type: object description: Request body for creating a new Custom Quaderno Connect account. properties: business_name: type: string description: Legal or trade name of the business. country: type: string description: >- Two-letter ISO 3166-1 alpha-2 country code. Cannot be changed after creation. currency: type: string description: >- Three-letter ISO 4217 currency code. Defaults to the country's official currency. nullable: true default_product_type: type: string enum: - good - service description: >- Fallback product type for documents and tax calculations. Defaults to "service". nullable: true default_tax_code: type: string enum: - eservice - ebook - saas - consulting - standard - reduced - retention description: >- Fallback tax code for items and tax calculations. Defaults to "eservice". nullable: true email: type: string description: Primary contact email for account notifications. local_tax_id: type: string description: >- Tax ID that registers the account for tax collection in the country. Cannot be changed after creation. nullable: true postal_code: type: string description: >- ZIP or postal code of the business location. Cannot be changed after creation. nullable: true web: type: string description: Business website URL. nullable: true registration_number: type: string description: >- Official government-issued number that identifies the business entity (e.g., EIN in the US, SIREN in France, W-IdNr. in Germany, ABN in Australia). nullable: true required: - business_name - country - email account_update: type: object description: Request body for updating an existing Custom Quaderno Connect account. properties: business_name: type: string description: Legal or trade name of the business. default_product_type: type: string enum: - good - service description: >- Fallback product type for documents and tax calculations. Defaults to "service". nullable: true default_tax_code: type: string enum: - eservice - ebook - saas - consulting - standard - reduced - retention description: >- Fallback tax code for items and tax calculations. Defaults to "eservice". nullable: true email: type: string description: Primary contact email for account notifications. web: type: string description: Business website URL. registration_number: type: string description: >- Official government-issued number that identifies the business entity (e.g., EIN in the US, SIREN in France, W-IdNr. in Germany, ABN in Australia). tax_transaction: type: object description: >- A tax transaction records a sale or refund for tax reporting and compliance purposes. properties: id: type: integer readOnly: true description: Unique identifier for the object. example: 92732431 processor: type: string description: The payment processor that handled this transaction. example: stripe processor_id: type: string description: >- The transaction ID in the payment processor. Must be unique per processor and transaction type. example: ch_1234567890 currency: type: string description: >- Three-letter [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) in uppercase. example: USD transaction_type: type: string enum: - sale - refund description: Whether this is a sale or a refund. status: type: string enum: - pending - taxed - errored - draft readOnly: true description: >- Processing status. `pending` means tax calculation is queued; `taxed` means successfully calculated; `errored` means the calculation failed. supply_type: type: string enum: - domestic - interstate - export readOnly: true nullable: true description: >- Supply type determined by Quaderno based on the origin and customer addresses. date: type: string format: date description: Date of the transaction. example: '2024-01-15' total: type: string description: Total transaction amount as a decimal string. Tax-inclusive. example: '100.00' customer: type: object description: Customer location and identification data used for tax calculation. properties: billing_address: type: object description: Customer billing address. properties: country: type: string description: >- 2-letter [ISO country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). example: US postal_code: type: string nullable: true example: '94102' region: type: string nullable: true description: State, province, or region. example: CA city: type: string nullable: true example: San Francisco street_line_1: type: string nullable: true street_line_2: type: string nullable: true shipping_address: type: object nullable: true description: >- Customer shipping address. Only present when the order contains physical goods. properties: country: type: string example: US postal_code: type: string nullable: true example: '10001' region: type: string nullable: true example: NY city: type: string nullable: true example: New York street_line_1: type: string nullable: true street_line_2: type: string nullable: true tax_id: type: string nullable: true description: Customer's tax identification number (VAT number, EIN, etc.). items: type: array items: type: object properties: description: type: string description: Description of the product or service. example: Ruby Essentials sku: type: string nullable: true description: Stock keeping unit. example: SKU-001 quantity: type: number format: float description: Quantity of units. example: 1 amount: type: string description: Item total amount as a decimal string. Tax-inclusive. example: '50.00' product_type: type: string enum: - good - service description: Whether this item is a physical good or a service. tax_code: type: string description: Tax code used for tax calculation. example: eservice required: - description - quantity - amount - product_type tax_breakdown: type: array readOnly: true description: Tax breakdown by jurisdiction. Empty while status is `pending`. items: type: object properties: jurisdiction_name: type: string description: Name of the tax jurisdiction. example: California jurisdiction_level: type: string description: Level of the jurisdiction (country, state, county, city). example: state jurisdiction_currency: type: string description: Currency of the jurisdiction. example: USD tax_type: type: string description: Type of tax applied. example: sales_tax tax_status: type: string description: Tax applicability status. example: taxable taxable_amount: type: string description: Amount subject to this tax, as a decimal string. example: '100.00' tax_rate: type: number format: float description: Tax rate as a decimal. example: 0.0875 tax_amount: type: string description: Tax amount collected, as a decimal string. example: '8.75' exchange_rate: type: object nullable: true readOnly: true description: >- Exchange rate applied when the transaction currency differs from the account base currency. `null` when currencies match. properties: from_currency: type: string example: EUR to_currency: type: string example: USD rate: type: number format: float example: 1.1 rate_source: type: string description: Source of the exchange rate (e.g. ecb, hmrc). example: ecb rate_date: type: string format: date example: '2024-01-15' discrepancy: type: object nullable: true readOnly: true description: >- Discrepancy between the tax declared in the transaction and the tax calculated by Quaderno. `null` when there is no discrepancy. properties: amount: type: string description: Discrepancy amount as a decimal string. example: '0.01' currency: type: string example: USD formatted_amount: type: string example: $0.01 tax_transaction_create: type: object description: Request body for creating a tax transaction. properties: transaction_type: type: string enum: - sale - refund default: sale description: Whether this is a sale or a refund. processor: type: string description: The payment processor that handled this transaction. example: stripe processor_id: type: string description: >- The transaction ID in the payment processor. Must be unique per processor and transaction type. example: ch_1234567890 refund_of_processor_id: type: string nullable: true description: >- The `processor_id` of the original sale. Required when `transaction_type` is `refund`. example: ch_0987654321 date: type: string format: date description: Date of the transaction. Defaults to today. example: '2024-01-15' currency: type: string description: >- Three-letter [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) in uppercase. example: USD customer: type: object description: Customer location and identification data. properties: tax_id: type: string nullable: true description: Customer's tax identification number. billing_address: type: object description: Customer billing address. Required. properties: country: type: string description: >- 2-letter [ISO country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). example: US postal_code: type: string nullable: true description: Required for US, CA, and IN. example: '94102' region: type: string nullable: true description: State, province, or region. Required for AE. example: CA city: type: string nullable: true example: San Francisco street_line_1: type: string nullable: true street_line_2: type: string nullable: true required: - country shipping_address: type: object nullable: true description: Customer shipping address. Required for physical goods. properties: country: type: string example: US postal_code: type: string nullable: true example: '10001' region: type: string nullable: true example: NY city: type: string nullable: true street_line_1: type: string nullable: true street_line_2: type: string nullable: true required: - billing_address origin_address: type: object nullable: true description: Origin address for the transaction. Defaults to the account address. properties: country: type: string example: ES postal_code: type: string nullable: true example: '08001' region: type: string nullable: true example: Barcelona city: type: string nullable: true example: Barcelona street_line_1: type: string nullable: true street_line_2: type: string nullable: true items: type: array description: Line items in the transaction. items: type: object properties: description: type: string description: Description of the product or service. example: Ruby Essentials sku: type: string nullable: true description: Stock keeping unit. example: SKU-001 quantity: type: number format: float default: 1 example: 1 amount: type: string description: >- Item total amount (tax-inclusive). Provide as a decimal string. example: '50.00' product_type: type: string enum: - good - service default: service tax_code: type: string description: Tax code for the item (e.g. eservice, saas, ebook, standard). example: eservice required: - amount required: - processor - processor_id - date - currency - customer - items transaction_item: type: object description: A transaction item represents the concept being sold or refunded. properties: id: type: integer description: Unique identifier for the object. readOnly: true example: 92732431 product_code: type: string description: >- Code of an existing product. If present, you don't need to set the description. example: 012345678901-MFN created_at: type: integer readOnly: true description: >- Time at which the object was created. Measured in seconds since the Unix epoch. example: '1593260908' description: type: string description: >- Concept being sold or refunded. Meant to be displayable to the customer. quantity: type: number format: float nullable: true description: Quantity of units for the transaction item. Defaults to 1. example: 10 discount_rate: type: number format: float nullable: true description: >- This represents the discount percent out of 100 included in the amount, if applicable. example: 10 amount: type: number format: float description: >- Total amount of the transaction item. This should always be equal to the amount charged after discounts and taxes. example: 10 tax: type: object $ref: '#/components/schemas/transaction_tax' description: >- The tax details applied to the transaction item. Responses from the tax calculation endpoint are valid input. required: - amount transaction_tax: type: object description: Represents a tax calculation on a transaction item. properties: name: type: string nullable: true description: Name of the tax. example: Sales tax rate: type: number format: float description: Tax rate applied. example: 8.875 taxable_part: type: number nullable: true format: float description: >- Percentage of the subtotal used for calculating the tax amount. It's usually 100% but there are a few exceptions. For example, in Texas the taxable base is 80% for SaaS products. example: 100 country: type: string description: Country used for the tax calculation. example: US region: type: string nullable: true description: Region used for the tax calculation. example: NY tax_code: type: string nullable: true enum: - consulting - eservice - ebook - saas - standard - reduced description: >- The transaction's tax code used for calculating the tax rate. When not specified, it uses the account's default tax code. example: eservice additional_name: type: string nullable: true description: >- Only for jurisdictions that need to apply two tax rates (e.g. some Canadian provinces). additional_rate: type: number format: float nullable: true description: >- Only for jurisdictions that need to apply two tax rates (e.g. some Canadian provinces). additional_taxable_part: type: number format: float nullable: true description: >- Only for jurisdictions that need to apply two tax rates (e.g. some Canadian provinces). import: type: boolean nullable: true description: Whether the product is considered an import sale or not. required: - rate - country - tax_code transaction: type: object description: A transaction logs a new sale or refund in Quaderno. properties: id: type: integer description: Unique identifier for the object. readOnly: true example: 92732431 type: type: string enum: - sale - refund default: sale description: The transaction’s type. currency: type: string nullable: true description: >- Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217), in uppercase. Defaults to the account’s default currency. example: USD custom_metadata: type: hash nullable: true description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. You can have up to 20 keys, with key names up to 40 characters long and values up to 500 characters long. example: 'anything_you_want: extra info' customer: type: object $ref: '#/components/schemas/contact' description: >- The data of the customer who paid the transaction. You can reference an existing contact by its id, or pass the json object to create a new contact. created_at: type: integer readOnly: true description: >- Time at which the object was created. Measured in seconds since the Unix epoch. example: '1593260908' date: type: string format: date description: The transaction’s date. Defaults to today. items: type: array items: type: object $ref: '#/components/schemas/transaction_item' description: The list of individual items that make up the transaction. shipping_address: type: object description: >- The mailing address to where the order will be shipped. Use it if the order contains physical goods. properties: street_line_1: type: string street_line_2: type: string city: type: string country: type: string region: type: string postal_code: type: string evidence: type: object $ref: '#/components/schemas/evidence' description: Evidence of the customer’s location. **Highly recommended**. payment: type: object description: Detailed information about the transaction payment. properties: method: type: string enum: - credit_card - cash - wire_transfer - direct_debit - check - iou - paypal - other default: other description: The payment method used to pay the transaction. processor: type: string description: >- The name of the payment processor used to take the payment. E.g. stripe, paypal… processor_id: type: string description: The ID of the transaction in the payment processor. processor: type: string nullable: true description: >- The name of the platform that processed the transaction. E.g. shopify, woocommerce or any user agent you may want to use to identify yourself… **Recommended** example: my_platform_user_agent processor_id: type: string nullable: true description: >- The ID of the transaction in the processor. Use the same ID to link sales and refunds for the same operation. **Recommended** example: my_internal_request_id processor_fee_cents: type: integer nullable: true description: Processor total fee, in cents. example: 99 exchange_rate: type: number format: float nullable: true description: >- The rate used for currency conversion when the transaction currency differs from the account base currency. If omitted, the default ECB reference exchange rate for the transaction date is applied. example: 0.23345 po_number: type: string nullable: true description: The number of the related order. **Recommended**. example: po_xxxxxxxx notes: type: string nullable: true description: Optional notes attached to the transaction. example: A note. tags: type: string nullable: true description: >- Tags attached to the transaction, formatted as a string of comma-separated values. Tags are additional short descriptors, commonly used for filtering and searching. Each individual tag is limited to 40 characters in length. example: tagA, tagB required: - items - payment tax_rate: type: object description: >- A tax calculation, based on your tax settings and the customer's location. properties: name: type: string nullable: true description: Name of the tax. example: Sales tax rate: type: number format: float description: Tax rate applied. example: 8.875 taxable_part: type: number nullable: true format: float description: >- Percentage of the subtotal used for calculating the tax amount. It's usually 100% but there are a few exceptions. For example, in Texas the taxable base is 80% for SaaS products. example: 100 country: type: string description: Country used for the tax calculation. example: US region: type: string nullable: true description: Region used for the tax calculation. example: NY county: type: string nullable: true description: Tax county. Only for US sales tax. example: NEW YORK city: type: string nullable: true description: City used for the tax calculation. example: NEW YORK tax_code: type: string description: The transaction's tax code used for calculating the tax rate. example: eservice tax_behavior: type: string description: >- Whether the price was considered inclusive of taxes or exclusive of taxes. example: eservice tax_amount: type: number nullable: true description: The tax amount. example: 100 subtotal: type: number nullable: true description: Price before taxes. example: 100 total_amount: type: number nullable: true description: Total price, including taxes. example: 100 status: type: string description: Tax calculation status. enum: - taxable - non_taxable - not_registered - reverse_charge example: not_registered notes: type: string nullable: true deprecated: true description: >- In old API versions, this field specified special status like reverse-charge. Deprecated in favor of `status` field. example: Tax amount subject to reverse charge. notice: type: string nullable: true description: Help message complementing the tax calculation `status`. example: >- You aren't registered for tax collection in United States - New York. If you need to collect taxes there, please add the tax jurisdiction to your Quaderno account. additional_name: type: string nullable: true description: >- Only for jurisdictions that need to apply two tax rates (e.g. some Canadian provinces). additional_rate: type: number format: float nullable: true description: >- Only for jurisdictions that need to apply two tax rates (e.g. some Canadian provinces). additional_taxable_part: type: number format: float nullable: true description: >- Only for jurisdictions that need to apply two tax rates (e.g. some Canadian provinces). additional_tax_amount: type: number format: float nullable: true description: >- Only for jurisdictions that need to apply two tax rates (e.g. some Canadian provinces). invoice: type: object description: >- Invoices are formal payment requests documenting amounts owed by customers for goods or services. Unlike receipts, invoices typically include payment terms and may remain unpaid for a period. properties: id: type: integer description: Unique identifier for the invoice. readOnly: true example: 92732431 created_at: type: integer description: >- Timestamp when the invoice was created. Measured in seconds since the Unix epoch. readOnly: true example: 1593260908 number: type: string description: >- Unique, sequential number identifying this invoice. Invoice numbers must be sequential without gaps or duplicates to comply with legal requirements. Automatically generated if not provided. example: '00001' issue_date: type: string format: date description: >- Date the invoice was issued. May differ from the actual delivery or service date. example: '2020-06-27' related_document: type: object readOnly: true description: >- Reference to the source document that generated this invoice. Can be an Estimate (converted to invoice), a Recurring invoice (for recurring payments), or a Receipt (upgraded to full invoice). properties: id: type: integer description: Unique identifier for the related document. readOnly: true example: 92732430 type: type: string description: >- Type of the related document: "Estimate", "Recurring", or "Receipt". readOnly: true example: Recurring po_number: type: string nullable: true description: Customer's purchase order number for reference and tracking. example: '999' due_date: type: string format: date nullable: true description: >- Payment due date. Defines when payment is expected and affects the invoice state (outstanding, late, etc.). example: '2020-07-27' currency: type: string description: >- Three-letter [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) in uppercase. example: USD exchange_rate: type: number format: float nullable: true description: >- Exchange rate applied when converting from transaction currency to account base currency. If omitted, the ECB (European Central Bank) reference rate for the issue date is automatically applied. example: 0.680309 tag_list: type: array items: type: string nullable: true description: >- Array of tags for categorizing and filtering invoices. Useful for organizing by product line, sales channel, or custom categories. example: consulting, premium payment_details: type: string nullable: true description: >- Additional information about accepted payment methods, displayed to the customer. notes: type: string nullable: true description: >- Internal notes or additional information about this invoice. Not typically shown to customers. contact: anyOf: - type: object $ref: '#/components/schemas/contact' - type: object properties: id: type: integer full_name: type: string description: >- Customer being billed. Can reference an existing contact by ID or include full contact details. attachment: type: object $ref: '#/components/schemas/attachment' country: type: string readOnly: true description: >- Customer's billing country as a 2-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). Used for tax calculations. example: US postal_code: type: string readOnly: true nullable: true description: >- Customer's billing postal code or ZIP code. Used for tax calculations in some jurisdictions. example: '91104' region: type: string readOnly: true nullable: true description: >- Customer's billing state, province, or region. Important for calculating state/provincial taxes. example: CA city: type: string readOnly: true nullable: true description: Customer's billing city. example: Pasadena street_line_1: type: string nullable: true description: First line of customer's billing address (street address or PO Box). example: 2311 North Los Robles Av. street_line_2: type: string nullable: true description: >- Second line of customer's billing address (apartment, suite, unit, or building number). example: Apartment C tax_id: type: string nullable: true description: >- Customer's tax identification number (VAT number, EIN, etc.). Important for B2B transactions and tax exemptions. subject: type: string nullable: true description: >- Brief summary or title describing what this invoice is for. Displayed prominently on the document. deliveries: type: array nullable: true readOnly: true items: type: object $ref: '#/components/schemas/envelope' description: >- Delivery history showing when and how this invoice was sent to the customer (email, etc.). items: type: array items: type: object $ref: '#/components/schemas/document_item' description: >- Line items included in this invoice (products, services, fees, etc.). Maximum 200 items per request; use update requests to add more. Total limit: 1000 items per invoice. taxes: type: array readOnly: true items: type: object $ref: '#/components/schemas/document_tax' description: >- Calculated tax breakdown showing each applicable tax (VAT, sales tax, etc.) with rates and amounts. payments: type: array readOnly: true items: type: object $ref: '#/components/schemas/payment' description: >- Payment records associated with this invoice, showing partial or full payments received. evidence: type: object $ref: '#/components/schemas/evidence' description: >- Location evidence (IP address, billing country, etc.) used to determine applicable tax rates and jurisdictions. payment_processor: type: string nullable: true description: >- Name of the payment processor that handled this transaction (e.g., "stripe", "paypal", "braintree"). example: stripe payment_processor_id: type: string nullable: true description: >- Transaction ID from the payment processor. Used to link this invoice to the original payment gateway transaction. example: ch_999999999999 processor_fee_cents: type: integer nullable: true description: Payment processing fee charged by the payment processor, in cents. example: 99 custom_metadata: type: object nullable: true description: >- Custom key-value pairs for storing additional structured data. Useful for integrations and storing application-specific information. subtotal_cents: type: integer readOnly: true description: >- Sum of all line items before discounts and taxes are applied, in cents. example: 9375 discount_cents: type: integer readOnly: true description: Total discount amount applied to this invoice, in cents. example: 0 total_cents: type: integer readOnly: true description: Final amount due after applying discounts and taxes, in cents. example: 9375 state: type: string enum: - outstanding - late - uncollectible - paid - refunded - archived default: outstanding readOnly: true description: >- Current payment status. Can be: "outstanding" (unpaid, not overdue), "late" (overdue), "uncollectible" (marked as bad debt), "paid" (fully paid), "refunded" (payment reversed), or "archived" (removed from active invoices). alerts: type: array readOnly: true items: type: object $ref: '#/components/schemas/document_alert' description: >- Important notifications or warnings about this invoice (e.g., validation issues, tax calculation warnings). permalink: type: string format: uri description: Public URL where customers can view and pay this invoice online. readOnly: true example: https://quadernoapp.com/invoice/123345abcdef67890 pdf: type: string format: uri description: Direct download URL for the PDF version of this invoice. readOnly: true example: https://quadernoapp.com/invoice/123345abcdef67890.pdf url: type: string format: uri description: API endpoint URL for this invoice resource. readOnly: true example: https://quadernoapp.com/api/invoice/92732431 required: - contact - items receipt: type: object description: >- Receipts are simplified invoices that document payment for goods or services. They serve as proof of transaction and typically contain less detail than full invoices. **All receipts are paid by definition** — unlike invoices, a receipt always represents a completed transaction. properties: id: type: integer description: Unique identifier for the receipt. readOnly: true example: 92732431 created_at: type: integer description: >- Timestamp when the receipt was created. Measured in seconds since the Unix epoch. readOnly: true example: 1593260908 number: type: string description: >- Unique, sequential number identifying this receipt. Receipt numbers must be sequential without gaps or duplicates to comply with legal requirements. Automatically generated if not provided. example: '00001' issue_date: type: string format: date description: >- Date the receipt was issued. May differ from the actual transaction date. example: '2020-06-27' po_number: type: string nullable: true description: Customer's purchase order number for reference and tracking. example: '999' due_date: type: string format: date nullable: true description: >- Payment due date. For receipts this is typically the same as the issue date since payment is usually immediate. example: '2020-07-27' currency: type: string description: >- Three-letter [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) in uppercase. example: USD exchange_rate: type: number format: float nullable: true description: >- Exchange rate applied when converting from transaction currency to account base currency. If omitted, the ECB (European Central Bank) reference rate for the issue date is automatically applied. example: 0.680309 tag_list: type: array items: type: string nullable: true description: >- Array of tags for categorizing and filtering receipts. Useful for organizing by product line, sales channel, or custom categories. example: consulting, premium payment_details: type: string nullable: true description: >- Additional information about accepted payment methods, displayed to the customer. notes: type: string nullable: true description: >- Internal notes or additional information about this receipt. Not typically shown to customers. contact: anyOf: - type: object $ref: '#/components/schemas/contact' - type: object properties: id: type: integer full_name: type: string description: >- Customer receiving this receipt. Can reference an existing contact by ID or include full contact details. attachments: type: array readOnly: true items: type: object $ref: '#/components/schemas/attachment' description: Files attached to this receipt. country: type: string readOnly: true description: >- Customer's billing country as a 2-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). Used for tax calculations. example: US postal_code: type: string readOnly: true nullable: true description: >- Customer's billing postal code or ZIP code. Used for tax calculations in some jurisdictions. example: '91104' region: type: string readOnly: true nullable: true description: >- Customer's billing state, province, or region. Important for calculating state/provincial taxes. example: CA city: type: string readOnly: true nullable: true description: Customer's billing city. example: Pasadena street_line_1: type: string nullable: true description: First line of customer's billing address (street address or PO Box). example: 2311 North Los Robles Av. street_line_2: type: string nullable: true description: >- Second line of customer's billing address (apartment, suite, unit, or building number). example: Apartment C subject: type: string nullable: true description: >- Brief summary or title describing what this receipt is for. Displayed prominently on the document. deliveries: type: array nullable: true readOnly: true items: type: object $ref: '#/components/schemas/envelope' description: >- Delivery history showing when and how this receipt was sent to the customer (email, etc.). items: type: array items: type: object $ref: '#/components/schemas/document_item' description: >- Line items included in this receipt (products, services, fees, etc.). Maximum 200 items per request; use update requests to add more. Total limit: 1000 items per receipt. taxes: type: array readOnly: true items: type: object $ref: '#/components/schemas/document_tax' description: >- Calculated tax breakdown showing each applicable tax (VAT, sales tax, etc.) with rates and amounts. payments: type: array readOnly: true items: type: object $ref: '#/components/schemas/payment' description: >- Payment records associated with this receipt, showing when and how payment was received. evidence: type: object $ref: '#/components/schemas/evidence' description: >- Location evidence (IP address, billing country, etc.) used to determine applicable tax rates and jurisdictions. payment_processor: type: string nullable: true description: >- Name of the payment processor that handled this transaction (e.g., "stripe", "paypal", "braintree"). example: stripe payment_processor_id: type: string nullable: true description: >- Transaction ID from the payment processor. Used to link this receipt to the original payment gateway transaction. example: ch_999999999999 processor_fee_cents: type: integer nullable: true description: Payment processing fee charged by the payment processor, in cents. example: 99 custom_metadata: type: object nullable: true description: >- Custom key-value pairs for storing additional structured data. Useful for integrations and storing application-specific information. subtotal_cents: type: integer readOnly: true description: >- Sum of all line items before discounts and taxes are applied, in cents. example: 9375 discount_cents: type: integer readOnly: true description: Total discount amount applied to this receipt, in cents. example: 0 total_cents: type: integer readOnly: true description: Final amount due after applying discounts and taxes, in cents. example: 9375 state: type: string enum: - paid default: paid readOnly: true description: >- **All receipts are paid by definition.** Receipts document completed transactions and are always in the "paid" state. alerts: type: array readOnly: true items: type: object $ref: '#/components/schemas/document_alert' description: >- Important notifications or warnings about this receipt (e.g., validation issues, tax calculation warnings). permalink: type: string format: uri description: Public URL where customers can view this receipt online. readOnly: true example: https://quadernoapp.com/receipt/123345abcdef67890 pdf: type: string format: uri description: Direct download URL for the PDF version of this receipt. readOnly: true example: https://quadernoapp.com/receipt/123345abcdef67890.pdf url: type: string format: uri description: API endpoint URL for this receipt resource. readOnly: true example: https://quadernoapp.com/api/receipt/92732431 required: - contact - items credit: type: object description: >- Credit notes are formal documents that reduce or cancel amounts owed by customers. They are issued for refunds, order cancellations, pricing corrections, or to reverse previously invoiced amounts. properties: id: type: integer description: Unique identifier for the credit note. readOnly: true example: 92732431 created_at: oneOf: - type: string - type: integer description: >- Timestamp when the credit note was created. Measured in seconds since the Unix epoch. readOnly: true example: '1593260908' number: type: string description: >- Unique, sequential number identifying this credit note. Credit note numbers must be sequential without gaps or duplicates to comply with legal requirements. Automatically generated if not provided. example: '00001' issue_date: type: string format: date description: >- Date the credit note was issued, documenting when the credit was applied. example: '2020-06-27' related_document: type: object description: >- Reference to the original invoice or receipt that this credit note is refunding or correcting. Links the credit to the source transaction. properties: id: type: integer description: Unique identifier for the related invoice or receipt. readOnly: true example: 92732430 type: type: string description: 'Type of the related document: "Invoice" or "Receipt".' readOnly: true example: Invoice po_number: type: string nullable: true description: >- Original purchase order number from the related invoice, maintained for reference. example: '999' due_date: type: string format: date nullable: true description: >- Due date for credit application or refund processing. May differ from issue date for complex refund workflows. example: '2020-07-27' currency: type: string description: >- Three-letter [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) in uppercase. Typically matches the original invoice currency. example: USD tag_list: type: array items: type: string nullable: true description: >- Array of tags for categorizing and filtering credit notes. Useful for tracking refund reasons or processing status. example: refund, product_return notes: type: string nullable: true description: >- Internal notes or reason for issuing this credit note. Helps track why credits were issued. contact: anyOf: - type: object $ref: '#/components/schemas/contact' - type: object properties: id: type: integer full_name: type: string description: >- Customer receiving this credit. Can reference an existing contact by ID or include full contact details. country: type: string description: >- Customer's billing country as a 2-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). Used for tax calculations on the credit. example: US postal_code: type: string nullable: true description: >- Customer's billing postal code or ZIP code. Used for tax calculations in some jurisdictions. example: '91104' region: type: string nullable: true description: >- Customer's billing state, province, or region. Important for calculating state/provincial tax credits. example: CA street_line_1: type: string nullable: true description: First line of customer's billing address (street address or PO Box). example: 2311 North Los Robles Av. street_line_2: type: string nullable: true description: >- Second line of customer's billing address (apartment, suite, unit, or building number). example: Apartment C tax_id: type: string nullable: true description: >- Customer's tax identification number (VAT number, EIN, etc.). Important for B2B credit note compliance. subject: type: string nullable: true description: >- Brief summary or reason for this credit note. Displayed prominently on the document (e.g., "Refund for Order #12345"). example: Product return refund deliveries: type: array nullable: true readOnly: true items: type: object $ref: '#/components/schemas/envelope' description: >- Delivery history showing when and how this credit note was sent to the customer (email, etc.). items: type: array items: type: object $ref: '#/components/schemas/document_item' description: >- Line items included in this credit note, typically matching items from the original invoice or receipt. Maximum 200 items per request; use update requests to add more. Total limit: 1000 items per credit note. taxes: type: array readOnly: true items: type: object $ref: '#/components/schemas/document_tax' description: >- Calculated tax breakdown showing tax credits being applied. Typically reverses taxes from the original document. payments: type: array readOnly: true items: type: object $ref: '#/components/schemas/payment' description: >- Refund payment records showing when and how credits were returned to the customer. payment_processor: type: string nullable: true description: >- Name of the payment processor handling the refund (e.g., "stripe", "paypal", "braintree"). Typically matches the original transaction processor. example: stripe payment_processor_id: type: string nullable: true description: >- Refund transaction ID from the payment processor. Links this credit to the refund transaction in the payment gateway. example: ch_999999999999 processor_fee_cents: type: integer nullable: true description: >- Payment processing fee for the refund transaction, in cents. May differ from original transaction fee. example: 99 custom_metadata: type: object nullable: true description: >- Custom key-value pairs for storing additional structured data. Useful for tracking refund reasons or linking to support tickets. exchange_rate: type: number format: float readOnly: true description: >- Exchange rate applied when converting from credit currency to account base currency. Typically matches the rate from the original invoice. example: 0.680309 subtotal_cents: type: integer readOnly: true description: >- Sum of all line items before discounts and taxes are applied, in cents. Represents the gross credit amount. example: 9375 discount_cents: type: integer readOnly: true description: >- Total discount amount from the original transaction being credited, in cents. example: 0 total_cents: type: integer readOnly: true description: >- Final credit amount after applying discounts and taxes, in cents. This is the amount returned to the customer. example: 9375 state: type: string enum: - outstanding - late - paid - void - archived default: outstanding readOnly: true description: >- Current processing status. Can be: "outstanding" (credit issued, refund pending), "late" (refund overdue), "paid" (refund completed), "void" (credit cancelled), or "archived" (removed from active credits). permalink: type: string format: uri description: Public URL where customers can view this credit note online. readOnly: true example: https://quadernoapp.com/credit/123345abcdef67890 pdf: type: string format: uri description: Direct download URL for the PDF version of this credit note. readOnly: true example: https://quadernoapp.com/credit/123345abcdef67890.pdf url: type: string format: uri description: API endpoint URL for this credit note resource. readOnly: true example: https://quadernoapp.com/api/credit/92732431 required: - contact - items proforma: type: object description: >- Proformas are preliminary documents sent to customers before a sale is confirmed. They outline the expected cost of goods or services and can be accepted, declined, or converted into an invoice. properties: id: type: integer description: Unique identifier for the proforma. readOnly: true example: 92732431 created_at: type: integer description: >- Timestamp when the proforma was created. Measured in seconds since the Unix epoch. readOnly: true example: 1593260908 url: type: string format: uri description: API endpoint URL for this proforma resource. readOnly: true example: https://quadernoapp.com/api/estimate/92732431 alerts: type: array readOnly: true items: type: object $ref: '#/components/schemas/document_alert' description: Important notifications or warnings about this proforma. attachment: type: object $ref: '#/components/schemas/attachment' city: type: string readOnly: true nullable: true description: Customer's billing city. example: Pasadena contact: anyOf: - type: object $ref: '#/components/schemas/contact' - type: object properties: id: type: integer full_name: type: string description: >- Customer receiving the proforma. Can reference an existing contact by ID or include full contact details. country: type: string readOnly: true description: >- Customer's billing country as a 2-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). Used for tax calculations. example: US currency: type: string description: >- Three-letter [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) in uppercase. example: USD custom_metadata: type: object nullable: true description: Custom key-value pairs for storing additional structured data. deliveries: type: array nullable: true readOnly: true items: type: object $ref: '#/components/schemas/envelope' description: >- Delivery history showing when and how this proforma was sent to the customer. due_days: type: integer nullable: true description: >- Number of days after the invoice issue date when payment is due. When the proforma is converted to an invoice, the invoice due_date is calculated as issue_date + due_days. example: 30 discount_cents: type: integer readOnly: true description: Total discount amount applied to this proforma, in cents. example: 0 issue_date: type: string format: date readOnly: true description: >- Date the proforma was issued. Automatically set to the creation date by the system. example: '2020-06-27' items: type: array items: type: object $ref: '#/components/schemas/document_item' description: >- Line items included in this proforma (products, services, fees, etc.). notes: type: string nullable: true description: Internal notes or additional information about this proforma. number: type: string readOnly: true description: >- Unique, sequential code identifying this proforma. Automatically generated by the system at creation time. example: E-00001 payment_details: type: string nullable: true description: >- Additional information about accepted payment methods, displayed to the customer. pdf: type: string format: uri description: Direct download URL for the PDF version of this proforma. readOnly: true example: https://quadernoapp.com/estimate/123345abcdef67890.pdf permalink: type: string format: uri description: Public URL where customers can view this proforma online. readOnly: true example: https://quadernoapp.com/estimate/123345abcdef67890 po_number: type: string nullable: true description: Customer's purchase order number for reference and tracking. example: '999' postal_code: type: string readOnly: true nullable: true description: Customer's billing postal code or ZIP code. example: '91104' region: type: string readOnly: true nullable: true description: Customer's billing state, province, or region. example: CA state: type: string enum: - outstanding - accepted - declined - invoiced - late default: outstanding readOnly: true description: >- Current state of the proforma. Can be: "outstanding" (awaiting response), "accepted" (customer agreed), "declined" (customer rejected), "invoiced" (converted to an invoice), or "late" (past the valid_until date without a response). street_line_1: type: string nullable: true description: First line of customer's billing address. example: 2311 North Los Robles Av. street_line_2: type: string nullable: true description: Second line of customer's billing address. example: Apartment C subject: type: string nullable: true description: >- Brief summary or title describing what this proforma is for. Displayed prominently on the document. subtotal_cents: type: integer readOnly: true description: >- Sum of all line items before discounts and taxes are applied, in cents. example: 9375 tag_list: type: array items: type: string nullable: true description: Array of tags for categorizing and filtering proformas. example: consulting, premium tax_id: type: string nullable: true description: Customer's tax identification number (VAT number, EIN, etc.). taxes: type: array readOnly: true items: type: object $ref: '#/components/schemas/document_tax' description: >- Calculated tax breakdown showing each applicable tax with rates and amounts. total_cents: type: integer readOnly: true description: Final total after applying discounts and taxes, in cents. example: 9375 valid_until: type: string format: date nullable: true description: >- Expiration date of the proforma. Once this date is passed and the proforma has not been accepted, it transitions to the "late" state. example: '2020-07-27' required: - contact - items recurring: type: object description: >- Recurring are special documents that periodically renew themselves, generating an invoice or and expense. properties: id: type: integer description: Unique identifier for the object. readOnly: true example: 92732431 start_date: type: string format: date description: >- Date of the issue of the first document for this recurring. Defaults to 1 months from today. example: '2023-01-27' end_date: type: string nullable: true format: date description: Date of the issue of the last document for this recurring. example: '2024-01-27' frequency: type: string enum: - daily - weekly - biweekly - monthly - bimonthly - quarterly - semiyearly - yearly - biyearly default: monthly description: >- Recurring frequency. Deprecated. Use recurring_period and recurring_frequency instead. recurring_period: type: string enum: - days - weeks - months - years default: months description: Recurring period. recurring_frequency: type: integer default: 1 description: The number of recurring periods between each document. due_days: type: string format: date nullable: true description: The date on which payment for this recurring is due. example: '2020-07-27' po_number: type: string nullable: true description: Purchase order number. example: '999' currency: type: string description: >- Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217), in uppercase. example: USD tag_list: type: array items: type: string nullable: true description: Multiple tags should be separated by commas. example: consulting, premium payment_details: type: string nullable: true description: Detailed information about the accepted payment methods. notes: type: string nullable: true description: Extra notes about the recurring. contact: anyOf: - type: object $ref: '#/components/schemas/contact' - type: object properties: id: type: integer full_name: type: string description: Customer who will be billed. subject: type: string nullable: true description: An optional summary description for the document. items: type: array items: type: object $ref: '#/components/schemas/document_item' description: >- The individual line items that make up the recurring. No more than 200 items are allowed in a request. To add more use subsequent update requests. Maximum items per document are limited up to 1000 items. taxes: type: array readOnly: true items: type: object $ref: '#/components/schemas/document_tax' description: >- An array of tax line objects, each of which details a tax applicable to the recurring. custom_metadata: type: object nullable: true description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. total_cents: type: integer readOnly: true description: Total after discounts and taxes. example: 9375 state: type: string enum: - active - archived default: active readOnly: true description: The status of the recurring. url: type: string format: uri description: URI of the object readOnly: true example: https://quadernoapp.com/api/recurring/92732431 required: - contact - items expense: type: object description: >- A business expense is an operating cost incurred to a business during an accounting period. properties: id: type: integer description: Unique identifier for the object. readOnly: true example: 927324 created_at: type: integer description: >- Time at which the object was created. Measured in seconds since the Unix epoch. readOnly: true example: 1593260908 issue_date: type: string format: date description: Date when the expense was issued. example: '2023-09-01' po_number: type: string nullable: true description: Purchase order number. example: '999' currency: type: string description: >- Three-letter [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217), in uppercase. example: USD tag_list: type: array items: type: string nullable: true description: Multiple tags should be separated by commas. example: consulting, office payment_details: type: string nullable: true description: Detailed information about the payment. notes: type: string nullable: true description: Extra notes about the expense. contact: anyOf: - type: object $ref: '#/components/schemas/contact' - type: object properties: id: type: integer full_name: type: string description: Provider of your expense. attachment: type: object $ref: '#/components/schemas/attachment' country: type: string description: >- The customer’s billing country. 2-letter [ISO country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). example: US postal_code: type: string nullable: true description: The customer’s billing ZIP or postal code. example: '91104' region: type: string nullable: true description: The customer’s billing state/province/region. example: CA street_line_1: type: string nullable: true description: The customer’s billing address line 1 (Street address/PO Box). example: 2311 North Los Robles Av. street_line_2: type: string nullable: true description: >- The customer’s billing address line 2 (Apartment/Suite/Unit/Building). example: Apartment C subject: type: string nullable: true description: An optional summary description of the document. items: type: array items: type: object $ref: '#/components/schemas/document_item' description: >- The individual line items that make up the expense. No more than 200 items are allowed in a request. To add more use subsequent update requests. Maximum items per document are limited up to 1000 items. taxes: type: array readOnly: true items: type: object $ref: '#/components/schemas/document_tax' description: >- An array of tax line objects, each of which details a tax applicable to the expense. payments: type: array readOnly: true items: type: object $ref: '#/components/schemas/payment' description: Array of all payments on this expense, if applicable. payment_method: writeOnly: true type: string enum: - credit_card - cash - wire_transfer - direct_debit - check - iou - paypal - other description: Payment method used. payment_processor: writeOnly: true type: string nullable: true description: The payment processor used to pay the expense. example: stripe payment_processor_id: writeOnly: true type: string nullable: true description: The ID the `payment_processor` assigned to the payment. example: ch_999999999999 custom_metadata: type: object nullable: true description: >- Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. subtotal_cents: type: integer readOnly: true description: >- Total of all items on the expense before any discount or tax is applied. example: 9375 discount_cents: type: integer readOnly: true description: Current discount applied, if there is one. example: 0 total_cents: type: integer readOnly: true description: Total after discounts and taxes. example: 9375 state: type: string enum: - outstanding - late - uncollectible - paid - refunded - archived default: outstanding readOnly: true description: The status of the expense. url: type: string format: uri description: URI of the object readOnly: true example: https://quadernoapp.com/api/expenses/1.json required: - contact - items final_document: type: object description: >- This object represents the updateable fields for a finalized document. Once a document is finalized for compliance, only these fields can be updated. properties: tag_list: type: array items: type: string nullable: true description: Multiple tags should be separated by commas. example: consulting, premium payment_details: type: string nullable: true description: Detailed information about the accepted payment methods. notes: type: string nullable: true description: Extra notes about the document. custom_metadata: type: object nullable: true description: Set of key-value pairs that you can attach to an object. example: key: value attachment: type: object $ref: '#/components/schemas/attachment' document_item: type: object description: >- Individual line item on an invoice or receipt, representing a product, service, or fee. properties: id: type: integer description: Unique identifier for this line item. readOnly: true example: 92732431 description: type: string description: >- Description of the product or service being billed, displayed to the customer on the invoice. example: Ruby Essentials subtotal_cents: type: integer readOnly: true description: >- Total price for this line item (unit_price × quantity) before discounts or taxes, in cents. example: 9375 discount_cents: type: integer description: Discount amount applied to this line item, in cents. example: 0 discount_rate: type: number format: float nullable: true description: >- Percentage discount applied to this item (0-100). Alternative to specifying discount_cents directly. example: 25.5 quantity: type: number format: float default: 1 description: Number of units of this product or service being billed. example: 2 product_code: type: string nullable: true description: >- SKU or product code from your Quaderno product catalog. Used for sales tracking and reporting by product. example: 012345678901-MFN tax_1_transaction_type: type: string enum: - consulting - eservice - ebook - saas - standard - reduced description: >- Primary tax classification for this item. Determines applicable tax rules and rates (e.g., "eservice" for digital services, "saas" for software subscriptions). example: eservice tax_1_country: type: string nullable: true description: Country where the primary tax applies, as a 2-letter ISO code. example: CA tax_1_name: type: string nullable: true description: Name of the primary tax (e.g., "VAT", "GST", "Sales Tax"). example: GST tax_1_rate: type: number format: float nullable: true description: Primary tax rate as a percentage. example: 5 tax_1_region: type: string nullable: true description: >- State/province where the primary tax applies. Used for US sales tax and Canadian GST/PST. example: BC tax_2_transaction_type: type: string enum: - consulting - eservice - ebook - saas - standard - reduced description: >- Secondary tax classification. Used when multiple taxes apply to a single item (e.g., GST + PST in Canada). example: eservice tax_2_country: type: string nullable: true description: Country where the secondary tax applies, as a 2-letter ISO code. example: CA tax_2_name: type: string nullable: true description: Name of the secondary tax. example: PST tax_2_rate: type: number format: float nullable: true description: Secondary tax rate as a percentage. example: 7 tax_2_region: type: string nullable: true description: >- State/province where the secondary tax applies. Used for US sales tax and Canadian GST/PST. example: BC total_amount: type: number format: float description: >- Final total for this line item after discounts and taxes. Required if unit_price is not provided. Quaderno will back-calculate the base price. example: 19.98 unit_price: type: number format: float description: >- Price per unit before discounts or taxes. Required if total_amount is not provided. Quaderno will calculate the final total. example: 9.99 required: - description document_tax: type: object description: >- Calculated tax line showing the breakdown of a specific tax applied to the invoice. Multiple tax lines may appear when different taxes apply (e.g., federal and state taxes, or multiple tax rates for different items). properties: label: type: string nullable: true description: Display name of the tax. example: GST rate: type: number format: float default: 0 description: Tax rate applied as a percentage. example: 5 country: type: string description: Country where this tax applies, as a 2-letter ISO code. example: CA region: type: string nullable: true description: >- State or province where this tax applies. Relevant for US sales tax and Canadian provincial taxes (GST/PST). example: BC county: type: string nullable: true description: >- County where this tax applies. Only applicable for US sales tax in states with county-level taxes. example: Los Angeles transaction_type: type: string enum: - consulting - eservice - ebook - saas - standard - reduced nullable: true description: >- Tax classification that determined this tax rate (e.g., "eservice" for digital services, "saas" for software). example: eservice amount_cents: type: integer description: Total tax amount for this tax line, in cents. example: 1000 document_alert: type: object description: >- Warning or notification about potential issues with the invoice, particularly related to tax calculations or compliance. properties: kind: type: string enum: - conflicting_evidence - jurisdiction_mismatch - wrong_tax_rate - non_taxable - reverse_charge - not_registered description: >- Type of alert: "conflicting_evidence" (inconsistent location data), "jurisdiction_mismatch" (tax location doesn't match billing location), "wrong_tax_rate" (unexpected tax rate applied), "non_taxable" (transaction may be exempt), "reverse_charge" (customer may owe tax instead), "not_registered" (not registered for tax in this jurisdiction). description: type: string description: >- Detailed explanation of the issue, such as conflicting location evidence, tax exemptions that weren't applied, or missing tax registration information. example: >- Location evidence indicates customer is in US, but billing address shows CA. Tax calculated based on evidence. payment: type: object description: A payment associated with a document. properties: id: type: integer description: Unique identifier for the object. readOnly: true example: 92732431 amount: type: number format: float description: Paid amount. example: 56.6 created_at: type: integer readOnly: true description: >- Time at which the object was created. Measured in seconds since the Unix epoch. example: '1593260908' date: type: string format: date nullable: true description: Default is current date. example: '2020-06-27' payment_method: type: string enum: - credit_card - cash - wire_transfer - direct_debit - check - iou - paypal - other - credit - offset nullable: true description: '' example: credit_card processor: type: string nullable: true description: The payment processor used to process the payment. example: stripe processor_id: type: string nullable: true description: The ID the `payment_processor` assigned to the payment. example: ch_999999999999 url: type: string format: uri description: URI of the object readOnly: true example: https://quadernoapp.com/api/payments/92732431 attachment: type: object description: Invoices and expenses can have attached files. writeOnly: true properties: data: type: string description: File data encoded in base64. filename: type: string description: Name of the attached file. example: ticket.jpeg public: type: boolean description: >- Visibility of attached file. Public attachments can be seen and downloaded by customers. default: false example: true required: - data - filename address: type: object description: >- Address information for a connected account. Note: Changing the country is strongly discouraged if the new country has a different official currency, as this may cause inconsistencies with the account currency and affect tax calculations and reporting. properties: id: type: integer description: Unique identifier for the address. example: 16 readOnly: true street_line_1: type: string description: Primary street address, including street number and name or PO Box. example: 2311 North Los Robles Av. nullable: true street_line_2: type: string description: >- Secondary address line for apartment, suite, unit, or building details. example: Apartment C nullable: true city: type: string description: City, district, suburb, town, or village name. example: Pasadena nullable: true region: type: string description: State, province, or region code. example: CA nullable: true postal_code: type: string description: ZIP or postal code. example: '91104' nullable: true country: type: string description: >- Two-letter ISO 3166-1 alpha-2 country code. Defaults to the account's original country. WARNING: Changing the country is not recommended, especially if the new country uses a different official currency than the account currency. This may lead to tax calculation errors, reporting inconsistencies, and compliance issues. If you need to operate in a different country with a different currency, consider creating a new account instead. example: US nullable: true valid_from: type: string format: date description: >- Date when this address becomes effective (ISO 8601 format: YYYY-MM-DD). Defaults to the current date. example: '2023-07-01' valid_until: type: string format: date description: >- Date when this address expires, if applicable (ISO 8601 format: YYYY-MM-DD). Leave empty for addresses with no end date. example: '2024-02-03' nullable: true webhook: type: object description: >- Webhooks allow to be notified about events that happen in your Quaderno account. They can be created from the dashboard or via API. properties: id: type: integer description: Unique identifier for the object. readOnly: true example: 92732431 auth_key: type: string readOnly: true description: The endpoint's secret, used to generate webhook signatures. example: zXQgArTtQxAMaYppMrDoUQ created_at: type: string format: date-time readOnly: true description: Time at which the object was created. example: '2023-01-24T10:59:15.000Z' events_sent: type: integer nullable: true readOnly: true description: Number of events delivered to the endpoint. example: 0 events_types: type: array items: type: string description: The list of events to enable for this endpoint. example: - invoice.created - credit.created last_error: type: string nullable: true readOnly: true description: Description of the last error returned by the endpoint. example: Response code 503 returned. last_error_at: type: string format: date-time nullable: true readOnly: true description: Time at which the endpoint returned the last error. example: '2023-01-24T10:59:15.000Z' last_sent_at: type: string format: date-time nullable: true readOnly: true description: Time at which the events were delivered for the last time. example: '2023-01-24T10:59:15.000Z' url: type: string format: uri description: The URL of the webhook endpoint. example: https://myawesomeapp.com/notifications required: - events_types - url envelope: type: object description: >- An envelope stores the document´s delivery information for external systems. properties: delivered_at: type: integer readOnly: true description: >- Time at which the document was delivered. Measured in seconds since the Unix epoch. example: '1593260908' recipient: type: string readOnly: true enum: - ticketbai_araba - ticketbai_gipuzkoa - ticketbai_bizkaia description: Name of the destination system. example: ticketbai_araba service_response: type: string readOnly: true nullable: true description: >- Response from the system after delivering the document. May contain error messages. type: type: string readOnly: true enum: - registration - cancellation description: Envelope type. example: registration securitySchemes: API key: description: HTTP Authentication with your API Key type: http scheme: basic Bearer token: description: Quaderno Connect OAuth2 Bearer tokens type: oauth2 flows: authorizationCode: authorizationUrl: https://quadernoapp.com/oauth/authorize tokenUrl: https://quadernoapp.com/oauth/token scopes: read_only: Grants read access read_write: Grants read and write access security: - API key: [] - Bearer token: []