Skip to main content

Onboard Custom accounts

A Quaderno Connect Custom account is designed for platforms or marketplaces that want to handle all account management and user interactions on behalf of their sellers. This means you are responsible for the entire user experience, from onboarding to reporting.

Since custom account holders don't have direct access to a Quaderno dashboard, you must build the entire interface on your platform.

Onboarding process​

The onboarding process for Custom accounts is a simple, three-step API workflow.

Step 1: Create a Quaderno App​

Before you begin, you must first create a Quaderno App. This app represents your platform and provides the necessary credentials for integrating with the API.

  1. Log in to your Quaderno account and create a new app.
  2. Provide a unique name for your app.
  3. Add your website URL and a support email.
  4. You can safely ignore the required "Callback URL" field, which is only necessary for Standard accounts.

Once created, you will be issued a unique Client ID and a Client Secret. Keep these secure, as you will need them to identify your application if you ever need to revoke a custom account's token.

Step 2: Create a Custom account per seller​

You can create a custom account for each seller on your platform by sending their configuration data to the Accounts API. This will return an access_token that allows you to act on the seller's 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"
  }'
tip

It's crucial to provide the billing address, default product type, and default tax code when creating the account. This information is required for Quaderno to calculate taxes properly and should not be omitted.

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


{
  "id": 21791,
  "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": "xxxxxx",
  "type": "custom",
  // use this authentication to act on behalf of the created custom account
  "authentication": {
    "token_type": "Bearer",
    "access_token": "xxxxx",
  }
}

Custom account tokens do not expire, since you are responsible for managing the account. You should securely store the access_token and subdomain to make API calls on behalf of this seller.

Step 3: Add seller's tax jurisdictions and addresses​

For Quaderno to accurately calculate tax, you must set up all the tax jurisdictions where your seller’s business is registered for tax collection.

tip

You should provide an interface in your application for sellers to select their registered jurisdictions and business addresses, which you can then register via Quaderno API.

Use our Tax ID API to register each jurisdiction where your seller is registered for tax collection:

curl https://sandbox-quadernoapp.com/api/tax_ids \
  -H "Authorization: Bearer {{YOUR_SELLER_ACCESS_TOKEN}}" \
  --data '{
    "jurisdiction_id": 94,
    "value": "123456789BW0001"
  }'

If your seller has multiple localizations, use our Address API to add them:

  curl https://sandbox-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"
  }'

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

Post-onboarding tasks​

Revoking access​

Since custom account tokens do not expire, you must manually revoke them if needed for security reasons. To disconnect a custom account, send a POST request to the /oauth/revoke endpoint:

curl https://sandbox-quadernoapp.com/oauth/revoke \
  -u {{YOUR_CLIENT_ID}}:{{YOUR_SECRET_KEY}} \
  -d token={{ACCESS_TOKEN}}

A successful revocation returns a 200 OK status with an empty body.

Making API calls​

Once the account is set up, you can make API calls on the seller's behalf. Use the Authorization: Bearer {{access_token}} header with each API request.

curl https://sandbox-quadernoapp.com/api/tax_rates/calculate?to_country=US\&to_postal_code=90210\&tax_code=eservice \
  -H "Authorization: Bearer {{access_token}}"