LogoLogo
System Status
  • Digital River API
  • Getting started
  • Using our services
    • Local pricing
    • Item classification
    • Subscriptions
    • e-Invoicing
  • Integration options
    • Low-code checkouts
      • Implementing a Prebuilt Checkout
      • Implementing a Components checkout
      • Offering local pricing
      • Using a shipping endpoint
      • Processing subscription acquisitions
      • Adding custom fields
      • Offering store credit
      • Displaying policies and getting consent
      • Collecting e-invoice information
      • Handling completed checkout-sessions
    • Direct integrations
      • Standard flow
      • Building checkouts
        • Checking out guest and registered customers
        • Describing line items
          • Setting the price of an item
          • Managing items with shared SKU identifiers
        • Providing address information
        • Handling shipping choice
        • Tax identifiers
        • Applying a discount
        • Setting the customer type
        • Providing the IP address
        • Selecting a currency
        • Initiating a charge
        • Setting the purchase location
        • Configuring taxes
        • Accessing regulatory fee information
        • Localizing invoices and credit memos
        • Providing an upstream identifier
        • Applying store credit
        • Handling e-invoicing requirements
        • Landed cost
        • Tax calculation inputs
        • Selling entities
        • Payment sessions
        • Applying store credit (legacy)
        • Country specs
      • Building payment workflows
        • Handling redirect payment methods
        • Handling delayed payment methods
      • Subscription acquisitions
        • Handling subscription acquisitions
        • Handling external subscription acquisitions
        • Subscription information
      • Digital River coordinated fulfillments
        • Checking inventory levels
        • Using shipping quotes
        • Reserving inventory items
        • Managing a fulfillment order
        • Cancelling a fulfillment order
    • Connectors
  • Order management
    • Processing orders
    • Handling a rejected order
    • Accessing invoices and credit memos
    • Fulfilling goods and services
    • Capturing and cancelling charges
    • Payment reauthorizations
    • Handling reversals
      • Return basics
        • Digital River coordinated returns
        • Third party coordinated returns
      • Refund basics
        • Issuing refunds
        • Refunding asynchronous payment methods
      • Disputes and chargebacks
    • Customer notifications
    • Responding to events
      • Events
        • Key event types
        • All event types
      • Webhooks
        • Creating a webhook
        • Digital River API safelist
        • Digital River signature
      • Expanding events
      • Preventing webhooks from getting disabled
    • Distributor model
  • Subscription Management
    • Managing a subscription
    • Managing an external subscription
  • Payments
    • Payment solutions
      • Drop-in payments
        • How Drop-in payments work
        • Drop-in payments integration guide
      • DigitalRiver.js with Elements
        • Elements integration guide
        • Configuring payment methods
          • Configuring Afterpay
          • Configuring Alipay+ (cross-border)
          • Configuring Alipay (domestic)
          • Configuring Amazon Pay
          • Configuring Apple Pay
          • Configuring Bancontact
          • Configuring BNP Paribas
          • Configuring BLIK
          • Configuring CCAvenue
          • Configuring Clearpay
          • Configuring Credit Cards
          • Configuring FPX Online Banking
          • Configuring Google Pay
          • Configuring iDEAL
          • Configuring Klarna
          • Configuring Konbini
          • Configuring Online Banking (IBP)
          • Configuring Online Banking (Korea Bank Transfer)
          • Configuring PayCo
          • Configuring PayPal
          • Configuring SEPA Direct Debit
          • Configuring Trustly
          • Configuring Wire Transfer
          • Common payment sources
          • Common payment objects
    • Supported payment methods
      • Afterpay
      • Alipay (domestic)
      • Alipay+ (cross-border)
      • Amazon Pay
      • Apple Pay
      • Bancontact
      • BNP Paribas
      • BLIK
      • CCAvenue
      • Clearpay
      • Credit Cards
      • FPX Online Banking
      • Google Pay
      • iDEAL
      • Klarna
      • Konbini
      • Korea Bank Transfer (Online Banking)
      • Online Banking (IBP)
      • Pay with Installments France
      • PayCo
      • PayPal
      • PayPal Billing Agreement
      • PayPal Credit
      • PayPal Pay in 3
      • PayPal Pay in 4
      • PayPal RatenZahlung (Installment Payment)
      • SEPA Direct Debit
      • Trustly
      • Wire Transfer
    • Source basics
      • Managing sources
      • Handling credit card sources
      • Retrieving sources
    • Authorization declines
    • PSD2 and SCA
      • How to ensure SCA compliance
    • Payment testing scenarios
  • Product management
    • Product basics
    • Managing SKUs
    • Using product details
    • Grouping SKUs
    • SKU-inventory item pairs
    • Managing inventory items
    • Regulatory fees
      • What are regulatory fees?
        • Fees terminology
        • Regulatory fee management
        • European regulatory fees
        • Compliance obligations
        • WEEE directive requirements
        • Copyright directive requirements
        • Compliance challenges
      • Managing regulatory fees
  • Customer management
    • Customer basics
    • Creating and updating customers
    • Setting up tax exemptions
    • Recording a customer's request to be forgotten
  • Financial reporting
    • Financials basics
    • Sales transactions
      • Returning a list of sales transactions
      • Getting a sales transaction by ID
    • Sales summaries
      • Returning a list of sales summaries
      • Getting a sales summary by ID
    • Payouts
      • Returning a list of payouts
      • Getting a payout by ID
      • Get a list of transactions included in payout by ID
  • Developer resources
    • Digital River API reference
    • DigitalRiver.js reference
      • Including DigitalRiver.js
      • Initializing DigitalRiver.js
      • DigitalRiver object
      • Elements
        • Amazon Pay element
        • Apple Pay elements
        • Google Pay elements
        • IBAN element
        • iDEAL element
        • Konbini elements
        • Compliance element
        • Offline Refund elements
        • Online Banking elements
        • Tax Identifier element
        • Invoice attribute element
        • Delayed Payment Instructions element
        • PayPal elements
      • Guidelines for capturing payment details
      • Security
      • Digital River payment objects
      • Error types, codes, and objects
    • DigitalRiverCheckout.js reference
      • Including DigitalRiverCheckout.js
      • Initializing DigitalRiverCheckout.js
        • DigitalRiverCheckout configuration object
      • DigitalRiverCheckout object
        • Configuring Prebuilt Checkout
          • Performing actions
          • Defining experience
        • Components
          • Configuring components
          • Address component
          • Shipping component
          • Tax identifier component
          • Invoice component
          • Wallet component
          • Payment component
          • Compliance component
          • Order summary component
          • Thank you component
        • Rendering a checkout button
          • Performing actions on the checkout button
        • Determining the checkout's status
      • Accessing country and currency
    • DynamicPricing.js reference
    • Postman collection
  • administration
    • Sign in
    • Digital River Dashboard
      • Digital River Dashboard quick start guide
      • Key features
      • Reset your password
      • Test and production environments
      • Account
        • Adding an account
        • Switching accounts
        • Account access
      • Profile settings
        • Viewing your personal information
        • Changing your password
        • Updating your phone number
        • Enabling multi-factor authentication
      • Finance
        • Payouts
          • Viewing your payout details
          • Filtering your payouts
          • Exporting your payouts
        • Sales summaries
          • Viewing your sales summaries details
          • Filtering your sales summaries
          • Exporting your sales summaries
          • Exporting your sales summary details
        • Transactions
          • Viewing your transaction details
          • Filtering your transactions
          • Exporting your transactions
      • Order management
        • Orders
          • Searching for orders
          • Filtering your orders
          • Viewing the order details
          • Cancelling items
          • Fulfilling items
          • Downloading an invoice
          • Downloading a credit memo
          • Creating shipping labels
          • Recording a customer's request to be forgotten
          • Viewing returns and refunds
          • Creating a return
          • Accepting a return
          • Creating a refund
          • Viewing the order's timeline
        • Checkouts
          • Searching for checkouts
          • Filtering your checkouts
          • Viewing the checkout details
        • Prebuilt Checkout links
          • Generate Prebuilt Checkout links
          • View and work with Prebuilt Checkout link details
          • Add a customer during Prebuilt Checkout
          • Add a product during Prebuilt Checkout
      • Customers
        • Viewing customer details
        • Searching for customers
        • Filtering your customers
        • Editing account information
        • Adding a customer
        • Tax IDs and certificates
          • Adding a tax certificate
          • Adding a tax ID
          • Deleting a tax ID
        • Metadata
          • Adding metadata
          • Editing metadata
        • Manage subscriptions from the Customer Details page
        • Disabling a customer
        • Recording a customer's request to be forgotten
        • Deleting a customer
      • Catalog
        • SKUs
          • Viewing the SKU details
          • Searching for SKUs
          • Filtering your SKUs
          • Adding a SKU
          • Editing a SKU
          • Deleting a SKU
          • Adding a fee to a SKU
          • Editing a fee
          • Deleting a fee
          • Viewing product tariff codes
        • Managing customer subscriptions from Digital River Dashboard
      • Developers
        • API keys
          • Updating your API version
          • Getting your API keys
          • Changing the API version for your key
          • Creating a restricted key
          • Editing a restricted key
          • Deleting a restricted key
          • Rotating keys
        • Webhooks
          • Creating a webhook
          • Editing a webhook
          • Deleting a webhook
          • Rotating a webhook's secret
        • API logs
          • Filtering the API log
          • Viewing the API log details
        • Event logs
          • Filtering the events log
          • Viewing the event details
      • Settings
        • Users and roles
          • Roles
          • Searching for a user by name or email
          • Filtering your users and roles
          • Adding a user
          • Editing a user
          • Deleting a user
        • Prebuilt Checkout
        • Payment methods
          • Viewing your payment methods
          • Viewing payment method details
            • Enabling currencies
            • Managing countries
          • Enabling or disabling a payment method
  • General Resources
    • eCompass
    • eCompass documentation
    • Release notes
      • 2024
      • 2023
      • 2022
      • 2021
      • 2020
      • 2019
    • Standards and certifications
      • Certification process
      • Compliance requirements
      • Documentation requirements
      • Integration checklists
        • Admin portal
        • Products and SKUs
        • Customers and tax exemptions
        • Checkouts, payment sources, and orders
        • Disclosures, compliance statements, and emails
        • Fulfillments and cancellations
        • Customer portal
        • Order refund synchronization
        • Reversals
        • Error handling
      • Test and use cases
    • Commerce infrastructure
    • Versioning
    • Glossary
Powered by GitBook
On this page
  • Background
  • The tax identifier object
  • Unique identifier
  • Customer identifier
  • Type and value
  • States and triggered events
  • Verified name and address
  • Created and updated time
  • How we validate tax identifiers
  • When tax identifiers can be applied to checkouts
  • How we select tax identifiers
  • Managing tax identifiers
  • Validating tax identifiers
  • Creating tax identifiers
  • Deleting tax identifiers
  • Attaching tax identifiers to customers
  • Detaching tax identifiers from customers
  • Reassigning tax identifiers
  • Replacing a customer's tax identifier
  • Applying tax identifiers
  • Attaching tax identifiers to checkouts and invoices
  • Using tax identifiers in registered checkouts
  • Filtering applicable tax identifiers
  • Informing Digital River not to apply tax identifiers
  • Missing tax identifier notifications
  • Ensuring tax identifier information displays on invoices
  • Supported tax identifiers
  • Test tax identifiers
  1. Integration options
  2. Direct integrations
  3. Building checkouts

Tax identifiers

Learn how to manage and apply tax identifiers.

PreviousHandling shipping choiceNextApplying a discount

Last updated 2 months ago

In 2021-02-23 and later, use the features described on this page to manage tax identifiers. Once you upgrade to any of these versions, the tax identifiers you previously created through the will no longer be available. For assistance with migrating your data, contact us.

For versions 2020-12-17 and earlier, refer to the section on the .

The Digital River API uses tax identifiers for .

When you , we initiate a . Once the transitions to the appropriate , assuming it , it can be used to determine its taxability.

To , you can . Alternatively, you can and .

Your checkout flow should also consider that some . When a customer in one of these countries doesn't supply a tax identifier, we block the order and of the problem.

You can use our test tax identifiers when you're ready to evaluate your integration.

Background

In most value-added tax (VAT) schemes, domestic sales to business customers are assessed tax, and customers then get a credit for this tax paid when they complete their monthly or quarterly VAT return. Customers need the invoice to display their tax identifier to obtain this credit.

Alternatively, cross-border sales to business customers are not assessed tax in most VAT schemes. Instead, in a reverse charge practice, customers self-assess the tax while simultaneously getting a ta credit when they complete their monthly or quarterly VAT return. In these cases, the tax identifier is used to determine whether or not a reverse charge applies to a specific order.

Additionally, in a limited number of cases, tax identifiers are collected because they are for invoicing purposes.

The tax identifier object

In the Digital River APIs, a tax identifier is always represented by a . Additionally, the object will contain attributes that indicate its , its , and .

Sometimes, a tax identifier may include a , a , and an .

{
    "id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
    "createdTime": "2018-04-25T20:36:00Z",
    "updatedTime": "2018-04-28T22:16:00Z",
    "customerId": "5774321009",
    "type": "de",
    "value": "DE123456789",
    "state": "verified",
    "stateTransitions": {
        "verified": "2020-05-30T06:52:31.041Z",
        "pending": "2020-05-30T06:45:12.041Z"
    }
}

Unique identifier

Customer identifier

Type and value

States and triggered events

(1) When the tax identifier is...
(2) its state transitions to...
(3) and a...event is emitted.

under review by an external verification agency

pending

tax_identifier.pending

determined to be valid

verified

tax_identifier.verified

determined to be invalid

not_valid

tax_identifier.not_valid

Verified name and address

Created and updated time

How we validate tax identifiers

 {
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "value",
            "message": "Tax identifier 'IT00121239990xxxx' invalid."
        }
    ]
}

VIES no longer verifies VAT numbers from Great Britain.

If VIES indicates a tax identifier is not_valid, then we don't use it to determine an order's taxability.

We also apply validation algorithms for certain countries defined by the local authority that issued the number.

When tax identifiers can be applied to checkouts

For example, the following is a partial response to a POST/orders request. In this case, a tax identifier has been successfully applied. This is because the tax identifier's type is in agreement with the order's shipTo.country and the customer is a business entity.

{
  "id": "9182309218",
  ...
  "customerId": "5774321009",
  ...
  "shipTo": {
       "address": {
            ...
            "country": "GB"
        },
        ...
  },
  "customerType": "business",
  ...
  "taxIdentifiers": [{
        "id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
        "customerId": "5774321009",
        "type": "uk",
        "value": "GB123283536",
        "state": "verified",
        "stateTransitions": {
             "pending": "2020-05-13T11:00:00.000Z",
             "verified": "2020-05-15T16:00:00.000Z"
        },
        "verified_name": "A.C. Doyle Inc.",
        "verified_address": "Hudson House, 221B Baker Street, London",
        "createdTime": "2020-08-01T02:25:53Z",
        "updatedTime": "2020-08-01T05:47:21Z"
    }],
   ...
}

If you were to submit another POST /orders request with the same settings—the only difference is that in the new request, you specified ashipTo.country of DK (Denmark)—you'd receive a 409 Conflict response. Customers holding tax identifiers issued by one country can't apply them to orders shipped to a different country.

{
    "type": "conflict",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "taxIdentifiers",
            "message": "Tax identifiers of type 'uk' are not applicable to this order."
        }
    ]
}

How we select tax identifiers

If no tax identifiers are directly attached to a checkout or invoice and the customer is a guest, we don't use any tax identifiers when computing taxes.

Managing tax identifiers

Validating tax identifiers

When you configure the element with a payment session identifier, we filter out tax identifiers that do not apply to the transaction.

Creating tax identifiers

curl --location --request POST 'https://api.digitalriver.com/tax-identifiers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
    "type": "de",
    "value": "DE123456789"
}'
{
    "id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
    "createdTime": "2018-04-25T20:36:00Z",
    "updatedTime": "2018-04-28T22:16:00Z",
    "type": "de",
    "value": "DE123456789",
    "state": "pending",
    "stateTransitions": {
        "pending": "2020-05-30T06:45:12.041Z"
    }
}

Deleting tax identifiers

{
    "type": "not_found",
    "errors": [
        {
            "code": "not_found",
            "parameter": "id",
            "message": "Tax identifier '88b8fd94-14bd-4711-b381-9f73abef1546' not found."
        }
    ]
}

Attaching tax identifiers to customers

{
    "id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
    "customerId": "5774321009",
    "type": "uk",
    "value": "GB123283536",
    "state": "verified",
    "stateTransitions": {
         "pending": "2020-05-13T11:00:00.000Z",
         "verified": "2020-05-15T16:00:00.000Z"
    },
    "verified_name": "Royal Flushing Inc.",
    "verified_address": "Westminster, London SW1A 1AA, United Kingdom",
    "createdTime": "2020-08-01T02:25:53Z",
    "updatedTime": "2020-08-01T05:47:21Z"
}

Detaching tax identifiers from customers

Reassigning tax identifiers

{
    "type": "conflict",
    "errors": [
        {
            "code": "customer_not_updateable",
            "parameter": "customerId",
            "message": "You cannot replace a tax identifier's customer id."
        }
    ]
}

Replacing a customer's tax identifier

Applying tax identifiers

Attaching tax identifiers to checkouts and invoices

curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
    "customerId": 520984250336,
    ...
    "taxIdentifiers": [{
        "id": "2bba2529-97cb-4f0e-872f-5d97ac242cc0"
    }],
    ...
}'
{
    "id": "1003189166920",
    ....
    "customerId": "520984250336",
    ...
    "shipTo": {
        "address": {
            "line1": "Neuschwansteinstraße 20",
            "city": "Schwangau",
            "postalCode": "87645",
            "country": "DE"
        },
        "organization": "Wagner,LLC",
        ...
    },
    ...
    "customerType": "business",
    ...
    "sellingEntity": {
        "id": "DR_IRELAND-ENTITY",
        "name": "Digital River Ireland Ltd."
    },
    "taxIdentifiers": [
        {
            "id": "2bba2529-97cb-4f0e-872f-5d97ac242cc0",
            "customerId": "520984250336",
            "type": "de",
            "value": "DE231287923",
            "state": "verified",
            "stateTransitions": {
                 "pending": "2020-12-23T16:00:00.000Z",
                 "verified": "2020-12-23T16:00:00.000Z"
            },
            "verifiedName": "Checkpoint Security Services Ltd.",
            "verifiedAddress": "Friedrichstraße 43-45, 10117 Berlin, Germany",
            "createdTime": "2020-12-23T15:21:26Z",
            "updatedTime": "2020-12-23T15:21:26Z"
        }
    ],
    ...
}

For registered checkouts, any tax identifiers directly attached must be associated with the customer placing the order. If any are held by a different customer, the following 409 Conflict response is returned:

{
    "type": "conflict",
    "errors": [
        { 
            "code": "tax_identifier_in_use", 
            "parameter": "taxIdentifiers", 
            "message": "Tax identifier 'a6809a63-e6a9-4016-abbc-f33d19fccb5b' is attached to a different customer." 
        }
    ]
}

When using a customer's saved tax identifier, determine whether it exists. If you associate a tax identifier with a checkout, but the object has been deleted, we return the following error:

{
    "type": "conflict",
    "errors": [
        {
            "code": "not_found",
            "parameter": "id",
            "message": "Tax identifier 'a6809a63-e6a9-5029-abbc-f66d19fccbcb' not found."
        }
    ]
}

Using tax identifiers in registered checkouts

{
  "id": "9182309218",
  ...
  "customerId": "5774321009",
  ...
  "shipTo": {
       "address": {
            ...
            "country": "GB"
        },
        ...
  },
  "customerType": "business",
  ...
  "taxIdentifiers": [{
        "id": "a6809a63-e6a9-4016-abbc-f33d19fccb5b",
        "customerId": "5774321009",
        "type": "uk",
        "value": "GB000283536",
        "state": "verified",
        ...
    }],
   ...
}

Filtering applicable tax identifiers

{
    "type": "conflict",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "taxIdentifiers",
            "message": "Tax identifier '0c38e49d-79d1-44a0-b484-472ca3f20cf3' is not applicable."
        }
    ]
}

To avoid this, you can apply a filter using the tax identifier's applicability block. This data structure contains the following attributes:

Each attribute provides the required transaction values before a tax identifier can be successfully applied. In other words, the corresponding values in the checkout/invoice must be the same. If they're not, the tax identifier isn't applicable.

Saved tax identifiers

In the following example, a customer has two saved tax identifiers. Both are applicable for DR_IRELAND-ENTITY facilitated transactions. The first tax identifier, however, is only appropriate for purchases made by individuals in Italy, while the other can be used for business transactions in the Netherlands.

{
    "id": "541337030336",
    ...
    "taxIdentifiers": [
        {
            "id": "a19d26e7-8b7d-40e8-8358-b0a8b7203796",
            "state": "verified",
            "customerId": "541337030336",
            "type": "it_natural",
            "value": "IT5555555555",
            ...
            "applicability": [
                {
                    "country": "IT",
                    "entity": "DR_IRELAND-ENTITY",
                    "customerType": "individual"
                }
            ]
        },
        {
            "id": "6f5d4cb6-3c66-4a0b-a2aa-31cc25d3016d",
            "state": "verified",
            "customerId": "541337030336",
            "type": "nl",
            "value": "NL555555555555",
            ...
            "applicability": [
                {
                    "country": "NL",
                    "entity": "DR_IRELAND-ENTITY",
                    "customerType": "business"
                }
            ]
        }
    ],
    ...
    "type": "individual"
} 
{
    "id": "5d0f0213-d8ab-4cc7-b721-1df1567df758",
    ...
    "customerId": "541337030336",
    ...
    "shipTo": {
        "address": {
            "line1": "Via del Governo Vecchio 87",
            "city": "Roma",
            "postalCode": "00186",
            "country": "IT"
        },
        ...
    },
    "shipFrom": {
        "address": {
            "country": "GB"
        }
    },
    ...
    "customerType": "individual",
    "sellingEntity": {
        "id": "DR_IRELAND-ENTITY",
        "name": "Digital River Ireland Ltd."
    },
    ...
}

New tax identifiers

If it does, attach the tax identifier to the checkout. If not, inform the customer that they provided an ineligible tax identifier. In the following guest checkout, the customer-supplied tax identifier is not applicable because the customerType values do not agree.

{
    "id": "a56be3b9-bdc1-4188-8ee9-b20b12264e48",
    "state": "verified",
    ...
    "type": "nl",
    "value": "NL555555555555",
    ...
    "applicability": [
        {
            "country": "NL",
            "entity": "DR_IRELAND-ENTITY",
            "customerType": "business"
        }
    ]
}
{
    "id": "e4fca0fa-b303-4840-a912-e116abe746ca",
    ...
    "shipTo": {
        "address": {
            "line1": "Paulus Potterstraat 7",
            "city": "Amsterdam",
            "postalCode": "1071 DJ",
            "country": "NL"
        },
        ...
    },
    "shipFrom": {
        "address": {
            "country": "GB"
        }
    },
    ...
    "customerType": "individual",
    "sellingEntity": {
        "id": "DR_IRELAND-ENTITY",
        "name": "Digital River Ireland Ltd."
    },
    ...
}

Informing Digital River not to apply tax identifiers

For example, if a customer selects a saved tax identifier during the checkout process but later deselects it, you can submit the following POST/checkouts/{id} request to ensure it's not applied.

curl --location --request POST 'https://api.digitalriver.com/checkouts/183731720336' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
    "customerId": 520984250336,
    ...
    "taxIdentifiers": [],
    ...
}'

Missing tax identifier notifications

{
    "type": "conflict",
    "errors": [
        {
            "code": "additional_information_required",
            "parameter": "taxIdentifiers",
            "message": "Tax identifiers of type 'br_natural' are required with this selling entity."
        }
    ]
}

Ensuring tax identifier information displays on invoices

Supported tax identifiers

Ship to country
Tax id type
Customer Type
Selling Entity
Required?
Description

Australia

au

business

DR_IRELAND-ENTITY

No

ABN

Austria

at

business

DR_IRELAND-ENTITY

No

VAT Number

Bahrain

bh

business

DR_IRELAND-ENTITY

No

VAT Number

Belarus

by

business

DR_IRELAND-ENTITY

No

VAT Number

Belgium

be

business

DR_IRELAND-ENTITY

No

VAT Number

Brazil

br

business

DR_BRAZIL-ENTITY

Yes

Cadastro Nacional da Pessoa Jurídica

Brazil

br_ie

business

DR_BRAZIL-ENTITY

Yes

Inscrição Estadual

Brazil

br_natural

individual

DR_BRAZIL-ENTITY

Yes

Cadastro de Pessoas Físicas (individuals)

Bulgaria

bg

business

DR_IRELAND-ENTITY

No

VAT Number

Canada

ca

business

DR_IRELAND-ENTITY

No

Canadian GST

Canada

ca

business

C5_INC-ENTITY

No

GST Number

Chile

cl

individual

DR_IRELAND-ENTITY

No

RUT

Chile

cl

business

DR_IRELAND-ENTITY

No

RUT

Colombia

co

business

DR_IRELAND-ENTITY

No

VAT Number

Croatia

hr

business

DR_IRELAND-ENTITY

No

VAT Number

Cyprus

cy

business

DR_IRELAND-ENTITY

No

VAT Number

Czech Republic

cz

business

DR_IRELAND-ENTITY

No

VAT Number

Denmark

dk

business

DR_IRELAND-ENTITY

No

VAT Number

Estonia

ee

business

DR_IRELAND-ENTITY

No

VAT Number

Finland

fi

business

DR_IRELAND-ENTITY

No

VAT Number

France

fr

business

DR_IRELAND-ENTITY

No

VAT Number

Germany

de

business

DR_IRELAND-ENTITY

No

VAT Number

Greece

gr

business

DR_IRELAND-ENTITY

No

VAT Number

Hungary

hu

business

DR_IRELAND-ENTITY

No

VAT Number

Iceland

is

business

DR_IRELAND-ENTITY

No

VAT Number

India

in

business

DR_IRELAND-ENTITY

No

GSTIN

Indonesia

id

business

DR_IRELAND-ENTITY

No

NPWP

Ireland

ie

business

DR_IRELAND-ENTITY

No

VAT Number

Isle of Man

uk

business

DR_IRELAND-ENTITY

No

VAT Number

Isle of Man

uk

business

DR_UK-ENTITY

No

VAT Number

Italy

it

business

DR_IRELAND-ENTITY

No

VAT Number

Italy

it_cf

individual

DR_IRELAND-ENTITY

No

Codice Fiscal (individuals)

Italy

it_natural

individual

DR_IRELAND-ENTITY

No

VAT Number (individuals)

Japan

jp

business

DR_JAPAN-ENTITY

No

TIN

Japan

jp_offshore

business

DR_IRELAND-ENTITY

No

Consumption Tax ID (offshore)

Kenya

ke

business

DR_IRELAND-ENTITY

Yes

PIN

Korea

kr_offshore

business

DR_IRELAND-ENTITY

No

VAT Number (offshore)

Latvia

lv

business

DR_IRELAND-ENTITY

No

VAT Number

Lithuania

lt

business

DR_IRELAND-ENTITY

No

VAT Number

Luxembourg

lu

business

DR_IRELAND-ENTITY

No

VAT Number

Malaysia

my

business

DR_IRELAND-ENTITY

No

VAT Number

Malta

mt

business

DR_IRELAND-ENTITY

No

VAT Number

Mexico

mx_natural

individual

DR_IRELAND-ENTITY

No

RFC

Mexico

mx

business

DR_IRELAND-ENTITY

No

RFC

Monaco

fr

business

DR_IRELAND-ENTITY

No

VAT Number

Netherlands

nl

business

DR_IRELAND-ENTITY

No

VAT Number

New Zealand

nz

business

DR_IRELAND-ENTITY

No

GST ID

Norway

no

business

DR_IRELAND-ENTITY

No

VAT Number

Philippines

ph

business

DR_IRELAND-ENTITY

No

TIN

Poland

pl

business

DR_IRELAND-ENTITY

No

VAT Number

Portugal

pt

business

DR_IRELAND-ENTITY

No

VAT Number

Portugal

pt_nif

individual

DR_IRELAND-ENTITY

No

NIF

Romania

ro

business

DR_IRELAND-ENTITY

No

VAT Number

Russia

ru

business

DR_IRELAND-ENTITY

No

INN

Russia

ru_natural

business

DR_IRELAND-ENTITY

No

INN

Saudi Arabia

sa

business

DR_IRELAND-ENTITY

No

VAT Number

Singapore

sg

business

DR_IRELAND-ENTITY

No

VAT Number

Slovakia

sk

business

DR_IRELAND-ENTITY

No

VAT Number

Slovenia

si

business

DR_IRELAND-ENTITY

No

VAT Number

South Africa

za

business

DR_IRELAND-ENTITY

No

VAT Number

Spain

es

business

DR_IRELAND-ENTITY

No

VAT Number

Sweden

se

business

DR_IRELAND-ENTITY

No

VAT Number

Switzerland

ch

business

DR_IRELAND-ENTITY

No

VAT Number

Taiwan

tw

business

DR_TAIWAN-ENTITY

Yes

Unified Business Number

Taiwan

tw_offshore

business

DR_IRELAND-ENTITY

Yes

Unified Business Number (offshore)

Thailand

th

business

DR_IRELAND-ENTITY

No

VAT Number

Turkey

tr

business

DR_IRELAND-ENTITY

No

VAT Number

Ukraine

ua

business

DR_IRELAND-ENTITY

No

VAT Number

United Arab Emirates

ae

business

DR_IRELAND-ENTITY

No

VAT Number

United Kingdom

uk

business

DR_IRELAND-ENTITY

No

VAT Number

United Kingdom

uk

business

DR_UK-ENTITY

No

VAT Number

Test tax identifiers

Country

type

value

Belgium

be

BE0000000000, BE1234567890

Germany

de

DE000000000, DE123456789

Italy

it or it_natural

IT00000000000, IT12345678901

{
    "id": "3234adc5-4857-4e48-8190-5a7d36843b89",
    "state": "verified",
    "liveMode": false,
    "type": "it_natural",
    "value": "IT12345678901",
    "stateTransitions": {
        "verified": "2021-09-02T18:44:55Z"
    },
    "createdTime": "2021-09-02T18:44:55Z",
    "updatedTime": "2021-09-02T18:44:55Z",
    "applicability": [
        {
            "country": "IT",
            "entity": "DR_IRELAND-ENTITY",
            "customerType": "individual"
        }
    ]
}
{
    "id": "92d8984a-8c56-48a5-8cfd-c466ca8f3e62",
    "state": "verified",
    "verifiedName": "---",
    "verifiedAddress": "---",
    "liveMode": false,
    "type": "it",
    "value": "IT12345678901",
    "stateTransitions": {
        "verified": "2021-09-02T18:53:23Z"
    },
    "createdTime": "2021-09-02T18:53:23Z",
    "updatedTime": "2021-09-02T18:53:23Z",
    "applicability": [
        {
            "country": "IT",
            "entity": "DR_IRELAND-ENTITY",
            "customerType": "business"
        }
    ]
}

A tax identifier is always returned with a unique id. Besides using this identifier to and a tax identifier, you can use it to or .

The customerId is only returned when the tax identifier is .

The type attribute identifies the country that issued the tax identifier. The typically consist of a lowercase, two-letter country code. However, some countries have more than one and contain a suffix to the country code. For example, Brazil has tax identifiers with types of br, br_ie, and br_natural.

The value is assigned by the issuing country. Before , you can use the to help you validate its format. This element indicates if a tax identifier is required in the purchase country.

A tax identifier can be in a state of pending, not_valid, and verified. Its state is dependent on where it is in the .

Each state transition causes a corresponding to be emitted whose data.object consists of the tax identifier.

A tax identifier in any state can be or . Before taking either action, your integration should ideally wait to receive the tax_identifier.verified event. However, a tax identifier in either a pending or verified state is used to determine an order's taxability.

Additionally, as it moves from one state to another, an formatted date and time is returned in the stateTransitions hash table.

During the tax identifier , we sometimes can obtain the holder's verifiedName and verifiedAddress.

A tax identifier always contains a createdTime. When a tax identifier is , its or the are added, then the time these events occurred is reflected in the updatedTime field.

When a request is submitted, Digital River initiates a validation process. As part of this process, we always validate the format of a tax identifier, whatever its country of origin. Incorrectly formatted tax identifiers return the following error:

Before , you can .

For European Union tax identifiers, commonly known as Value Added Tax (VAT) numbers, we use the to validate the customer's data.

After a POST /tax-identifiers is submitted, Digital River provides VIES with the data submitted in the request. VIES, in turn, transmits our validation query to the relevant member state's database. The member state's reply to VIES indicates whether the number exists and, if so, whether it's valid. The reply may also include the . VIES then relays this information back to us.

If VIES successfully responds before the , then the transitions to either verified or not_valid . This causes either a tax_identifier.verified or tax_identifier.not_valid to fire. The tax identifier is immediately applied to the order if the number is verified.

In many situations, however, VIES responds slowly or is down for scheduled or unscheduled reasons. This means the tax identifier might not transition from pending to verified until after creation. We treat a pending tax identifier as being verified in these cases until we know otherwise. In other words, pending and verified tax identifiers are both used by Digital River to determine an taxability.

A tax identifier's information is displayed on , regardless of its state.

Before a tax identifier can be successfully applied to a , the , the , the , and the country (a country for or a country for ) must agree.

With a few , most countries only allow business customers to apply tax identifiers.

Digital River first searches for directly . This is true whether you're checking out a or a .

However, when it's a registered checkout and that that are applicable, and those tax identifiers are not yet attached, we apply them as well.

Before they are , we allow you to information provided by customers. Once validated, you can use the to , , , and them.

You can also and then later, if necessary, . To or tax identifiers, you must delete the existing object before creating a new one.

You can use the tax identifier element to validate the format entered by a customer and determine whether a tax identifier is required and applicable to the transaction. To create the element, you must combine the identifier, , and ship to/bill to returned in a or .

You use the method to create a tax identifier. In the request, you must specify both a . Once the request is submitted, we initiate a .

The following is an example 201 Created response. It doesn't contain a customerId because the tax identifier hasn't been attached to a customer yet. The of the tax identifier indicates it's still being .

You can delete a tax identifier by submitting a request that sends its unique identifier as a path parameter. A successful request returns a 204 No Content response. It also triggers a tax_identifier.deleted event and it may have been associated with.

Once a tax identifier is deleted, if you later attempt to , you'll get the following 404 Not Found error.

Once you've , you can use the POST /customers/{id}/tax-identifiers/{taxId} method to attach it to an existing customer. This request returns the and triggers a customer.tax_identifier.created event. The event's data.object also represents the tax identifier.

The customerId attribute is populated in the response since it's now associated with a customer. The following example response shows a British (uk) issued tax identifier in a . When the customer next makes an , this tax identifier will automatically apply to the order.

To disassociate a tax identifier from a customer, send a through the . A successful request means that when the customer creates registered checkouts in the future, this tax identifier will no longer be applied.

The same tax identifier object can't be attached to multiple customers. If you attempt to , but it's already attached to a different customer, you'll receive a 409 Conflict response.

In these cases, you must first , create a new object with an identical , and then assign it to the desired customer.

Customers can have multiple tax identifiers but not more than one of the same . So, if you want to attach a new tax identifier to a customer, but that customer already holds one with that type, you must first . Once you've consumed either the 204 No Content response or the tax_identifier.deleted event, your integration can and .

Once they are created, there are two ways to apply tax identifiers to a purchase. You can either . Or you can .

In either case, during the checkout process, we determine whether the and .

You should also ensure you pass the necessary information to correctly .

When checking out , you can attach tax identifiers directly to a checkout or invoice. You do this by using a POST /checkouts,POST /checkouts/{id}, or POST /invoices request and send the object's identifier in the taxIdentifiers array.

A successful response returns a checkout or invoice that contains an array of . The indicates whether it will be used to determine an order's taxability, depending on .

Before attaching a tax identifier, you should .

This information in this section is only applicable to 2021-03-23 and earlier of the Digital River APIs.

For more information, refer to on the customers page.

When you create a , we search for tax identifiers . If we locate any, they are automatically applied to the checkout or invoice and returned in its taxIdentifiers array.

You can send an empty taxIdentifiers array to .

For example, let's say a customer holds a tax identifier of type dk (Denmark) and another type uk (Great Britain). In a POST/checkouts request, you and specify a of GB(Great Britain).

In this case, only the uk tax identifier is returned in the response. This is because tax identifiers are not applied to purchases when the .

If you attach a tax identifier to the checkout and the are not met, you receive an error:

country: The ship-to country for or the bill-to country for

entity: The of the transaction

customerType: The making the purchase

The applicability block is especially useful with . But, if you decide not to , you can also use applicability with .

During , you can use applicability to filter customers' saved tax identifiers and display this filtered list to them on your site. Once the transaction's customer type is set and we've , make a request to retrieve the customer's saved tax identifiers.

In registered checkouts, you can send an empty taxIdentifiers array to .

Next, use the checkout's (or for digital goods), sellingEntity.id, and customerType, along with the corresponding values in each of the customer's applicability blocks to filter out the non-applicable tax identifiers.

After that, display this filtered list to the customer. Once the customer selects an option, .

If a registered or supplies new tax identifier information during checkout, send the necessary data in a request. You can then use applicability in the response to determine whether the checkout contains the matching country, selling entity, and customer type values.

We suggest .

When you want to inform us that no tax identifiers should be applied to a , submit a create or update request with an empty taxIdentifiers array. This indicates that none of the customer's should be used to determine the order's taxability.

On the other hand, not including thetaxIdentifiers array in a registered checkout has no effect. In this scenario, we any applicable tax identifiers saved to the customer's account.

In , customers are required to provide a valid tax identifier when conducting online transactions. If customers in these countries don't provide this information, Digital River blocks their orders from being placed.

During checkout, you can use the to determine whether a tax identifier is required in the customer's country.

As an example, let's say a POST /checkouts request specifies a of individual and a of BR (Brazil). In that same request, if no tax identifiers with a of br_natural are either or , you'll receive a 409 Conflict response.

After fulfilling an order and receiving the necessary events, you can . When a applies a tax identifier, the company name must be displayed on these invoices. To ensure this happens, you must set the organization parameter when for orders that contain .

The following table lists the combination of country, , , and that must be aligned before a tax identifier can be applied to an order.

As the table indicates, most countries don't require a tax identifier when purchasing online within their borders. For those that do, however, without first providing a valid tax identifier.

In the , the following pairs allow you to create tax identifiers:

The Italian values can be paired with either it or it_natural. The type you specify depends on whether you're to a test purchase made by an . Once you , you can always reference to determine its .

event
ISO8601
VAT Information Exchange System (VIES)
registered and guest customers
selling entity
type of customer
tax identifier element
associated with a customer
available types
tax identifier element
creating a tax identifier
verification process
attached directly to a checkout
associated with a customer
verification process
associated with a customer
state changes
holder's name and address
creating a tax identifier
use the tax identifier element to perform validation
holder's name and address
notable exceptions
customer has associated tax identifiers
attach tax identifiers to customers
detach them
reassign
replace
pending state
validated by an external agency
attach it to a customer
created a tax identifier
tax identifier
verified state
applicable purchase
associate a tax identifier with a customer
delete the tax identifier
type and value
type
delete the existing object
create the new tax identifier
attach it to the same customer
attach the tax identifier directly to a checkout or invoice
use tax identifiers in registered checkouts
tax identifier is applicable
notify you of missing tax identifiers
display the tax identifier on invoices
tax identifier objects
state of each tax identifier
how it is validated
determine whether it's applicable
instruct Digital River not to automatically apply tax identifiers
type and ship to country are not in agreement
necessary requirements
saved tax identifiers
use the tax identifier element as a filter
new tax identifiers
instruct Digital River not to automatically apply tax identifiers
attach that tax identifier to the transaction
using the tax identifier element to determine applicability
automatically apply
some countries
customers can't conduct transactions
individual or a business
applying the tax identifier
create a test tax identifier
applicability
appropriate use
invoices
Setting up tax exemptions page
tax assessment and invoicing purposes
create a tax identifier
validation process
tax identifier object
verification state
applies to the order
apply a tax identifier
attach it directly to a checkout or invoice
associate it with a customer
use it in registered checkouts
countries require tax identifiers
send a notification
required by a specific country’s tax authority
unique identifier
type and value
state
created time
customer identifier
verified name and address
updated time
event
tax identifier's state
selling entity
tax identifier type
selling entity
ISO 3166 country code
Checking out guest and registered
selling entity
tax ID type
attach a tax identifier to a checkout
associate it with a customer
applicable tax identifiers
attached to a checkout or invoice
applied to orders
validate the tax identifier
create
type and value
validation process
detaches the tax identifier from any customer
delete request
applicable
applicable
attached to that customer
POST/tax-identifiers
applicable tax identifiers
type
attached directly to the checkout
associated with the customer placing the order
type and value
verified
guest
registered customer
registered checkouts
registered checkout
guest customer
registered checkout
physical goods
digital goods
versions
test environment
retrieve
delete
POST /tax-identifiers
order
order's
Tax Identifiers API
retrieve
delete
search for
POST /tax-identifiers
DELETE /tax-identifiers/{id}
Tax Identifiers API
registered checkouts
assigned a selling entity
GET /customers/{id}
bill-to
physical goods
digital goods
checkout
associate this customer with the checkout
physical products
versions
Customers API
checkout
invoice
checkout is converted to an order
shipTo.country
billTo.country
share the generated invoice with customers
specifying a shipping address
ship-to
ship to country
ship-to country
ship to
payment session identifier
Tax identifiers (legacy)
customer type
business
customer type
business customer
customer type