DOCSEARCHbyAlgolia
Submit Docs

Quaderno Developer Documentation

website·Indexed 39 days ago

https://developers.quaderno.io

API and integration guides for tax management and invoicing. Features include tax calculation via Quaderno.js and backend APIs, recording sales and refunds, tax ID validation, e-invoicing (including Verifactu and TicketBAI), and webhook configuration. Includes SDKs for Ruby and PHP, a sandbox environment, and OAuth integration for Quaderno Connect.

Tokens
20.9K
Snippets
92
Records
155
Agent score
62%

What's inside Quaderno

  1. Overview of Quaderno Connect for Marketplaces and Platforms

    Quaderno Connect is an API and toolset designed for business models such as marketplaces and software platforms. It allows these platforms to integrate sales tax calculations into checkout forms and record merchant sales and refunds to generate compliant invoices, reports, and tax obligation notifications.

    Availability: Quaderno Connect requires a Business plan or higher.

  2. Overview of Quaderno Connect Custom accounts

    Quaderno Connect Custom accounts are designed for platforms or marketplaces that want to handle all account management and user interactions on behalf of their sellers. Because custom account holders do not have direct access to a Quaderno dashboard, the platform provider is responsible for building the entire user interface, from onboarding to reporting.

  3. Understand Quaderno tax calculation rules

    Quaderno calculates worldwide taxes based on registered tax jurisdictions, product details, and customer location. The rules vary by product type:

    • Physical Goods: Tax is calculated based on the shipping origin and destination.
    • e-Services, e-Books, and SaaS: Tax rates are applied based on the customer's location and the business's registered jurisdictions.
    • Consulting Services: Local tax rates are applied where the business is based; no tax is applied in other jurisdictions.
    • Other Services: The business's local tax rate is applied to all worldwide sales.

  4. Manage customer and vendor data with Contacts

    Contacts in Quaderno represent the customers and vendors associated with invoices, credit notes, and expenses. The Contact object stores critical billing information and tax identification data, which Quaderno uses to automatically determine the correct tax treatment for each transaction.

  5. Monitor tax obligation thresholds via webhooks

    To notify sellers when they are nearing or have reached tax collection obligations, create a webhook endpoint using the Webhooks API and subscribe to the following events:

    • threshold.warning: A tax threshold is about to be reached.
    • threshold.exceeded: A tax threshold has been reached.
    • threshold.eu.100k: Digital sales within the EU have reached €100,000 (applies to EU-based sellers only).

  6. Understand the Quaderno proforma lifecycle

    A proforma is a preliminary document sent to a customer before a sale is confirmed. It serves as a quote or invoice draft that can be updated or declined before being converted into a final, uneditable invoice. Proformas transition through the following states:

    • outstanding: Awaiting a response from the customer (default).
    • late: The valid_until date has passed without a response.
    • accepted: The customer agreed to the proforma.
    • declined: The customer rejected the proforma.
    • invoiced: The proforma has been converted into an invoice.

  7. Create billing documents using the Transactions API

    The Transactions API allows you to generate invoices, receipts, or credit notes by passing payment processor events (e.g., from Stripe or PayPal). Quaderno automatically calculates applicable taxes and can optionally deliver the document to the customer.

  8. Quaderno API core capabilities

    The Quaderno API provides the following tax and billing features:

    • Worldwide tax calculation for every sale.
    • Automatic generation of tax-compliant invoices and credit notes.
    • Webhook alerts for new tax registrations and obligations.
    • Tax reports filtered by country or state.
    • Tax ID validation.
    • Quaderno Connect for building marketplaces or platforms.
    • Quaderno Checkout for users without a custom checkout flow.
    • Multi-country e-invoicing compliance via a single API.

  9. Delete invoices and credits using credit notes

    The DELETE /invoices/INVOICE_ID and DELETE /credits/CREDIT_ID endpoints have been removed and will return 404 Not Found. To remove an invoice, you must associate it with a credit note using POST /credits with the invoice ID, which changes the invoice state to paid. To correct errors in credit notes, use PUT /credits/CREDIT_ID/void to void them.

  10. Initialize Quaderno.js using Custom Init

    Custom initialization completely dissociates Quaderno.js from the DOM. You must explicitly provide the public API key to the init() method and manually provide all options to tax calculation methods.
    Quaderno.init('pk_xxxxxxxx').then(function() {
  console.log('Quaderno.js successfully initialized');
}).catch(function(error) {
  console.log(error.description, error.messages);
});

  11. Install Quaderno.js

    Include the Quaderno.js browser-side library by adding the following script tag to your pages. The script must be loaded directly from the official source.
    <script src="https://js.quaderno.io/v4/"></script>

  12. Paginate list results in the Quaderno API

    List endpoints use the created_before parameter for pagination, which accepts an object ID to retrieve records created before that ID in reverse chronological order.

    • Page Size: Defaults to 25 objects; can be increased up to 100 using the limit parameter.
    • Pagination Headers:
      • X-Pages-HasMore: true if more records are available.
      • X-Pages-NextPage: The URL for the next page (present only if more records exist).
    curl "https://ACCOUNT_NAME.quadernoapp.com/api/contacts?created_before=42" \
  -u <YOUR_API_KEY>: