Managing tax identifiers

Learn how to manage tax identifiers.

Specifying a customer's type and adding any tax identifiers associated with the customer allows you to attach this data to 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 and 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

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.

cURL

curl --location --request GET 'https://api.digitalriver.com/v1/shoppers/me/carts/active/tax-registrations/schema' \
--header 'authorization: Basic  ***\
...

200 OK response

{
    "$schema": http://json-schema.org/draft-04/schema#,
    "id": https://api.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.

cURL

curl --location --request POST 'https://api.digitalriver.com/v1/shoppers/me/carts/active/tax-registrations' \
--header 'authorization: Basic ***\
...

Payload for a business shopper

{
    "customerType": "B",
    "taxRegistrations": [
        {
            "key": "CNPJ",
            "value": "77844699000109"
        },
        {
            "key": "IE",
            "value": "ISENTO"
        }
    ]
}

Payload for an individual shopper

{
    "customerType": "I",
    "taxRegistrations": [
        {
            "key": "CPF",
            "value": "03927107492"
        }
    ]
}

If Global Tax ID Management is not enabled in Global Commerce, we return a 409 Conflict.

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.

cURL

curl --location --request GET 
'https://api.digitalriver.com/v1/shoppers/me/carts/active' \
--header 'authorization: Basic ***\
...

Payload for a business shopper

{
    "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"
            }
    }
 
}

Active response body for an Individual shopper

{
    "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:

• 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

{
    "submitCart": {
        "order": {
            "uri": https://api.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://api.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": [e-mail],
            "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": [e-mail],
            "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.

If Global Tax ID Management is not enabled in Global Commerce, we return a 409 Conflict.

409 Not Found

{
    "errors": [
        {
            "code": "vat-exemption-failure",
            "description": "Tax Exemption Rest of the World is not enabled on this site."
        }
    ]
}