Calculate and display shopping cart taxes
Overview
When selling internationally, charging the appropriate amount for taxes can be tricky, as the correct taxation can depend on the shopper's country or US state, the product type, and the order total amount.
However, merchants on the 2Monetize package do not have to worry, as the API calculates and handles the VAT and Sales taxes based on the order information.
Availability
Available to all 2Checkout accounts.
getContents API Method
Information about VAT and sales taxes is handled by the getContents (for JSON-RPC and SOAP protocols) or by making a PUT request to /orders/0/ on REST.
This API method will take into account the product configuration (NET or GROSS price type, product category, pricing options, etc.), any marketing campaign (like discounts) together with the shopper's location, and return all the information needed to display to the shopper.
Request object
The getContents API call accepts as an input an order object, the same object used for placing an order. However, the only required objects for calculating the taxes are the items information (what products the shopper has in their cart) and the BillingDetails (needed in order to locate the customer and retrieve the taxes that should be applied).
Switching the currency
Switching the currency and converting prices is supported both for prices set in multiple currencies in the product configuration, as well as on the fly.
In order to do this, the currency ISO code needs to be updated in the root object Currency element.
Request example
{
"Country": "DE",
"Currency": "EUR",
"Items": [
{
"Code": "NIQRPI0GTU",
"Quantity": 2
},
{
"Code": "0XICS3OVDK",
"Quantity": 1
}
],
"BillingDetails": {
"FirstName": "Customer First Name",
"LastName": "Customer Last Name",
"CountryCode": "DE",
"City": "Bucharest",
"Address1": "Example Street",
"Zip": "73331",
"Email": "example@email.com"
}
}
Response Object
The API will respond with the full order object, including the price and tax information, both on a line item (unit) level as well as on a cart level.
{
"Currency": "eur",
"NetPrice": 266.71,
"GrossPrice": 309.38,
"NetDiscountedPrice": 266.71,
"GrossDiscountedPrice": 309.38,
"Discount": 0,
"VAT": 42.67,
"AffiliateCommission": 0,
"Errors": null,
"Items": [
{
"AdditionalFields": null,
"Code": "NIQRPI0GTU",
"ExternalReference": "",
"LineItemReference": "7fe4770c0c95d44dec5c02ee1bc752b568b47808",
"CrossSell": null,
"Quantity": 2,
"Price": {
"Currency": "eur",
"NetPrice": 169.88,
"GrossPrice": 197.06,
"NetDiscountedPrice": 169.88,
"GrossDiscountedPrice": 197.06,
"Discount": 0,
"VAT": 27.18,
"AffiliateCommission": 0,
"UnitNetPrice": 84.94,
"UnitGrossPrice": 98.53,
"UnitVAT": 13.59,
"UnitDiscount": 0,
"UnitNetDiscountedPrice": 84.94,
"UnitGrossDiscountedPrice": 98.53,
"UnitAffiliateCommission": 0,
"ItemUnitNetPrice": null,
"ItemUnitGrossPrice": null,
"ItemNetPrice": null,
"ItemGrossPrice": null,
"VATPercent": 16,
"HandlingFeeNetPrice": 0,
"HandlingFeeGrossPrice": 0
},
"PriceOptions": [],
"ProductDetails": {
"Name": "100 USD NET API Product",
"ShortDescription": "<p>100 USD NET API Product<\/p>",
"Tangible": false,
"IsDynamic": false,
"ExtraInfo": null,
"RenewalStatus": false,
"Subscriptions": null,
"DeliveryInformation": {
"Delivery": "NO_DELIVERY",
"DownloadFile": null,
"DeliveryDescription": "",
"CodesDescription": "",
"Codes": []
}
},
"Promotion": null,
"PurchaseType": "PRODUCT",
"RenewalInformation": null,
"SKU": null,
"SubscriptionStartDate": null,
"Trial": null,
"SubscriptionCustomSettings": null
},
{
"AdditionalFields": null,
"Code": "0XICS3OVDK",
"ExternalReference": "",
"LineItemReference": "7fe4770c0c95d44dec5c02ee1bc752b568b47808",
"CrossSell": null,
"Quantity": 1,
"Price": {
"Currency": "eur",
"NetPrice": 96.83,
"GrossPrice": 112.32,
"NetDiscountedPrice": 96.83,
"GrossDiscountedPrice": 112.32,
"Discount": 0,
"VAT": 15.49,
"AffiliateCommission": 0,
"UnitNetPrice": 96.83,
"UnitGrossPrice": 112.32,
"UnitVAT": 15.49,
"UnitDiscount": 0,
"UnitNetDiscountedPrice": 96.83,
"UnitGrossDiscountedPrice": 112.32,
"UnitAffiliateCommission": 0,
"ItemUnitNetPrice": null,
"ItemUnitGrossPrice": null,
"ItemNetPrice": null,
"ItemGrossPrice": null,
"VATPercent": 16,
"HandlingFeeNetPrice": 0,
"HandlingFeeGrossPrice": 0
},
"PriceOptions": [],
"ProductDetails": {
"Name": "2nd API NET product",
"ShortDescription": "<p>2nd API NET product<\/p>",
"Tangible": false,
"IsDynamic": false,
"ExtraInfo": null,
"RenewalStatus": false,
"Subscriptions": null,
"DeliveryInformation": {
"Delivery": "NO_DELIVERY",
"DownloadFile": null,
"DeliveryDescription": "",
"CodesDescription": "",
"Codes": []
}
},
"Promotion": null,
"PurchaseType": "PRODUCT",
"RenewalInformation": null,
"SKU": null,
"SubscriptionStartDate": null,
"Trial": null,
"SubscriptionCustomSettings": null
}
],
"Promotions": [],
"AdditionalFields": null,
"BillingDetails": {
"FirstName": "Customer First Name",
"LastName": "Customer Last Name",
"CountryCode": "de",
"State": null,
"City": "Bucharest",
"Address1": "Example Street",
"Address2": null,
"Zip": "73331",
"Email": "example@email.com",
"Phone": null,
"Company": null,
"FiscalCode": null,
"TaxOffice": null
},
"DeliveryDetails": {
"FirstName": "Customer First Name",
"LastName": "Customer Last Name",
"CountryCode": "de",
"State": null,
"City": "Bucharest",
"Address1": "Example Street",
"Address2": null,
"Zip": "73331",
"Email": "example@email.com",
"Phone": null,
"Company": null
},
"DeliveryInformation": {
"ShippingMethod": {
"Code": null,
"TrackingUrl": null,
"TrackingNumber": null,
"Comment": null
}
},
"Affiliate": {
"AffiliateCode": null,
"AffiliateSource": null,
"AffiliateName": null,
"AffiliateUrl": null
},
"CustomParameters": null
}
Unit price information
Per Line Item, each product contains a Price object, with all relevant information for the product's price and taxes:
| Key name | Type | Description |
|---|---|---|
|
Currency |
String |
The currency ISO 4217 code; This currency is used in all the price values for that product. Example: USD. |
|
UnitNetPrice |
Float |
The value per product unit (quantity = 1), excluding sales tax/VAT. Discounts are not reflected in this price. |
|
UnitGrossPrice |
Float |
Total value per product unit (quantity = 1), including sales tax/VAT. Discounts are not reflected in this price. |
|
UnitVAT |
Int |
Sales tax/VAT per product unit. |
|
UnitNetDiscountedPrice |
Float |
The value per product unit,, excluding sales tax/VAT, from which 2Checkout deducts the unit discount. |
|
UnitGrossDiscountedPrice |
Float |
Total costs shoppers incur per product unit. This value includes sales tax/VAT, 2Checkout, and affiliate commissions, but 2Checkout deducts the value of any discounts. |
|
VATPercent |
Int |
Percentage of VAT charged on the order. |
|
VAT |
Float |
Value of VAT per order line. |
|
Discount |
Float |
Value of the discounts per order line expressed in the payment currency. |
|
NetDiscountedPrice |
Float |
The NetPrice value per order line, excluding sales tax/VAT, from which 2Checkout deducts discounts. |
|
GrossDiscountedPrice |
Float |
Total costs shoppers incur per order line. This value includes sales tax/VAT, 2Checkout, and affiliate commissions, but 2Checkout deducts the value of any discounts. |
Order price information
On order level, in the response object root level, you can find all relevant information for the order's price and taxes:
| Key name | Type | Description |
|---|---|---|
|
NetPrice |
Float |
Order value excluding sales tax/VAT. |
|
GrossPrice |
Float |
Total order value, including sales tax/VAT. GrossPrice does not reflect any discounts. |
|
NetDiscountedPrice |
Float |
The NetPrice order value excluding sales tax/VAT, from which 2Checkout deducts discounts. |
|
GrossDiscountedPrice |
Float |
Total costs shoppers incur. This value includes sales tax/VAT, 2Checkout, and affiliate commissions, but 2Checkout deducts the value of any discounts. |
|
Discount |
Float |
Value of the discounts for an order. |
|
VAT |
Float |
Value of sales tax/VAT. |
Integration test cases
- Create a simple product (be it a catalog product in the Control Panel, or a dynamic product), using a round number as the price (like 100) in order to be able to easily check the calculated taxes.
- Using the getContents API call, build your checkout flow, and display the taxes as needed.
- As an easy comparison, you can use a catalog product and generate a buy-link in ConvertPlus and compare the way the taxes are displayed.
- If needed, implement the currency switching in the checkout flow.
- Keep in mind that, where prices in other currencies are specified in the product catalog, they will be used instead of the prices automatically converted by 2Checkout.
