Skip to main content

Onboard Custom accounts

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

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.

At the very least, you'll need to add some configuration options to your platform's settings, so that sellers are able to introduce:

  • Their product's details and tax code.
  • Their billing address.
  • The jurisdictions where their business is registered for tax collection and its tax IDs.

You'll use that configuration information to create one custom account for each seller. This configuration is required to accurately calculate taxes on behalf of your platform's sellers.

In order to provide tax collection obligation alerts and reporting functionalities, you will have to send your sales and refunds data to Quaderno, via Transactions API.

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.

1. Creating a Quaderno app​

For your main Quaderno account to be ready to create custom accounts, you first need to create an "app" which represents your platform in the Quaderno system.

When creating an app for issuing custom accounts, you can safely ignore the required "Callback URL" field, that is only needed for Standard accounts following the whole OAuth2 flow. You’ll be issued with a client_id which you'll need to revoke custom account tokens if needed for security reasons.

info

All the examples shown use our Sandbox environment. Once your integration is fully developed and tested, just change your API URLs from https://ACCOUNT_NAME.sandbox-quadernoapp.com/api to https://ACCOUNT_NAME.quadernoapp.com/api.

2. Creating a Custom account per seller​

Send your seller's configuration data to the Accounts API, in order to get the access_token that will allow you to calculate taxes with their business and product details, and in general, act on their behalf:

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

Note that default_product_type and default_tax_code will be used as fallback when no product details are provided for calculating taxes on behalf of that seller.

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

{
  "id": 21791,
  // use this authentication to act on behalf of the created custom account
  "authentication": {
    "token_type": "Bearer",
    "access_token": "xxx", // custom account tokens does not expire *
  },
  "business_name": "Big Bang Inc.",
  "country": "US",
  "created_at": 1632212259,
  "currency": "USD",
  "default_product_type": "service",
  "default_tax_code": "ebook",
  "email": "[email protected]",
  "local_tax_id": "123456789",
  "state": "active",
  "subdomain": "ninive-xxxx", // the new ACCOUNT_NAME for your merchant
  "type": "custom"
}

* Since custom accounts are fully managed by the connected platform and users cannot revoke permissions, the provided tokens never expire. If you need to revoke an access_token for security reasons, follow the same process as with Standard accounts: revoke the token, deactivate the account, and contact us at [email protected].

Congratulations! 🎉

Now you can use the provided access_token with an Authorization: Bearer HTTP header to perform any Quaderno API call on your seller's behalf, including calculating taxes, recording their sales and refunds, issuing invoices, generating tax reports, and receiving new tax collection obligation alerts.

3. Setting up Custom accounts' tax jurisdictions​

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

First, let your sellers 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_SELLER_ACCESS_TOKEN}}" \
  --data '{
    "jurisdiction_id": 94,
    "value": "123456789BW0001"
  }'

4. Add seller's addresses​

To add addresses for the seller's custom account you just created, use an Authorization: Bearer {{access_token}} header per API request to the /adresses endpoint:

Adding an address to a custom account:
curl https://quadernoapp.com/api/addresses \
  -H "Authorization: Bearer {{YOUR_SELLER_ACCESS_TOKEN}}" \
  --data '{
    "street_line_1": "2311 North Los Robles Av.",
    "street_line_2": "Apartment C",
    "city": "Pasadena",
    "postal_code": "91104",
    "region": "CA",
    "valid_from": "2024-07-01"
  }'

* You might also want to modify the default seller address created automatically in Step 2, to add values as street_line_1 or region.

Congratulations! 🎉

Your seller's custom account is now fully onboarded. Please continue reading the "Integrate Connect" guide to learn how to calculate your seller's taxes, record their sales and refunds, provide reports to them, and alert them of new tax collection obligations.