Quaderno.js

This reference documents every object and method available in Quaderno's browser-side JavaScript library, Quaderno.js.

You can use Quaderno.js to calculate taxes and validate tax IDs right on your frontend.

Including Quaderno.js

To get started, include this script on your pages — it should always be loaded directly from https://js.quaderno.io

  <script src="https://js.quaderno.io/v4/"></script>

Initializing Quaderno.js

For your convenience, there are a few different ways to initialize Quaderno.js.

With the automatic inits (simple and deferred) Quaderno.js attaches itself to the DOM, looking for data-quaderno attributes in your forms to automatically fill the options for calculateTaxes().

You can avoid this behavior using the custom init method.

warning

Please note that we provide a differentiated publishable API key for Quaderno.js for security reasons. This public API key is different from your account's private API key, which should never be exposed on your frontend.

You can tell the difference by their naming:

private key starts with sk_, which stands for "secret key"
public key starts with pk_, which stands for "public key"

While the private API key is meant for being used server-side, secured in your backend, the public API key is only used by Quaderno.js, and only allow access to our tax calculations engine. No data can be leaked from your account with the public API key.

Simple automatic init

    <head>
      <script src="https://js.quaderno.io/v4/"></script>
    </head>

    <body>
      <form id="quaderno-payment-form" data-publishable-key="pk_xxxxxxxx">
        <select data-quaderno="country"> … </select>
        <input data-quaderno="postalCode" />
        ...
      </form>
    </body>

Automatically loads quaderno.js if the form has the quaderno-payment-form id and a valid data-publishable-key. Optionally you can also set a data-product-id.

data-publishable-key: Your Quaderno public key. Remember to never expose your private API keys.

The input fields will be automatically detected as long as they have the data-quaderno with their definition:

postalCode (highly recommendable)
country (mandatory)
businessNumber
city
productId
amount
quantity
taxType
taxClass
productId
couponCode
sellerPostalCode
sellerCity
sellerCountry

Deferred automatic init

    <head>
      <script src="https://js.quaderno.io/v4/"></script>
    </head>

    <body>
      <form id="payment-form" data-publishable-key="pk_xxxxxxxx" data-product-id="prod_xxxxxxxx">
        <select data-quaderno="country"> … </select>
        <input data-quaderno="postalCode" />
        <!-- … -->
      </form>

      <script>
        Quaderno.bindForm('#payment-form').then(function(response) {
          console.log(response.product);
        }).catch(function(error){
          console.log(error.description, error.messages);
        });
      </script>
    </body>

If you don't want the form to load automatically, you can load it later by not using the "quaderno-payment-form" id, and then call the bindForm method whenever you want.

Custom init

    <label for="country">
      <span>Country</span>
      <input id="country" name="country" value="ES" />
    </label>

    <label for="postal-code">
      <span>Postal code</span>
      <input id="postal-code" name="postal-code" value="35007" />
    </label>

    <script>
      Quaderno.init(publishableKey).then(function() {
        console.log('Quaderno.js successfully initialized');
      }).catch(function(error) {
        console.log(error.description, error.messages);
      });
    </script>

Futhermore, you can also dissociate Quaderno from the DOM by setting the Quaderno object properties by yourself.

This means you need to explicitly set your publishableKey as argument for the init call, instead of using the data-publishable-key html attribute in your form.

Afterwards, you'll need to specify all options for calculateTaxes().

Methods

When you include the Quaderno.js script in your page, a global Quaderno object will be available with the following methods:

init( publishableKey )

  // never expose your private API key on your frontend, use the public API key instead
  Quaderno.init(publishableKey).then(function(){
    console.log('Success');
  }).catch(function(error){
    console.log(error.description, error.messages);
  });

Async request. Use this method to initialize the global object Quaderno.

Use init for initializing Quaderno.js unbinded from the UI, as explained in initializing Quaderno.js – Custom Init. This means you won't be using custom attributes like id="quaderno-payment-form" data-publishable-key="pk_xxxxxxxx" in your forms, but just pure javascript.

This method returns a Promise which resolves if the publishableKey verification was successful. If there's any issue, this method returns a Promise which rejects with an error object. This object has either:

error.description: A full description of the error.
error.messages: If present, it indicates the affected attribute and an specific error (ie. { email: "invalid", businessNumber: "invalid" }).

bindForm( formId )

  // to use along with the deferred automatic init
  Quaderno.bindForm("#formId").then(function(){
    console.log('Success');
  }).catch(function(error){
    console.log(error.description, error.messages);
  });

Async request. This method also initializes the global object Quaderno from a form object.

Use this method when you need to use your own id in your forms or when you want to not load the form with the page but later, in conjuction with the deferred automatic init.

If you want to completely detach from the UI and just use pure javascript, check Custom Init.

error.description: A full description of the error.
error.messages: A brief description if each invalid attribute.

calculateTaxes( options )

  // use `options` along with Custom init
  var options = { taxClass: 'eservice', postalCode: '123456', city: 'Dublin', country: 'IE' }

  Quaderno.calculateTaxes(options).then(function(taxObject){
    console.log(taxObject.name, taxObject.rate, taxObject.country); // ie. "VAT", 23, "IE"
  })

Async request. Calculates the taxes based on the billing data from options object

Available options are documented below:

Attribute	Mandatory	Description
`taxClass`	No	Indicates the tax class of the transaction.
`postalCode`	No	ZIP or postal code.
`city`	No	The customer's city. Used to make more accurate calculations based on the postal code
`country`	No	ISO 3166-1 alpha-2
`businessNumber`	No	A valid business number. Quaderno validates EU VAT numbers, ABN, and NZBN.
`sellerPostalCode`	No	ZIP or postal code. The seller's postal code during the transaction. Defaults to your account postal code.
`sellerCity`	No	The of the seller's city during the transaction. Defaults to your account city
`sellerCountry`	No	ISO 3166-1 alpha-2. The seller's country during the transaction. Defaults to your account country

  <!-- no need to fill the `options` of calculateTaxes() with automatic inits -->
  <form id="quaderno-payment-form" data-publishable-key="pk_xxxxxxxx">
    <select data-quaderno="country"> … </select>
    <input data-quaderno="postalCode" />
    ...
  </form>

The options can be omitted if you've set a form using bindForm and the proper data-quaderno, or used the simple automatic init.

This method returns a Promise which resolves with a tax object.

Note that when you calculate taxes using our Tax Rates API, parameters follow a slighty different naming scheme:

Quaderno.js	Tax Rates API
`taxClass`	`tax_code`
`businessNumber`	`tax_id`
`taxType`	`tax_behavior`

calculatePrice ([options])

  options = { amount: 100, quantity: 2 }
  priceObject = Quaderno.calculatePrice(options);

  priceObject.subtotal;
  priceObject.taxes;

Helper method which calculates the final price of the product, tax inclusive.

Available options are documented below:

Attribute	Mandatory	Description
`amount`	No	Amount you are going to charge your customer, in cents.
`quantity`	No	Quantity of the products.
`taxType`	No	If the tax is `included` or `excluded`

The options can be omitted if you've set a form using bindForm with its proper data-quaderno attributes, or if you've retrieved the product information from Quaderno with getProduct

This method returns a price object with the following attributes:

subtotal: the price without taxes and discounts.
taxes: the taxes amount.
total: the final amount.
discountedAmount: The discount amount.

destroy()

  Quaderno.destroy();

Remove event listeners from the DOM elements. It might be useful if you have single-page apps and have tied the Quaderno object to a form via bindForm or the simple initialization.

getProduct( productId )

  Quaderno.getProduct("productId").then(function(product){
    console.log(product.name, product.unitCost, product.code);
  });

Async request. Retrieve the product info identified by productId. Returns a product object in the resolve function.

You can register your products manually in quadernoapp.com/products or programatically with our API.

getCoupon( couponCode )

  Quaderno.getCoupon("couponCode").then(function(product){
    console.log(coupon.amountOff);
  });

Async request. Retrieve the product info identified by couponCode. Returns a coupon object in the resolve function.

You can register your products manually in quadernoapp.com/checkout/coupons or programatically with our API.

getLastTax()

  taxes = Quaderno.getLastTax();

  taxes.name;
  taxes.rate;
  taxes.country;

Reads the last calculated tax and returns a tax object.

tip

This performant method allows you to avoid repeatedly calling our API during your checkout process when you know the parameters won't change. Please use it whenever you can!

validateBusinessNumber(businessNumber, country)

  Quaderno.validateBusinessNumber("GB1234567", "GB").then(function(response){
    console.log(response.valid);
  }).catch(function(error){
    console.log(error.descriptions);
  });

Async request. This method validates the customer's business number. Quaderno currently validates EU VAT numbers, ABN, and NZBN.

Please keep in mind that business numbers are not actually validated when using Quaderno Sandbox.

This method returns a result object with the following attribute:

result.valid: true (valid business number)
result.valid: false (invalid business number)
result.valid: null (the external validation service is temporarily unavailable).

Objects

This section documents the objects you'll receive from Quaderno.js.

The Tax object

This object is passed by the resolve function of the Promise returned by the Quaderno.calculateTaxes method or by invoking Quaderno.getLastTax.

Attribute	Description
`country`	A valid ISO 3166-1 alpha-2 code.
`region`	State/Region/Province.
`county`	County (only for US sales tax).
`city`	City (only for US sales tax)
`countyTaxCode`	County tax code (if applicable on US sales taxes)
`cityTaxCode`	City tax code (if applicable on US sales taxes)
`name`	Name of the tax.
`rate`	Tax rate in percentage (6.5).
`extraName`	Name of the extra tax.
`extraRate`	Tax rate in percentage of the extra tax.
`taxClass`	The tax class of the transaction. Can be one of the following: `standard`, `eservice`, `ebook` or `saas`.
`businessNumberValid`	This attribute is only present if you've set a `businessNumber` during the calculation request. It can be `true`, `null` or `false`.

The Product object

This object contains the relevant information related to the productID you've set. It's returned by the resolve function of Quaderno.getProduct.

Attribute	Description
`code`	The product code in Quaderno.
`name`	The name of the product.
`image`	URL to the image of the product.
`unitCost`	Unit price of the product.
`currency`	A valid ISO-4271 code.
`kind`	Indicates if the product is either a `subscription` or a `one-off` sale.
`taxClass`	The tax class for the product. Can be one of the following: `standard`, `eservice`, `ebook` or `saas`.
`taxType`	Indicates if the tax is included or excluded from the product price.

The Coupon object

This object contains the relevant information related to the couponCode you've set. It's returned by the resolve function of Quaderno.getCoupon.

Attribute	Description
`code`	The product code in Quaderno.
`kind`	Indicates if the coupon is `percent_off` or `amount_off`
`amountOff`	The amount off.
`currency`	The currency of the amount off.
`percentOff`	The percent off.
`redeemable`	Indicates if the coupon is redeemable

Supported browsers

Quaderno.js strives to support all recent versions of major browsers. For the sake of security and providing the best experience to the majority of customers, we do not support browsers that are no longer receiving security updates and represent a small minority of traffic.

We support Internet Explorer and Edge per Microsoft's lifecycle policy.
We support Chrome and Safari on all platforms and Firefox on desktop platforms.
We support the Android native browser on Android 4.4 and later.
We respond to bug reports but do not proactively test other mobile browsers.

Including Quaderno.js​

Initializing Quaderno.js​

Simple automatic init​

Deferred automatic init​

Custom init​

Methods​

init( publishableKey )​

bindForm( formId )​

calculateTaxes( options )​

calculatePrice ([options])​

destroy()​

getProduct( productId )​

getCoupon( couponCode )​

getLastTax()​

validateBusinessNumber(businessNumber, country)​

Objects​

The Tax object​

The Product object​

The Coupon object​

Supported browsers​