Skip to main content
Avalara Help Center

Install Avalara CertCapture for Ecommerce SDK

This article applies to:Avalara CertCapture

Embed CertCapture's exemption document submission form into your ecommerce site so it can communicate with CertCapture. Once you install the JavaScript tag into your application's webpage, use the provided functions to customize the CertCapture submission form as it appears on your site.

We recommend you contact Avalara Professional Services before you install and configure the ecommerce Software Developer Kit (SDK) for help with implementation.

If this is your first time using the CertCapture SDK, plan your implementation before you begin installation


The GenCert API functionality is delivered through a JavaScript “script include” hosted by CertCapture. You need to reference this Javascript tag on any page that uses the API. Some basic understanding of JavaScript and custom scripting is required in order to properly process callback actions to customize functionality.

In addition to the Javascript tag, a CertCapture registration is required. This registration consists of:

  1. Client ID - Identifier for the client that the API connects to, located in your CertCapture account at Settings > Company Settings > Company Details > Company Information.
  2. Registration Key - A specific registration key assigned per API instance, located in your CertCapture account at Settings > Company Settings > Company Details > Webportal Registration.

Insert the JavaScript tag

In order to install the CertCapture E-Commerce SDK, insert a JavaScript tag into your application’s webpage. This lets your website request and receive information from the CertCapture's GenCert technology, and is typically done by your company’s web developer.

Include this JavaScript tag on any application page that requires use of the form:

<script language="JavaScript" src="[client id]&key=[registration key]">
  • Cid - Identifier for the client that the API connects to
  • Key - The registration key assigned per API instance, located in your CertCapture account at Settings > Company Settings > Company Details > Webportal Registration

Initialize the form

Once you've added the Javascript tag to a page, activate the form with an initialization JavaScript either via a body.onload trigger or a manual trigger. If it's manually triggered, a custom body.onload function must be written to ensure that the script source is completely downloaded before an attempt is made to initialize or generate the form.

The GenCert.init function creates a new certificate generation form object tied to a parent DOM element supplied by <container>. This form is initially dormant until the show() function makes it visible. Specify the DOM object and JSON style parameter in the function, based on the example below.

GenCert.init(container, options)

  • Container - DOM object selected to be the form parent
  • Options - JSON style parameter object (option parameters below)

There are a number of options that you can use to provide pre, post, and callback functionality. A customer number and certificate zone must be provided for full functionality. This can be included in the constructor options or by specifically calling the setCustomerNumber() and setShipZone()functions.

Use functions to construct a script

Use the functions in this section to construct a certificate form. The following callback functions will trigger automatically if defined:

Callback functions (triggered automatically if defined)
onInit After constructor has finished loading
beforeShow Called before the form is shown
afterShow Called after the form is shown
beforeValidate Before form validation
onValidateSuccess After form validation success, before submit
onValidateFailure After form validation failure
onCertSuccess After submission, when certificate is successful.  Access the generated certificate id with "GenCert.certificateIds"
onCertFailure After submission, when certificate is failure
onCancel User cancels the certificate generation process
onManualSubmit Called when a Manual Submit zone/template is chosen
onNotNeeded Called when a Zone that does not charge sales tax is chosen
onUpload Called when a document is uploaded.  Access the generated certificate id with "GenCert.certificateIds"

The following callback functions are common functions that should be overridden for custom website behavior:

Callback functions (Important Behaviors)
onCertSuccess This callback is usually overridden to perform a customized action such as user navigation after a certificate is successfully created
onCancel This callback should generally be used to reinitialize GenCert or provide user navigation
onManualSubmit This callback should generally be used to reinitialize GenCert or navigate the user elsewhere

The following callback functions relate to customer data that can be populated in your form:

Customer data (Prefilled customer data - inner JSON object with string data fields)

The following functions relate to customer certificates and shipping zones:

Certificate data (syntax and description)

certificate_number String identifying customer number or unique identifier
ship_zone String identifying exposure zone where a certificate is needed.  Parameter should be a valid US or Canadian state/province in proper case, ex: ('California').  Does not accept lower case or upper case names.

The following functions allow greater customization of the form before, during, and after submission: 

Additional options and functions
submit_to_stack Defaults to false. Sends certificate to be validated via data entry
preview Defaults to false. Allows user to quickly view the generated certificate for printing purposes. Certificate is not generated in CertCapture
customer_list Defaults to false. Append a page to the generated certificate PDF that includes "Customer Number", "Customer Name", and "Customer Address" of each customer associated with the certificate. Must be called at initialization of GenCert API.
hide_sig Defaults to false. Signature not required. Certificate get sgenerated in CertCapture
upload_only Defaults to false.  Allows uploading an existing prefilled certificate only.
fill_only This option disables upload. A certificate can only be filled via form submission.
show_files Shows a link to download the certificate after the process has been completed.
setCustomerData(customer) Sets form prefilled with customer data. Function must follow the standard convention below:
GenCert.setCustomerNumber('CustomerTestGencert4'); // create customer
customer = new Object(); = 'TEST NAME';
customer.address1 = '1300 EAST CENTRAL'; = 'San fransisco';
customer.state = 'CA'; = 'US'; = '89890';
setCustomerNumber(custnum) Sets the form unique identifier for customer number, to identify the customer to which the certificate should be applied. Parameter custnum should be an alphanumeric unique identifier for the customer filling out the form. The customer number must be supplied via either the constructor options or this function. 
setShipZone(zone) Sets the zone to which the transaction is shipping and/or where the certificate would apply (this is NOT the customer’s ShipTo state). Parameter state should be a valid US or Canadian state/province in proper case, ex: ('California').  Does not accept lower case or upper case names.
The ship zone must be supplied via either the constructor option or this function.
show() Shows the form in the parent container.
hide() Hides the form in the parent container.

Example script


        <!-- Please note: You will need to input your client id and registration key in
             the call below for this example to work
        <script src="<client_id>&key=<registration_key>"></script>
        <div id="form_container"></div>
            GenCert.init(document.getElementById("form_container"), {

                // Set customer and zone information to pre-determine form
                // The zone and customer must set to start the process!!!
                ship_zone: 'New York',
                customer_number: '123456',

If you have any questions or concerns about the GenCert API, contact your Customer Account Manager (CAM) or Avalara Support.