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. See here how.

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

curl --request POST \
  --url https://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,
  // use this authentication to act on behalf of the created custom account
  // custom account tokens provided upon account creation does not expire
  "authentication": {
    "token_type": "Bearer",
    "access_token": "xxx",
    "refresh_token": "yyy" // used to obtain a new expirable access_token
  },
  "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 provided access_token to perform any Quaderno API call on your user's behalf, including calculating taxes and recording their sales, issuing invoices, generating tax reports, and more.

As custom accounts are fully managed by the connected platform and final users can never revoke permissions, the provided tokens do not expire. Follow these steps to refresh any access_token when needed.

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": ""
  }'