Avalara Developer Network Developer avaTax

8.2 - Exemption Certificate

An Exemption Certificate provides information about the buyer or customer, and their tax status. The two most common reasons why a customer might be exempt from collecting sales tax are

  • If they have a resale exemption certificate; or
  • If they have a direct pay certificate.

In these cases, the seller must document the exemption certificate and be able to produce information about that certificate in the event of an audit. The AvaTax Certificate APIs provide an easy way to manage exemption certificates - and they will automatically link to your CertCapture and CertExpress accounts! Please note that the end points discussed here only work if you have a CertCapture linked to your AvaTax account. If you are calling the sandbox endpoints then you will be interacting with the CertCapture sandbox environment. This will not interact with customers and certificates you add directly to your admin console.

Exemption Certificate User Interface

In the B2B world, salespeople need to enter exemption certificates all the time! Let’s make their user interface as easy as possible. Our goals are to:

  • Help the salesperson find the right Customer record.
  • Tell the salesperson whether the Customer has a Certificate on file.
  • If the salesperson sees that no Certificate is on file, we'll offer to send the customer a CertExpressInvite. CertExpress is a friendly web site that allows a customer to upload their exemption certificates directly - it can save the salesperson a lot of work!
  • If the salesperson wants to enter a Certificate while they're writing the sales invoice, your software can upload a PDF or JPG file directly to the API.

Exemption Certificates are commonly used in accounting software sales order entry, but are not often seen in a web storefront. A web storefront may want to provide a CertExpress link on their “Account Profile” page, for example.

Let’s look at the APIs available to help with each of these tasks.

Find or Create Customer Records

First, when a user fills out a SalesOrder or SalesInvoice document, they will be expected to select the customerCode of the customer placing the transaction. This customerCode value was first explained in Chapter 2 - Transactions - but here is where we discover how it works.

You can call the ListCustomers API to review a list of all the customers that have been entered. Many accounting systems prefer to provide a drop-down list of customers to choose from to help the user select the correct customer code. You might want to filter the list of customers by using the pagination features of the ListCustomers API to show a small number of customers at a time, or to allow the user to search for a customer by its name.

When a salesperson user selects a customer from the drop-down list, you may want to offer to load the customer’s address into the “ShipTo” address. This should be considered optional; many businesses have different shipping addresses for every transaction.

If the user doesn’t find the customer they want, you can call the CreateCustomers API to define a customer record directly in your user interface. This customer record is necessary in order to allow the customer to upload an exemption certificate.

Test Case - 8.2.1

Setup

  • Call CreateCustomers with the following options:
    • CompanyId set to the company ID of your DEVGUIDE company
    • CustomerCode set to RESELLER
    • Name set to Alice Example
    • Address set to 100 Ravine Lane, Bainbridge Island, WA 98110
    • Phone number set to 949 555 1212
    • Email address set to alice@example.org

Assertions

  • Customer record is created.
  • The record has a valid ID number.
  • The record has the customer code RESELLER.
  • [
      {
        "companyId": 12345,
        "customerCode": "RESELLER",
        "name": "Alice Example",
        "line1": "100 Ravine Lane",
        "city": "Bainbridge Island",
        "region": "WA",
        "postalCode": "98110",
        "country": "US",
        "phoneNumber": "(206) 555-1212",
        "emailAddress": "alice@example.org"
      }
    ]
    
Test Case - 8.2.2

Setup

  • Call CreateCustomers with the following options:
    • CompanyId set to the company ID of your DEVGUIDE company
    • CustomerCode set to NOCERTIFICATE
    • Name set to Bob Example
    • Address set to 1000 Main Street, Irvine, CA 92614
    • Phone number set to 949 555 1212
    • Email address set to bob@example.org

Assertions

  • Customer record is created.
  • The record has a valid ID number.
  • The record has the customer code NOCERTIFICATE.
  • [
      {
        "companyId": 12345,
        "customerCode": "NOCERTIFICATE",
        "name": "Bob Example",
        "line1": "1000 Main Street",
        "city": "Irvine",
        "region": "CA",
        "postalCode": "92614",
        "country": "US",
        "phoneNumber": "(949) 555-1212",
        "emailAddress": "bob@example.org"
      }
    ]
    

Certificate Status

When the user has selected a Customer and a ShipTo address for the transaction, you can check to see if the customer has an exemption certificate on file. We Once a customer has been selected, you can determine if the customer has an exemption certificate on file by calling ListValidCertificatesForCustomer using the Country and Region values from the ShipTo address. This API determines if a customer has an exemption certificate on file for that state.

If the API reports that a certificate is on file, you can call the DownloadCertificateImage API to retrieve a JPG or PDF of the certificate if the user wishes to preview the document.

If there is no certificate on file, you have two options to help the customer correctly report their certificate: you can send them an invitation to CertExpress, or you can allow the salesperson to upload a certificate image directly.

Test Case - 8.2.3

Setup

  • Call ListValidCertificatesForCustomer with the following options:
    • CustomerCode set to RESELLER
    • Country set to US
    • Region set to WA

Assertions

  • The result has the value Status: NotExempt.
  • The "Certificates" array in the result should be null.
  • GET /api/v2/companies/12345/customers/RESELLER/certificates/US/WA
    

CertExpress Invitations

The CertExpress website is a friendly, step-by-step method of reporting an exemption certificate. When you send an invitation to CertExpress, the customer making a purchase can visit the website on their own time and upload an exemption certificate and all the necessary information themselves.

Unfortunately, if the customer doesn’t respond to the CertExpress invitation quickly enough, the certificate won’t be available when they make a purchase; which is why a salesperson working hard to close a sale should always be able to choose either a CertExpress invitation or a direct upload of a certificate.

To send a CertExpress invitation to a customer, call CreateCertExpressInvitation. You will be asked to choose whether you want an email, download, or facsimile invitation. You can check the status of an invitation, or load an invitation you created previously, by calling ListCertExpressInvitations.

When creating a CertExpress invitation, you are free to select a cover letter from the available list of prebuilt cover letters. A cover letter will make an email or facsimile invitation more readable to a customer. You can either choose the value STANDARD_REQUEST, or call the ListCoverLetters API for a list of available prebuilt cover letters.

If you wish, you can display the hyperlink from the CertExpress invitation directly in your user interface. This allows a salesperson or customer to click the link and directly jump to the friendly introduction page on CertExpress so that they can begin uploading an exemption certificate directly.

Note that CertExpress invitations take a few moments to build a custom welcome page for your customer. When you create a CertExpress invite, check the status value of the result. If the value says “InProgress,” the welcome page is currently being built. You must delay for a few seconds and fetch back the invitation using GetCertExpressInvitation before the URL will be ready.

Test Case - 8.2.4

Setup

  • Call CreateCertExpressInvitation with the following options:
    • CustomerCode set to RESELLER
    • Recipient set to alice@example.org
    • CoverLetterTitle set to STANDARD_REQUEST
    • Delivery method set to EMAIL

Assertions

  • The status value of the invitation is InProgress.
  • The invitation has an ID number.
  • The recipient email address is alice@example.org.
  • The DeliveryMethod value of the result is set to "email".
  • [
      {
        "recipient": "alice@example.org",
        "coverLetterTitle": "STANDARD_REQUEST",
        "deliveryMethod": "Email"
      }
    ]
    

Uploading Certificates

If a salesperson chooses, they can take a snapshot or a scanned image of an exemption certificate and create one or more certificate directly using the CreateCertificates API. Certificates created by this API are available for exemption use after a short processing delay; please make sure to accommodate a short time between creating a certificate and using the certificate.

Test Case - 8.2.5

Setup

  • Call the CreateCertificates API using the following information:
    • SignedDate set to 2016-02-01
    • ExpirationDate set to 2020-12-31
    • Filename set to "exemptCert.pdf"
    • Valid set to "true"
    • ExemptPercentage set to 100
    • IsSingleCertificate set to false
    • ExemptReason set to EXPOSURE
    • Customers record
      • Set the CompanyId to the ID of your DEVGUIDE company
      • Set the CompanyCode value to RESELLER
    • Exposure Zone
      • Set the name of the exposure zone to Washington

Assertions

  • The exemption certificate is created and is valid in Washington
  • [
      {
        "signedDate": "2016-02-01",
        "expirationDate": "2020-12-31",
        "filename": "exemptCert.pdf",
        "valid": true,
        "exemptPercentage": 100,
        "isSingleCertificate": false,
        "exemptionReason": {
          "name": "EXPOSURE"
        },
        "customers": [
          {
            "companyId": 7370914,
            "customerCode": "RESELLER"
          }
        ],
        "exposureZone": {
          "name": "Washington"
        }
      }
    ]
    
Test Case - 8.2.6

Setup

  • Call ListValidCertificatesForCustomer with the following options:
    • CustomerCode set to RESELLER
    • Country set to US
    • Region set to WA

Assertions

  • The result has the value Status: Exempt.
  • The "Certificates" array in the result should contain the certificate created in step #1.
  • GET /api/v2/companies/12345/customers/RESELLER/certificates/US/WA
    

Testing Exemption Certificates

Once you have created a customer and uploaded an exemption certificate, you can create a transaction and apply this exemption certificate to the transaction:

Test Case - 8.2.7

Setup

  • In your connector, create the following transaction:
    • Transaction Type: SalesInvoice
    • Transaction Code: Chapter-8-Test-7
    • Document Date: 2017-06-15
    • CompanyCode, Date set to reasonable default values.
    • CustomerCode set for RESELLER
    • Addresses:
      • SingleLocation
      • 100 Ravine Lane NE, Bainbridge Island, WA, 98110
    • Line #1:
      • Amount 100
      • TaxCode P0000000
    • Calculate tax for your transaction using AvaTax.

Assertions

  • The tax for line 1 should be $0.00.
  • The Taxable amount for line 1 should be $0.00.
  • The Exempt amount for line 1 should be $100.00.
  • {
      "type": "SalesInvoice",
      "code": "Chapter-8-Test-1",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "RESELLER",
      "addresses": {
        "singleLocation": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100,
          "taxCode": "P0000000"
        }
      ]
    }
    
Test Case - 8.2.8

Setup

  • Repeat the above transaction:
    • All values are the same, except
    • Use the CustomerCode NOCERTIFICATE

Assertions

  • The tax for line 1 should be $0.00.
  • The Taxable amount for line 1 should be $100.00.
  • The Exempt amount for line 1 should be $0.00.
  • {
      "type": "SalesInvoice",
      "code": "Chapter-8-Test-1",
      "companyCode": "DEVGUIDE",
      "date": "2017-06-15",
      "customerCode": "NOCERTIFICATE",
      "addresses": {
        "singleLocation": {
          "line1": "100 Ravine Lane NE",
          "city": "Bainbridge Island",
          "region": "WA",
          "country": "US",
          "postalCode": "98110"
        }
      },
      "lines": [
        {
          "number": "1",
          "amount": 100,
          "taxCode": "P0000000"
        }
      ]
    }