Documentation Portal

This Global-e GetMerchantPriceDetails REST API enables merchants to obtain the parameters required to calculate product prices in a destination country currency.

This document provides details about the GetMerchantPriceDetails API, a flow and explanations on how to implement the logic, and a sample implementation in JavaScript.

This document is intended for the developer in charge of evaluating and integrating the solution with the merchant's ecommerce platform and assumes familiarity with the Global-e technology, concepts, and terminology.

This section provides the logic and flow required to calculate product prices as they will be displayed to shoppers in their country's local currency on the merchant's website.

The following flow is affected by the various rules, regulations, and specific price factors. Make sure to keep these in consideration when implementing the calculations. The field properties are detailed in Parameters, VAT Settings, and Applying Rounding Rules.

Product Price Calculation Logic and Flow

The following diagram provides the logic that enables the developer to calculate the international price of products based on parameters obtained when running the GetMerchantPriceDetails REST API.

To implement the Product Price Logic and Flow:

Basic rule for arithmetic rounding

If the number you are rounding is followed by a decimal and digits containing 5, 6, 7, 8, or 9, round the number up. Example: .29 rounded up to the nearest ten is .30

If the number you are rounding is followed by a decimal and digits containing 0, 1, 2, 3, or 4, round the number down. Example: .24 rounded down to the nearest ten is .20.

This API enables merchants to obtain the parameters required to calculate international product prices in a destination country's currency.

Example of Price Calculation Based on the VATTypeID

The following table is the list of VATTypeID values and descriptions and the expected results for a sample product with an original cost in UK = 100 GBP before VAT to be shipped to Germany (with a country coefficient Rate=1 and the user selected currency=GBP, for simplicity).

For this sample product UK VAT=20%, DE Duties Total=17%:

This section shows an example of price conversion and rounding implementation in JavaScript. Use this example to write the APIs required for your specific environment and implement them.

function CalculatePrice(value, fxRate, vatRateTypes, productLocalVatRate, isGrossPrices, currencyDecimalPlaces, quantity, productClassCoefficient, priceCoefficient, productCountryVatRate, roundingRules) {
    if (value == 0)
        return (0).toFixed(currencyDecimalPlaces);

    var merchantVatRate = vatRateTypes.LocalVATRateType.Rate / 100;
    if (productLocalVatRate !== null) {
        if (productLocalVatRate == 0) {
            merchantVatRate = 0;
        } else {
            merchantVatRate = productLocalVatRate / 100;
        }
    }

    var countryVatRate = vatRateTypes.VATRateType.Rate / 100;
    if (productCountryVatRate || productCountryVatRate === 0) {
        if (productCountryVatRate == 0) {
            countryVatRate = 0;
        } else {
            countryVatRate = productCountryVatRate / 100;
        }
    }

    if (isGrossPrices) {
        if (vatRateTypes.IncludeVATTypeId == 0 ||
            vatRateTypes.IncludeVATTypeId == 8 ||
            (vatRateTypes.IncludeVATTypeId == 6 && vatRateTypes.UseCountryVAT)) {
            value = value / (1 + merchantVatRate);
            if (vatRateTypes.IncludeVATTypeId == 6) {
                value += value * countryVatRate;
            }
        }
    } else {
        if (vatRateTypes.IncludeVATTypeId == 2 ||
            vatRateTypes.IncludeVATTypeId == 4 ||
            vatRateTypes.IncludeVATTypeId == 6) {
            if (vatRateTypes.UseCountryVAT) {
                value += value * countryVatRate;
            } else {
                value += value * merchantVatRate;
            }
        }
    }

    value = value * fxRate;
    if (productClassCoefficient) {
        value = value / priceCoefficient * productClassCoefficient;
    }

    value = value.toFixed(currencyDecimalPlaces);
    if (skipRounding || roundingRules == null) {
        value = value * quantity;
    } else {
        var ranges = roundingRules.RoundingRanges;
        var range = null;
        for (var r in ranges) {
            var rg = ranges[r];
            if (rg.From < value && value <= rg.To) {
                range = rg;
                break;
            }
        }

        if (range != null) {
            // convert range to form of absolute
            range = ConvertRoundingRangeToAbsolute(value, range);
            // apply logic of absolute range rounding
            value = AbsoluteRounding(value, range) * quantity;

            if (value < 0) {
                value = 0;
            }
        }
    }

    return value;
};


function ConvertRoundingRangeToAbsolute(price, range) {
    var result = null;
    if (range.RangeBehavior == 1) {
        // range already has absolute behavior
        result = range;
    } else {
        result = new Object();
        result.RangeBehavior = range.RangeBehavior;
        result.RoundingExceptions = [];
        result.From = range.From;
        result.To = range.To;

        var int_part = Math.floor(price);

        if (range.RangeBehavior == 2) {
            //Relative Decimal 
            result.LowerTarget = int_part - 1 + range.LowerTarget;
            result.UpperTarget = int_part + range.UpperTarget;
            result.Threshold = int_part + range.Threshold;
            for (var ex in range.RoundingExceptions) {
                range.RoundingExceptions[ex].ExceptionValue += int_part;
                result.RoundingExceptions.push(range.RoundingExceptions[ex]);
            }
        } else if (range.RangeBehavior == 3) {
            // Relative Whole
            if (range.TargetBehaviorHelperValue == 0) {
                range.TargetBehaviorHelperValue = 10;
            }
            var base = Math.floor(price / 
                       range.TargetBehaviorHelperValue) *                                                                                                                                                                 range.TargetBehaviorHelperValue;
            result.LowerTarget = base - range.TargetBehaviorHelperValue + range.LowerTarget;
            result.UpperTarget = base + range.UpperTarget;
            result.Threshold = base + range.Threshold;
            for (var ex in range.RoundingExceptions) {
                range.RoundingExceptions[ex].ExceptionValue += base;
                result.RoundingExceptions.push(range.RoundingExceptions[ex]);
            }
        } else if (range.RangeBehavior == 4) {
            // Nearest target
            if (range.TargetBehaviorHelperValue == 0) {
                range.TargetBehaviorHelperValue = 5;
            }
            var base = Math.floor(price / range.TargetBehaviorHelperValue) * range.TargetBehaviorHelperValue;
            result.LowerTarget = base - 1 + range.LowerTarget;
            result.UpperTarget = base - 1 + range.TargetBehaviorHelperValue + range.UpperTarget;
            result.Threshold = base + range.Threshold;
            for (var ex in range.RoundingExceptions) {
                range.RoundingExceptions[ex].ExceptionValue += base;
                result.RoundingExceptions.push(range.RoundingExceptions[ex]);
            }

        }

    }

    return result;
};

function AbsoluteRounding(price, range) {
    var result = null;
    // check exceptions
    if (range.RoundingExceptions.length > 0) {
        for (var e in range.RoundingExceptions) {
            ex = range.RoundingExceptions[e];
            if (price == ex.ExceptionValue) {
                result = price;
            }
        }
    }
    // no exception was found 
    if (!result) {
        // check threshold
        if (price < range.Threshold) {
            result = range.LowerTarget;
        } else {
            result = range.UpperTarget;
        }
    }

    return result;
};