As part of the process of configuring tax exemptions, you can set a customer's , along with arrays of and
Customer type
For details on how a use the type to calculate taxes, refer to the page.
Tax identifiers (legacy)
In versions 2020-12-17 and earlier, use the legacy features described in this section to manage tax identifiers. If you're on versions 2021-02-23 and later, refer to the page.
Some customers have tax identifiers that allow them to purchase zero-rated goods. If you want customers to apply tax identifiers to their purchases, your integration must first . Once that operation is successfully completed, Digital River automatically attaches the tax identifier to the transaction whenever the customer creates an applicable .
Adding tax identifiers to customers
When you or , you can add one or more taxIdentifiers[]. For each tax identifier, you want to add, specify a type and a value. The typically consist of a lowercase, two-letter country code. This value is dependent on the format used in each country.
You can use the to validate customer-supplied data.
The following shows how to add multiple tax identifiers in a request:
Usually, customers who want to use a tax certificate must be a government agency, a non-profit organization, or a product reseller based in the United States.
In the US, almost all product end users are taxed. The primary exceptions are government agencies and not-for-profits. Businesses are typically only tax-exempt when reselling a product.
If we determine that a customer's document isn't a valid, state-accepted exemption certificate, we mark the account as in review. While in this state, certificates can't be used to make tax-exempt purchases.
We then email the customer to request additional documentation. If the customer fails to provide a valid certificate, we send another follow-up email. If that request doesn't produce the necessary documentation, we move the certificate into an unapproved state. This means it won't be applied to future transactions.
On your site, we recommend that you inform customers that they might receive a follow-up email from Digital River requesting more information about their tax certificate.
Collecting tax certificate information
If your site intends to offer tax-exempt purchases, provide a form for customers to enter their certificate information. The form must contain fields that collect:
The name of the company/organization/agency that was issued the tax exemption
The name of the tax authority (i.e., the US state) that issued the certificate
The start and end dates of the tax exemption
You'll also need to allow customers to upload a copy of their certificate. Restrict the format of the uploaded file to PDF, JPG, or PNG and its size to 10 MB or less.
The companyName should indicate the name of the company or organization granted the tax exemption.
Tax authority
Start and end dates
The startDate and endDate values correspond to the issue and expiration dates of the tax certificate, respectively.
Tax certificates can be difficult to interpret. As a result, your customers might be unable to determine appropriate input dates. If this is the case, define startDate as the first date of the current month and endDate as the last date of the current month. This allows us time to review the certificate, determine its validity, and set the applicable dates.
A can't have multiple taxIdentifiers[] of the same type. So, if you'd like to attach a new tax identifier to a with the same type as a saved tax identifier, you must first delete the existing object.
For a complete list, refer to the section on the page
You can build your integration so with can make tax-exempt purchases.
To configure certificates for use in , you must:
Digital River also allows you to .
In the Digital River APIs, tax certificates can only be used in and . Additionally, the record must contain a valid taxCertificates[] whose matches the transaction's shipTo.address.state or billTo.address.state. If the purchase contains , Digital River compares taxAuthority to . In transactions that only contain , we compare taxAuthority to .
For example, the following has . Since the taxAuthority of one is MN and the other is WI, if this customer requests to have physical products shipped to Minnesota or Wisconsin, that transaction is tax-exempt. However, if the customer specifies a shipping address other than these two states, Digital River applies taxes.
Since Digital River is the , we subject a taxCertificates[] to a verification process. When customers supply their certificate during a checkout, we issue a temporary exemption for that transaction.
On the other hand, if our review determines that a certificate is valid, we automatically apply a tax exemption to all future . However, once the tax certificate's elapses, that exemption no longer applies.
No methods currently exist to query the APIs and determine the status of a tax certificate. Additionally, at this time, you can't subscribe to that notify you when a certificate's state has been updated.
Certificates of exemption must be addressed to Digital River. This is because we act as the . The correct address depends on the that is facilitating the transaction. So, during the checkout process, use sellingEntity.id or sellingEntity.name to determine the appropriate address disclosure to display to customers:
After you collect the document, use it to .
Once customers upload their tax certificate, submit a request to create a file in Digital River's system. In the request, make sure you define and set to tax_document_customer_upload.
From the response, retrieve id and use it to .
After , pass the customer's unique identifier as a path parameter in a . In the body of the request, use taxCertificate to send the information your form collected, as well as the identifier of the file.
Since tax certificates only apply to US-based customers, taxAuthority corresponds to the issuing state. The value you assign should be formatted to conform to the . These are the same abbreviations used in the .
In the request, make sure startDate and endDate adhere to the .
Retrieve the identifier of the that you created and use it to define fileID.
Once you , send a request and parse the response to verify the object has been successfully added to taxCertificates[].
You can only send one taxCertificate in a or request. But a customer can have multiple taxCertificates[].
At checkout-time, Digital River determines which (if any) are .
