Skip to main content
knowledgecenter.2checkout.com

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

  1. 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. 
  2. Using the getContents API call, build your checkout flow, and display the taxes as needed. 
  3. 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.
  4. 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. 
  • Was this article helpful?