System status
Search…
⌃K
Links

Managing tax identifiers

Learn how to manage tax identifiers.
Specifying a customer's type, as well as adding any tax identifiers associated with the customer, allows you to attach this data in a cart and helps ensure that Digital River's tax computations are accurate.

Customer type

Use the customerType parameter to differentiate between business and individual customers. Specifying a customer's type, as well as adding any tax identifiers associated with a customer, allows you to pass this data to a cart and helps ensure that Digital River's tax computations are accurate. See Attaching a tax identifier to a cart to learn how to set the customer's type.

Attaching a tax identifier to a cart

You must attach the tax identifier to the cart before you can use the source.
To attach a tax identifier, create a cart.
Optional. Send a GET /v1/shopper/me/carts/active/tax-registrations/schema request to get the tax-registrations JSON schema. You can use this schema when attaching the tax identifier to the cart.
Schema response body
{
"$schema": http://json-schema.org/draft-04/schema#,
"id": https://dispatch-test.digitalriver.com:443/cart-api/active/tax-registrations/schema,
"oneOf": [
{
"type": "object",
"title": "Individual",
"additionalProperties": false,
"required": [
"customerType"
],
"properties": {
"customerType": {
"type": "string",
"readOnly": true,
"enum": [
"I"
]
},
"taxRegistrations": {
"type": "array",
"title": "Tax Registrations",
"minItems": 1,
"maxItems": 1,
"items": [
{
"$ref": "#/definitions/CPF"
}
]
},
"companyId": {
"type": "string"
},
"siteId": {
"type": "string"
}
}
},
{
"type": "object",
"title": "Business",
"additionalProperties": false,
"required": [
"customerType"
],
"properties": {
"customerType": {
"type": "string",
"readOnly": true,
"enum": [
"B"
]
},
"taxRegistrations": {
"type": "array",
"title": "Tax Registrations",
"minItems": 2,
"maxItems": 2,
"items": [
{
"$ref": "#/definitions/CNPJ"
},
{
"$ref": "#/definitions/IE"
}
]
},
"companyId": {
"type": "string"
},
"siteId": {
"type": "string"
}
}
}
],
"definitions": {
"CPF": {
"type": "object",
"additionalProperties": false,
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"readOnly": true,
"enum": [
"CPF"
]
},
"value": {
"type": "string",
"title": "CPF",
"description": "Digite seu número CPF individual. O número deve ter 11 dígitos e ser inserido sem espaços, períodos ou hifens como 12345678901.",
"pattern": "^[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}$"
}
}
},
"IE": {
"type": "object",
"additionalProperties": false,
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"readOnly": true,
"enum": [
"IE"
]
},
"value": {
"type": "string",
"title": "Inscrição Estadual (IE)",
"description": "Por favor, insira a Inscrição Estadual da sua empresa. O número deve ter 8-13 dígitos e ser inserido sem espaços, períodos ou hifens como 12345678, 1234567890123 ou ISENTO. Para encontrar a sua Inscrição Estadual, visite o site SINTEGRA.",
"pattern": "^[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}$,^[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}$,^[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}$,^[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}$,^[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}$,^[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}$,^[Ii]{1}[Ss]{1}[Ee]{1}[Nn]{1}[Tt]{1}[Oo]{1}$"
}
}
},
"CNPJ": {
"type": "object",
"additionalProperties": false,
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"readOnly": true,
"enum": [
"CNPJ"
]
},
"value": {
"type": "string",
"title": "CNPJ",
"description": "Digite o número CNPJ da sua empresa. O número deve ter 14 dígitos e ser inserido sem espaços, períodos ou hifens como 12345678901234.",
"pattern": "^[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}[0-9]{1}$"
}
}
}
},
"liveMode": false
}
Send a POST /v1/shopper/me/carts/active/tax-registrations request to attach the tax identifier to the cart. The following examples show the request body or response for customerType with the value of B for the business shopper and I for the individual shopper. You determine the value for the customerType enumerations in the schema when you attach it to the cart.
Tax-registrations response body for Business shopper
Tax registrations response body for Individual shopper
{
"customerType": "B",
"taxRegistrations": [
{
"key": "CNPJ",
"value": "77844699000109"
},
{
"key": "IE",
"value": "ISENTO"
}
]
}
{
"customerType": "I",
"taxRegistrations": [
{
"key": "CPF",
"value": "03927107492"
}
]
}
​
409 Not Found
{
"errors": [
{
"code": "vat-exemption-failure",
"subcode": "vat-exemption-unavailable",
"description": "Tax Exemption Rest of the World is not enabled on this site."
}
]
}
Optional. Send a GET /v1/shopper/me/carts/active request to confirm the tax information is present. The following examples show the response for customerType with the value of B for a business shopper and I for an individual shopper.
Active response body for a Business shopper
Active response body for an Individual shopper
JSO{
"cart": {
...
"pricing": {
"subtotal": {
"currency": "BRL",
"value": 10
},
"subtotalWithDiscount": {
"currency": "BRL",
"value": 10
},
"discount": {
"currency": "BRL",
"value": 0
},
"shippingAndHandling": {
"currency": "BRL",
"value": 0
},
"importTaxAndDuty": {
"currency": "BRL",
"value": 0
},
"tax": {
"currency": "BRL",
"value": 1.38
},
"orderTotal": {
"currency": "BRL",
"value": 11.38
},
"formattedSubtotal": "10,00 BRL",
"formattedSubtotalWithDiscount": "10,00 BRL",
"formattedDiscount": "0,00 BRL",
"formattedShippingAndHandling": "0,00 BRL",
"formattedImportTaxAndDuty": "0,00 BRL",
"formattedTax": "1,38 BRL",
"formattedOrderTotal": "11,38 BRL"
},
...
"customerType": "B",
"taxRegistrations": [
{
"key": "CNPJ",
"value": "77844699000109"
},
{
"key": "IE",
"value": "ISENTO"
}
}
}
​
{
"cart": {
...
"pricing": {
"subtotal": {
"currency": "BRL",
"value": 10
},
"subtotalWithDiscount": {
"currency": "BRL",
"value": 10
},
"discount": {
"currency": "BRL",
"value": 0
},
"shippingAndHandling": {
"currency": "BRL",
"value": 0
},
"importTaxAndDuty": {
"currency": "BRL",
"value": 0
},
"tax": {
"currency": "BRL",
"value": 1.38
},
"orderTotal": {
"currency": "BRL",
"value": 11.38
},
"formattedSubtotal": "10,00 BRL",
"formattedSubtotalWithDiscount": "10,00 BRL",
"formattedDiscount": "0,00 BRL",
"formattedShippingAndHandling": "0,00 BRL",
"formattedImportTaxAndDuty": "0,00 BRL",
"formattedTax": "1,38 BRL",
"formattedOrderTotal": "11,38 BRL"
},
...
"customerType": "I",
"taxRegistrations": [
{
"key": "CPF",
"value": "03927107492"
}
]
}
}
​
Apply the source to the cart using one of the following options:
The following example shows the response body for the cart.
Submit cart response body
{
"submitCart": {
"order": {
"uri": https://dispatch-test.digitalriver.com/v1/shoppers/me/orders/997463190080,
"id": 997463190080,
"submissionDate": null,
"displayName": "Novo pedido",
"locale": "pt_BR",
"optIn": "false",
"testOrder": "false",
"taxExempt": "false",
"businessEntityCode": "DR_BRAZIL-ENTITY",
"orderState": "Source Pending Redirect",
"orderStateDetails": {
"description": null,
"settled": {
"currency": "BRL",
"value": 0
},
"refunded": {
"currency": "BRL",
"value": 0
}
}
},
"lineItems": {
"lineItem": [
{
"id": 997502760080,
"quantity": 1,
"product": {
"uri": https://dispatch-test.digitalriver.com/v1/shoppers/me/products/328207600,
"displayName": "Download Product - Klarna",
"thumbnailImage": null
},
"lineItemState": "Source Pending Redirect",
"lineItemStateDetails": {
"description": null,
"backOrdered": 0,
"shipped": 0,
"returned": 0,
"pendingReturn": 0
},
"pricing": {
"listPrice": {
"currency": "BRL",
"value": 10
},
"listPriceWithQuantity": {
"currency": "BRL",
"value": 10
},
"salePrice": {
"currency": "BRL",
"value": 10
},
"salePriceWithQuantity": {
"currency": "BRL",
"value": 10
},
"formattedListPrice": "10,00 BRL",
"formattedListPriceWithQuantity": "10,00 BRL",
"formattedSalePrice": "10,00 BRL",
"formattedSalePriceWithQuantity": "10,00 BRL",
"totalDiscountWithQuantity": {
"currency": "BRL",
"value": 0
},
"formattedTotalDiscountWithQuantity": "0,00 BRL",
"productTax": {
"currency": "BRL",
"value": 1.38
},
"shippingTax": {
"currency": "BRL",
"value": 0
},
"feeTax": {
"currency": "BRL",
"value": 0
},
"taxRate": 0.1215,
"discountDescription": "empty",
"importTax": {
"currency": "BRL",
"value": 0
},
"formattedImportTax": "0,00 BRL",
"importDuty": {
"currency": "BRL",
"value": 0
},
"formattedImportDuty": "0,00 BRL"
},
"downloads": {},
"digitalRights": {}
}
]
},
"billingAddress": {
"id": "billingAddress",
"firstName": "Zachariah",
"lastName": "Harris",
"companyName": "Digital River",
"line1": "1067 Rua Coronel Quirino",
"line2": null,
"line3": null,
"city": "Centro",
"countrySubdivision": "SP",
"postalCode": "13025-002",
"country": "BR",
"countryName": "Brazil",
"phoneNumber": "246-838-8386",
"countyName": null,
"emailAddress": [email protected],
"phoneticFirstName": null,
"phoneticLastName": null,
"division": null
},
"shippingAddress": {
"id": "shippingAddress",
"firstName": "Zachariah",
"lastName": "Harris",
"companyName": "Digital River",
"line1": "1067 Rua Coronel Quirino",
"line2": null,
"line3": null,
"city": "Centro",
"countrySubdivision": "SP",
"postalCode": "13025-002",
"country": "BR",
"countryName": "Brazil",
"phoneNumber": "246-838-8386",
"countyName": null,
"emailAddress": [email protected],
"phoneticFirstName": null,
"phoneticLastName": null,
"division": null
},
"shippingMethod": {},
"taxInclusive": "false",
"landedCostState": "NOT_ELIGIBLE",
"pricing": {
"subtotal": {
"currency": "BRL",
"value": 10
},
"subtotalWithDiscount": {
"currency": "BRL",
"value": 10
},
"discount": {
"currency": "BRL",
"value": 0
},
"shippingAndHandling": {
"currency": "BRL",
"value": 0
},
"importTaxAndDuty": {
"currency": "BRL",
"value": 0
},
"tax": {
"currency": "BRL",
"value": 1.38
},
"orderTotal": {
"currency": "BRL",
"value": 11.38
},
"formattedSubtotal": "10,00 BRL",
"formattedSubtotalWithDiscount": "10,00 BRL",
"formattedDiscount": "0,00 BRL",
"formattedShippingAndHandling": "0,00 BRL",
"formattedImportTaxAndDuty": "0,00 BRL",
"formattedTax": "1,38 BRL",
"formattedOrderTotal": "11,38 BRL"
},
"paymentMethod": {
"type": "boletoBancario",
"sourceId": "729bfe56-93cc-4759-a6b5-cd40236d126e",
"sourceClientSecret": "729bfe56-93cc-4759-a6b5-cd40236d126e_0984ec75-f984-4d6d-a634-fd7f6b8dd20e",
"boletoBancario": {
"documentCode": "23790001246004987209031123456704579990000010000",
"clientSecret": "729bfe56-93cc-4759-a6b5-cd40236d126e_0984ec75-f984-4d6d-a634-fd7f6b8dd20e",
"flow": "redirect",
"document": https://link/to/the/payment-slip.pdf,
"reusable": "false"
}
},
"paymentCompletionResources": {},
"termsOfSalesAcceptance": null,
"paymentSession": {
"id": "03aede3b-29d9-4aca-a5c2-9e3707861e68",
"clientSecret": "03aede3b-29d9-4aca-a5c2-9e3707861e68_9e4f4089-0823-4dac-8915-0b2e2f8b085b",
"status": "pending_redirect",
"redirectUrl": https://api.digitalriver.com:443/payments/redirects/797e027a-6a75-482e-b18f-2ba02beddda6?apiKey=pk_sys_704d8a7ccbc44f38ab218da662bc347b
},
"customerType": "I",
"taxRegistrations": [
{
"key": "CPF",
"value": "03927107492"
}
]
}
}
​

Removing a tax identifier from a cart

You can remove the tax identifier with or without specifying the cart identifier (cartId).

Removing a tax identifier with the cart identifier

To remove a tax identifier associated with a specific cart, use DELETE /v1/shoppers/me/carts/active/tax-registrations and include the cart identifier (cartId).
A successful response returns a 204 Not Content.

Removing a tax identifier without the cart identifier

To remove a tax identifier without a cart identifier, use DELETE /v1/shoppers/me/carts/active/tax-registrations.
A successful response returns a 204 Not Content.
409 Not Found
{
"errors": [
{
"code": "vat-exemption-failure",
"description": "Tax Exemption Rest of the World is not enabled on this site."
}
]
}
Previous
Providing a shipping discount
Next
Getting line items from a cart
Last modified 5mo ago