Onboard Custom accounts

A Quaderno Connect Custom account is almost completely invisible to the account holder. You —the platform— are responsible for all interactions with your user and configure all the account's settings, including all the information needed for tax calculations, programmatically.

With Custom accounts you can modify the connected account’s details and settings programatically through the API, including managing their tax settings and invoices.

Since Custom account holders can’t log into Quaderno, it’s up to you to build the onboarding flow, user dashboard, reporting functionality, and communication channels.

note

💳 There’s an additional €2 cost per active custom account. A custom account is considered active when it has recorded at least one transaction or has made at least one API call during the month.

Creating a Custom account

info

We encourage testing these steps on our sandbox environment first.

To be able to create Custom accounts, first you'll need to create an Oauth app on your main Quaderno account. The step is the same as Step 1 from the guide "Integrating Standard accounts".

After that, use our Accounts API to create and connect each Custom account:

curl --request POST \
  --url https://YOUR_ACCOUNT_NAME.quadernoapp.com/api/accounts/ \
  -u YOUR_API_KEY:x \
  --header 'Content-Type: application/json' \
  --data '{
    "business_name": "Big Bang Inc.",
    "email": "bigbang@example.com",
    "country": "US",
    "postal_code": "10001",
    "local_tax_id": "123456789",
    "default_product_type": "service",
    "default_tax_code": "ebook"
  }'

The result of a successful API call is the user's account information and tokens:

{
  "id": 21791,
  "authentication": { // to be used to act on behalf of the new account
    "token_type": "Bearer",
    "access_token": "xxx", // expires on 25 days
    "refresh_token": "yyy" // does not expire on Custom accounts
  },
  "business_name": "Big Bang Inc.",
  "country": "US",
  "created_at": 1632212259,
  "currency": "USD",
  "default_product_type": "service",
  "default_tax_code": "ebook",
  "email": "bigbang@example.com",
  "local_tax_id": "123456789",
  "state": "active",
  "subdomain": "ninive-xxxx", // the new ACCOUNT_NAME for your merchant
  "type": "custom"
}

That's it! 🎉 Now you can use the Quaderno API on your user's behalf to calculate taxes, issue invoices, generate tax reports, and more.

info

🔐 Safely store the access_token and refresh_token in your database – You'll need those to make API calls on behalf of your connected accounts.

As Custom accounts are fully managed by the connected platform (final users can never revoke permissions), Custom account's refresh_token tokens does not expire.

Setting up Custom accounts' tax jurisdictions

For Quaderno to calculate tax correctly on behalf of your users, you first need to set up the tax jurisdictions where your connected account's business is currently registered.

First, let your users select which jurisdictions their business is registered in. You could provide a user interface in your application listing all available jurisdictions.

Then you can use our Tax ID API to register each jurisdiction on behalf of your connected accounts:

curl https://quadernoapp.com/api/tax_ids \
  -H "Authorization: Bearer {{YOUR_USER_ACCESS_TOKEN}}" \
  --data '{
    "jurisdiction_id": 94,
    "value": "123456789BW0001",
    "valid_from": "2023-01-01",
    "valid_until": ""
  }'