Managing tax identifiers

Search…
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!
If Global Tax ID Management is not enabled in Global Commerce,  we return a 409 Conflict.
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:
​Attach the shopper to the cart. The authenticated shopper's default payment option will be applied to the cart.
​Attach the source directly to the cart.
​Submit the cart. 
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.
If Global Tax ID Management is not enabled in Global Commerce,  we return a 409 Conflict.
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!
Terms of Sale (TOS) acceptance
Getting line items from a cart
Last modified 9mo ago
Copy link
Contents
Customer type
Attaching a tax identifier to a cart
Removing a tax identifier from a cart
Removing a tax identifier with the cart identifier
Removing a tax identifier without the cart identifier