Search…
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
1
{
2
"$schema": http://json-schema.org/draft-04/schema#,
3
"id": https://dispatch-test.digitalriver.com:443/cart-api/active/tax-registrations/schema,
4
"oneOf": [
5
{
6
"type": "object",
7
"title": "Individual",
8
"additionalProperties": false,
9
"required": [
10
"customerType"
11
],
12
"properties": {
13
"customerType": {
14
"type": "string",
15
"readOnly": true,
16
"enum": [
17
"I"
18
]
19
},
20
"taxRegistrations": {
21
"type": "array",
22
"title": "Tax Registrations",
23
"minItems": 1,
24
"maxItems": 1,
25
"items": [
26
{
27
"$ref": "#/definitions/CPF"
28
}
29
]
30
},
31
"companyId": {
32
"type": "string"
33
},
34
"siteId": {
35
"type": "string"
36
}
37
}
38
},
39
{
40
"type": "object",
41
"title": "Business",
42
"additionalProperties": false,
43
"required": [
44
"customerType"
45
],
46
"properties": {
47
"customerType": {
48
"type": "string",
49
"readOnly": true,
50
"enum": [
51
"B"
52
]
53
},
54
"taxRegistrations": {
55
"type": "array",
56
"title": "Tax Registrations",
57
"minItems": 2,
58
"maxItems": 2,
59
"items": [
60
{
61
"$ref": "#/definitions/CNPJ"
62
},
63
{
64
"$ref": "#/definitions/IE"
65
}
66
]
67
},
68
"companyId": {
69
"type": "string"
70
},
71
"siteId": {
72
"type": "string"
73
}
74
}
75
}
76
],
77
"definitions": {
78
"CPF": {
79
"type": "object",
80
"additionalProperties": false,
81
"required": [
82
"key",
83
"value"
84
],
85
"properties": {
86
"key": {
87
"type": "string",
88
"readOnly": true,
89
"enum": [
90
"CPF"
91
]
92
},
93
"value": {
94
"type": "string",
95
"title": "CPF",
96
"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.",
97
"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}quot;
98
}
99
}
100
},
101
"IE": {
102
"type": "object",
103
"additionalProperties": false,
104
"required": [
105
"key",
106
"value"
107
],
108
"properties": {
109
"key": {
110
"type": "string",
111
"readOnly": true,
112
"enum": [
113
"IE"
114
]
115
},
116
"value": {
117
"type": "string",
118
"title": "Inscrição Estadual (IE)",
119
"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.",
120
"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}quot;
121
}
122
}
123
},
124
"CNPJ": {
125
"type": "object",
126
"additionalProperties": false,
127
"required": [
128
"key",
129
"value"
130
],
131
"properties": {
132
"key": {
133
"type": "string",
134
"readOnly": true,
135
"enum": [
136
"CNPJ"
137
]
138
},
139
"value": {
140
"type": "string",
141
"title": "CNPJ",
142
"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.",
143
"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}quot;
144
}
145
}
146
}
147
},
148
"liveMode": false
149
}
Copied!
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 business shopper and I for 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
1
{
2
"customerType": "B",
3
"taxRegistrations": [
4
{
5
"key": "CNPJ",
6
"value": "77844699000109"
7
},
8
{
9
"key": "IE",
10
"value": "ISENTO"
11
}
12
]
13
}
Copied!
1
{
2
"customerType": "I",
3
"taxRegistrations": [
4
{
5
"key": "CPF",
6
"value": "03927107492"
7
}
8
]
9
}
10
Copied!
409 Not Found
1
{
2
"errors": [
3
{
4
"code": "vat-exemption-failure",
5
"subcode": "vat-exemption-unavailable",
6
"description": "Tax Exemption Rest of the World is not enabled on this site."
7
}
8
]
9
}
Copied!
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 Business shopper
Active response body for Individual shopper
1
{
2
"cart": {
3
...
4
"pricing": {
5
"subtotal": {
6
"currency": "BRL",
7
"value": 10
8
},
9
"subtotalWithDiscount": {
10
"currency": "BRL",
11
"value": 10
12
},
13
"discount": {
14
"currency": "BRL",
15
"value": 0
16
},
17
"shippingAndHandling": {
18
"currency": "BRL",
19
"value": 0
20
},
21
"importTaxAndDuty": {
22
"currency": "BRL",
23
"value": 0
24
},
25
"tax": {
26
"currency": "BRL",
27
"value": 1.38
28
},
29
"orderTotal": {
30
"currency": "BRL",
31
"value": 11.38
32
},
33
"formattedSubtotal": "10,00 BRL",
34
"formattedSubtotalWithDiscount": "10,00 BRL",
35
"formattedDiscount": "0,00 BRL",
36
"formattedShippingAndHandling": "0,00 BRL",
37
"formattedImportTaxAndDuty": "0,00 BRL",
38
"formattedTax": "1,38 BRL",
39
"formattedOrderTotal": "11,38 BRL"
40
},
41
...
42
"customerType": "B",
43
"taxRegistrations": [
44
{
45
"key": "CNPJ",
46
"value": "77844699000109"
47
},
48
{
49
"key": "IE",
50
"value": "ISENTO"
51
}
52
}
53
54
}
55
Copied!
1
{
2
"cart": {
3
...
4
"pricing": {
5
"subtotal": {
6
"currency": "BRL",
7
"value": 10
8
},
9
"subtotalWithDiscount": {
10
"currency": "BRL",
11
"value": 10
12
},
13
"discount": {
14
"currency": "BRL",
15
"value": 0
16
},
17
"shippingAndHandling": {
18
"currency": "BRL",
19
"value": 0
20
},
21
"importTaxAndDuty": {
22
"currency": "BRL",
23
"value": 0
24
},
25
"tax": {
26
"currency": "BRL",
27
"value": 1.38
28
},
29
"orderTotal": {
30
"currency": "BRL",
31
"value": 11.38
32
},
33
"formattedSubtotal": "10,00 BRL",
34
"formattedSubtotalWithDiscount": "10,00 BRL",
35
"formattedDiscount": "0,00 BRL",
36
"formattedShippingAndHandling": "0,00 BRL",
37
"formattedImportTaxAndDuty": "0,00 BRL",
38
"formattedTax": "1,38 BRL",
39
"formattedOrderTotal": "11,38 BRL"
40
},
41
...
42
"customerType": "I",
43
"taxRegistrations": [
44
{
45
"key": "CPF",
46
"value": "03927107492"
47
}
48
]
49
}
50
51
}
52
Copied!
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
1
{
2
"submitCart": {
3
"order": {
4
"uri": https://dispatch-test.digitalriver.com/v1/shoppers/me/orders/997463190080,
5
"id": 997463190080,
6
"submissionDate": null,
7
"displayName": "Novo pedido",
8
"locale": "pt_BR",
9
"optIn": "false",
10
"testOrder": "false",
11
"taxExempt": "false",
12
"businessEntityCode": "DR_BRAZIL-ENTITY",
13
"orderState": "Source Pending Redirect",
14
"orderStateDetails": {
15
"description": null,
16
"settled": {
17
"currency": "BRL",
18
"value": 0
19
},
20
"refunded": {
21
"currency": "BRL",
22
"value": 0
23
}
24
}
25
},
26
"lineItems": {
27
"lineItem": [
28
{
29
"id": 997502760080,
30
"quantity": 1,
31
"product": {
32
"uri": https://dispatch-test.digitalriver.com/v1/shoppers/me/products/328207600,
33
"displayName": "Download Product - Klarna",
34
"thumbnailImage": null
35
},
36
"lineItemState": "Source Pending Redirect",
37
"lineItemStateDetails": {
38
"description": null,
39
"backOrdered": 0,
40
"shipped": 0,
41
"returned": 0,
42
"pendingReturn": 0
43
},
44
"pricing": {
45
"listPrice": {
46
"currency": "BRL",
47
"value": 10
48
},
49
"listPriceWithQuantity": {
50
"currency": "BRL",
51
"value": 10
52
},
53
"salePrice": {
54
"currency": "BRL",
55
"value": 10
56
},
57
"salePriceWithQuantity": {
58
"currency": "BRL",
59
"value": 10
60
},
61
"formattedListPrice": "10,00 BRL",
62
"formattedListPriceWithQuantity": "10,00 BRL",
63
"formattedSalePrice": "10,00 BRL",
64
"formattedSalePriceWithQuantity": "10,00 BRL",
65
"totalDiscountWithQuantity": {
66
"currency": "BRL",
67
"value": 0
68
},
69
"formattedTotalDiscountWithQuantity": "0,00 BRL",
70
"productTax": {
71
"currency": "BRL",
72
"value": 1.38
73
},
74
"shippingTax": {
75
"currency": "BRL",
76
"value": 0
77
},
78
"feeTax": {
79
"currency": "BRL",
80
"value": 0
81
},
82
"taxRate": 0.1215,
83
"discountDescription": "empty",
84
"importTax": {
85
"currency": "BRL",
86
"value": 0
87
},
88
"formattedImportTax": "0,00 BRL",
89
"importDuty": {
90
"currency": "BRL",
91
"value": 0
92
},
93
"formattedImportDuty": "0,00 BRL"
94
},
95
"downloads": {},
96
"digitalRights": {}
97
}
98
]
99
},
100
"billingAddress": {
101
"id": "billingAddress",
102
"firstName": "Zachariah",
103
"lastName": "Harris",
104
"companyName": "Digital River",
105
"line1": "1067 Rua Coronel Quirino",
106
"line2": null,
107
"line3": null,
108
"city": "Centro",
109
"countrySubdivision": "SP",
110
"postalCode": "13025-002",
111
"country": "BR",
112
"countryName": "Brazil",
113
"phoneNumber": "246-838-8386",
114
"countyName": null,
115
"emailAddress": [email protected].com,
116
"phoneticFirstName": null,
117
"phoneticLastName": null,
118
"division": null
119
},
120
"shippingAddress": {
121
"id": "shippingAddress",
122
"firstName": "Zachariah",
123
"lastName": "Harris",
124
"companyName": "Digital River",
125
"line1": "1067 Rua Coronel Quirino",
126
"line2": null,
127
"line3": null,
128
"city": "Centro",
129
"countrySubdivision": "SP",
130
"postalCode": "13025-002",
131
"country": "BR",
132
"countryName": "Brazil",
133
"phoneNumber": "246-838-8386",
134
"countyName": null,
135
"emailAddress": [email protected].com,
136
"phoneticFirstName": null,
137
"phoneticLastName": null,
138
"division": null
139
},
140
"shippingMethod": {},
141
"taxInclusive": "false",
142
"landedCostState": "NOT_ELIGIBLE",
143
"pricing": {
144
"subtotal": {
145
"currency": "BRL",
146
"value": 10
147
},
148
"subtotalWithDiscount": {
149
"currency": "BRL",
150
"value": 10
151
},
152
"discount": {
153
"currency": "BRL",
154
"value": 0
155
},
156
"shippingAndHandling": {
157
"currency": "BRL",
158
"value": 0
159
},
160
"importTaxAndDuty": {
161
"currency": "BRL",
162
"value": 0
163
},
164
"tax": {
165
"currency": "BRL",
166
"value": 1.38
167
},
168
"orderTotal": {
169
"currency": "BRL",
170
"value": 11.38
171
},
172
"formattedSubtotal": "10,00 BRL",
173
"formattedSubtotalWithDiscount": "10,00 BRL",
174
"formattedDiscount": "0,00 BRL",
175
"formattedShippingAndHandling": "0,00 BRL",
176
"formattedImportTaxAndDuty": "0,00 BRL",
177
"formattedTax": "1,38 BRL",
178
"formattedOrderTotal": "11,38 BRL"
179
},
180
"paymentMethod": {
181
"type": "boletoBancario",
182
"sourceId": "729bfe56-93cc-4759-a6b5-cd40236d126e",
183
"sourceClientSecret": "729bfe56-93cc-4759-a6b5-cd40236d126e_0984ec75-f984-4d6d-a634-fd7f6b8dd20e",
184
"boletoBancario": {
185
"documentCode": "23790001246004987209031123456704579990000010000",
186
"clientSecret": "729bfe56-93cc-4759-a6b5-cd40236d126e_0984ec75-f984-4d6d-a634-fd7f6b8dd20e",
187
"flow": "redirect",
188
"document": https://link/to/the/payment-slip.pdf,
189
"reusable": "false"
190
}
191
},
192
"paymentCompletionResources": {},
193
"termsOfSalesAcceptance": null,
194
"paymentSession": {
195
"id": "03aede3b-29d9-4aca-a5c2-9e3707861e68",
196
"clientSecret": "03aede3b-29d9-4aca-a5c2-9e3707861e68_9e4f4089-0823-4dac-8915-0b2e2f8b085b",
197
"status": "pending_redirect",
198
"redirectUrl": https://api.digitalriver.com:443/payments/redirects/797e027a-6a75-482e-b18f-2ba02beddda6?apiKey=pk_sys_704d8a7ccbc44f38ab218da662bc347b
199
},
200
"customerType": "I",
201
"taxRegistrations": [
202
{
203
"key": "CPF",
204
"value": "03927107492"
205
}
206
]
207
}
208
}
209
Copied!

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
1
{
2
"errors": [
3
{
4
"code": "vat-exemption-failure",
5
"description": "Tax Exemption Rest of the World is not enabled on this site."
6
}
7
]
8
}
Copied!
Last modified 1mo ago