Skip to main content
International Prices GetCatalogPrices API
Introduction
The GetCatalogPrices API provides merchants with the most updated international prices of their products in different territories operated by Global‑e. These prices can be used for marketing needs (for example, in the Google Shopping Feed or in email marketing campaigns). The recommended frequency of usage of this API call is 1 call per day, as currency rates are updated in the Global-e system once a day. The maximum number of currency results (i.e. product count multiplied by requested countries count) cannot exceed 10,000. It means that if a merchant wishes to get prices of 10 currencies, the maximum number of products that can be sent via this API is 1000. If the API call exceeds this number, a failure message is sent back as a response, and no international prices are retrieved.
Merchants implementing the Price feeds API (GetCatalogPrices API ) to show correct international prices in the Google Shopping feed must ensure that the correct product landing page URL is set to show the price for a country that the feed was generated for.For example, for GEM merchants, the URL should have an additional query string parameter: glCountry, so that the URL for the UK looks like this:<product_page_url>?glCountry=gbIn addition, if the glCountry parameter has been specified, make sure to change the Link of Global‑e CSS by adding the same parameter, so that it looks like this://gepi.global-e.com/proxy/css/&lt;MerchantID&gt;?glCountry=gb
This document is intended for Global-e merchants wishing to retrieve updated international prices for their products, as calculated by the Global-e platform. This document describes relevant API methods and provides implementation examples. For details on the Global-e API, see the General API Reference documentation.
GetCatalogPrices API
This API endpoint is used to pull the catalogue prices for international markets. If the merchant wishes it to be fully automated for new products, we need to make sure that they also upload catalogues through SFTP, otherwise, some new products may not exist in the Global-e Database.
Request sent by the merchant:
  • A list of countries - two letters country codes (ISO2), for which international prices product feed is required.
  • A list of products for which international prices product feed is required, with the following details for each product:
    • ProductCode (SKU) - ProductCode (SKU) for the product.
    • OriginalCurrencyCode - Optional. Currency code for the received product. If left empty, then the default merchant currency will be assumed.
    • OriginalSalePrice per product - Price in original currency.
    • VATRate - Local VAT rate of the product in the merchant country.
    • ProductClassCode - Optional. Product class code used by the merchant to overwrite country coefficient rate.
    • IsPriceIncludeVAT- Optional. The default value is True. Indicates whether the price includes the merchant country’s local VAT rate.
Response sent by Global‑e: The Merchant receives back a list of SKUs and related prices in the countries that were sent in the request.
GetCatalogPrices Method
GetCatalogPrices (FullProductCatalogRequest request) Receives a catalogue conversion request from a merchant and returns the requested list of country and currency prices for the catalogue. Request URL (link to the QA environment):
Sample Request Body:
Response:
Request Body FullProductCatalogRequest request Full request specification. Includes: Products. For each product: Countries. Response Body FullProductCatalogResponse class
FullProductCatalogRequest
ParameterTypeDescriptionMandatory
CountriesList of FullCatalogCountryRequestList of countries required for the responseYes
ProductsList of CatalogProductRequestList of product information. Will include the entire catalogue required for the responseYes
CatalogProductRequest
ParameterTypeDescriptionMandatory
IsPriceIncludeVATBooleanIf not set, the default is True. Indicates whether the price includes merchant VAT rate.No
OriginalCurrencyCodeStringCurrency code for the received product. If left empty, the configured merchant currency is assumedNo
OriginalSalePriceDecimalPrice in original currency
ProductClassCodeStringProduct class code used by the merchant to overwrite country coefficient rate.If not set, the default is True. Indicates whether the price includes merchant VAT rateNo
ProductCodeStringProductCode (SKU) for the product. Returned with the response for product identification
VATRateDeimalLocal VAT rate of the product in the merchant country
FullCatalogCountryRequest
ParameterTypeDescriptionMandatory
CountryCodeStringCountry code for the requested country
CatalogProductRequest
ParameterTypeDescriptionMandatory
IsPriceIncludeVATBooleanIf not set, the default is True. Indicates whether the price includes merchant VAT rate.No
OriginalCurrencyCodeStringCurrency code for the received product. If left empty, the configured merchant currency is assumedNo
OriginalSalePriceDecimalPrice in original currency
ProductClassCodeStringProduct class code used by the merchant to overwrite country coefficient rate.If not set, the default is True. Indicates whether the price includes merchant VAT rateNo
ProductCodeStringProductCode (SKU) for the product. Returned with the response for product identification
VATRateDeimalLocal VAT rate of the product in the merchant country
FullCatalogCountryRequest
ParameterTypeDescriptionMandatory
CountryCodeStringCountry code for the requested country
FullProductCatalogResponse
ParameterTypeDescriptionMandatory
ProductsList of CatalogProductResponseList of requested products with a list of prices for each required country
CatalogProductResponse
ParameterTypeDescriptionMandatory
CountriesList of CatalogCountryResponseList of relevant country results for the product.
ProductCodeStringProductCode (SKU) for the product. Same as the received value in the request
CatalogCountryResponse
ParameterTypeDescriptionMandatory
CountryCodeStringCountry Code of the current returned country
CurrencyList of CatalogCurrencyResponseList of relevant currency values for the current product and country
CatalogCurrencyResponse
ParameterTypeDescriptionMandatory
CurrencyCodeStringCurrency Code of the current returned currency
PriceDecimalPrice for the specific product in the relevant country and currency
CatalogProductResponse
ParameterTypeDescriptionMandatory
CountriesList of CatalogCountryResponseList of relevant country results for the product.
ProductCodeStringProductCode (SKU) for the product. Same as the received value in the request
CatalogCountryResponse
ParameterTypeDescriptionMandatory
CountryCodeStringCountry Code of the current returned country
CurrencyList of CatalogCurrencyResponseList of relevant currency values for the current product and country
CatalogCurrencyResponse
ParameterTypeDescriptionMandatory
CurrencyCodeStringCurrency Code of the current returned currency
PriceDecimalPrice for the specific product in the relevant country and currency
CatalogCountryResponse
ParameterTypeDescriptionMandatory
CountryCodeStringCountry Code of the current returned country
CurrencyList of CatalogCurrencyResponseList of relevant currency values for the current product and country
CatalogCurrencyResponse
ParameterTypeDescriptionMandatory
CurrencyCodeStringCurrency Code of the current returned currency
PriceDecimalPrice for the specific product in the relevant country and currency
CatalogCurrencyResponse
ParameterTypeDescriptionMandatory
CurrencyCodeStringCurrency Code of the current returned currency
PriceDecimalPrice for the specific product in the relevant country and currency
International Price Calculation (Mobile Platforms)
GetMerchantPriceDetails Overview
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.
Calculating Prices: Logic and Flow
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. 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](/international-prices#GetMerchantPriceDetails API-218716).
To implement the Product Price Logic and Flow:
  1. Call the [GetMerchantPriceDetails REST API](/international-prices#GetMerchantPriceDetails API-218716) to get the set of price calculation rules for the relevant territory.
  2. Fixed prices: Check if at least some of the products have fixes prices. If true, these products are configured as fixed prices in the merchant’s database. Fixed prices do not require additional calculation. Therefore, skip this entire flow. However, make sure to show the fixed prices for the products as set in your database. For non-fixed prices, proceed as detailed below. For each product, perform the following steps:
  3. VAT settings: If you are a merchant from the European Union, proceed as follows. If you are a non-EU merchant, skip to step 4. There are two VAT scenarios, depending on how you manage pricing in the e‑commerce platform. The price of the product in the merchant’s system includes the local VAT.
    1. Get the merchant’s product price (including the local VAT).
    2. Deduct the local VAT from the base price of the product if you selected one of the following VAT options: VATTypeId = 0 (hide/deduct the VAT) or VATTypeID = 6anduseDistanceSellingVAT = true (This means that the product is shipped to a destination country where the distance selling regulation applies (within the EU)) Formula:
    3. Add the destination country VAT to the base price of the product if: VATTypeID = 6 (force VAT). Formula:
      Otherwise, if the VATTypeID is not 0 or 6 and the rate of the destination country is not applicable, (useDistanceSellingVAT = False), proceed to step 4.
    The price of the product in the merchant’s country does not include the local VAT.
    1. Get the merchant’s product price (without the local VAT).
    2. Depending on the VAT options you choose, add the destination or local VAT to the base price of the product if the the product is shipped to a destination country where the distance selling regulation applies (within the EU):
      • if VATTypeId = 0 (hide/deduct the VAT), proceed to step 4.
      • Add the destination VAT to the base price of the product if: VATTypeID = 4 (pocket VAT) or VATTypeID = 6anduseDistanceSellingVAT = true (This means that the product is shipped to a destination country where the distance selling regulation applies (within the EU)). Formula:
      • Add the local VAT to the base price of the product if: VATTypeID = 4 (pocket VAT) or VATTypeID = 6anduseDistanceSellingVAT = false (This means that the product is shipped to a destination country where the distance selling regulation does not apply). Formula:
    See VAT Settings for field and option descriptions.
  4. Apply the currencyConversionRate.
  5. Apply the the countryCoefficientRate or apply the correct rate from the productClassCoefficients list, according to the following:
    • If the countryCoefficientRate is not defined and the productClassCoefficient is not defined, no coefficient is applied.
    • If the countryCoefficientRate is not defined and the productClassCoefficient is defined, the productCoefficient is applied.
    • If the countryCoefficientRate is defined and the productClassCoefficient is not defined, the countryCoefficientRate is applied.
    • If the countryCoefficientRate is defined and the productClassCoefficient is defined, the productClassCoefficientis applied.
  6. Perform the arithmetic rounding: Round up the currency’s decimal places, leaving the same number of decimals defined in currencyDecimalPlaces. Example: If currencyDecimalPlaces = 2 And your currency = 223.0234512 Round up the number after the decimal =223.02
  7. Calculate and apply the marketing rounding. See Applying Rounding Rules.

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 .30If 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.
GetMerchantPriceDetails REST API
This API enables merchants to obtain the parameters required to calculate international product prices in a destination country’s currency. Method/URL:
Request query type: string Parameters:
GEM_API_URLThe API host name, based on the environment (such as sandbox, live, and more).
MerchantTokenSecret token (unique merchant ID) to be provided to the merchant by Global‑e.
Country2-char ISO destination country code.Example: IL
Currency3-char ISO currency code of the customer’s country (destination country).Example: ILS
Response
Parameters
Response
NameTypeDescription
countryCodeString2-char ISO destination country code.Example: IL
countryCode3String3-char ISO destination country code.Example: ISR
countryNameStringThe name of the destination country.Example: Israel
currencySymbolStringThe symbol of the currency in the destination country.Example: ₪
currencyCodeString3-char ISO currency code of the customer’s country (destination country).Example: ILS
currencyDecimalNominatorStringCurrency decimal separator type.(”,” or ”.”)Example:XX.XXXX,XX
currencyThousandSeparatorStringCurrency thousands separator indicator.(”,” or ”.”)Example:XXX.XXXXXX,XXX
currencyDecimalPlacesInt32Currency decimal places.Example: 0
cultureStringThe language or locale of the destination country.Example: he
baseCountryCodeStringMerchant’s base country code 2-char ISO.Example: GB
baseCurrencySymbolStringThe symbol of the currency in the country or origin (merchant’s country or base country).Example: £
baseCurrencyCodeStringThe currency code in the merchant’s base country.Example: GBP
baseCurrencyDecimalPlacesInt32Currency decimal places in the base currency.Example: 2
isOperatedByGlobalEBoolWhether the selected country is operated by Global-e.This flag is be used as a Mode indicator.True: yes. In this case, Global-e converts the prices and opens their checkout.False: no. Countries that are not operated by Global‑e must still be available for selection as a shipping destination on the merchant’s site. However Global‑e functionality must be disabled for such countries.
currencyConversionRateDecimalConversion rate between the base currency (GBP in this example) and the converted currency (ILS in this example).Example: 284.001848944500
countryCoefficientRateDecimalPrice uplift as set for this destination country.Example: 1.050000
productClassCoefficientsObject(seedescription)Product uplift as set per product (if the product uplift is set, this parameter overrides the country uplift),TYPE = object of key or value pairs (string / decimal).Example: {“extra-charge”: 1.05, “special”: 1.1}
roundingRulesObjectList of rounding rules that are applied when converting the prices, based on the rounding rule ranges and business rules. See Applying Rounding Rules for the list of properties.
vatSettingsObjectVAT settings and calculation. Only applicable to European countries. See: VAT Settings.
VAT Settings
This section lists the VAT properties and provides an example on how to calculate the VAT based on the selected VATTypeId option.
PropertyTypeDescription
VATTypeIdInt32ID indicating how the merchant has decided to treat the local VAT for customers in the relevant territory.Possible values: 0, 4, 6Example: 0See VatTypeID Descriptions.
LocalVATRateDecimalThe VAT Rate in the merchant’s country.Example: 20.000000 (20%)
UseDistanceSellingVATBoolWhether to apply the distance selling VAT.True: Apply the destination country’s VAT.False: Do not apply the destination country’s VAT.
DistanceSellingVATRateDecimalThe distance selling VAT Rate in the shopper’s (destination) country.Example: 21.000000 (21%)
VATTypeIDDescription
0Hide VAT (default)
4“Pocket” VAT (increase the original price by the value of the respective product’s VAT)
6Force VAT (used to support trade agreements between the countries such as EEA, when the customer in the destination country must pay VAT; for simplicity assuming UseCountryVAT=false)
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%:
Include VAT Option ValueDescriptionPrice in BrowsingPrice in CheckoutPrice Paid to Merchant (incl. VAT)Checkout Duties TotalCheckout Total
0Hide VAT(default)10010012017117
4“Pocket” VAT (increase the original price by the value of the respective product’s VAT)12012014420.4 (17%)140.4
6Force VAT (used to support trade agreements between the countries such as EEA, when end customer must pay VAT; for simplicity assuming UseCountryVAT=false)1201201200120
Applying Rounding Rules
After calculating the price of the product, you must apply the arithmetic and marketing rounding rules. The arithmetic rounding rule is detailed in section Price Calculation Logic and Flow. The following tables provide the list of properties required to implement the remaining rounding rules.
RoundingRule
PropertyTypeDescription
RoundingRuleIDInt64Rule identifier denoting the respective Rounding Rule on Global‑e side. This value must be further specified when calling SaveProductsList and SendCart methods.
CurrencyCodeString3-char ISO currency code
CountryCodeString2-char ISO country code
RoundingRangesListList of decimal ranges and their respective rounding behaviours
RoundingRange
PropertyTypeDescription
FromDecimalA decimal value of the range start, exclusive of the From value itself. If a range must start from 0 inclusive, the From value must be set to a negative number.Example: 100.0000
ToDecimalA decimal value of the range end, inclusive.Example: 1000.0000
ThresholdDecimalA decimal value used to split the range so that the values less than the threshold would be rounded to the Lower target, and values greater than or equal to the threshold would be rounded to the Upper target. For ranges having “Absolute target” behavior, Threshold value is considered as an absolute value. For other behaviors it’s considered as a Relative value.Example: 5.0100
LowerTargetDecimalA decimal value used to calculate the target rounded value, for the numbers less than the Threshold, according to the defined Range behavior. If LowerTarget value violates MaxDecimalPlaces setting for the respective currency, it must be truncated as described in the “Important Notices” below.Example: 15.0000
UpperTargetDecimalA decimal value used to calculate the target rounded value, for the numbers greater than or equal to the Threshold, according to the defined Range behavior. If UpperTarget value violates MaxDecimalPlaces setting for the respective currency, it must be truncated as described in the “Important Notices” below.Example: 10.0000
RangeBehaviorInt64One of the possible values of RangeBehaviors enumeration defined below which is designated to control the way rounding range is handled. The range behavior is applied to Threshold, LowerTarget, UpperTarget and Exceptions in RoundingExceptions list.Example: 3
TargetBehaviorHelperValueDecimalA decimal value required for “nearest target” and “relative whole target” behaviors.Example: 10.0000
RoundingExceptionsListList of decimal values used to calculate the exceptions for rounding, i.e. values to which not to apply rounding.
RangeBehavior Option ValueNameBehavior Description
1Absolute targetAll the values within the specified range (LowerTarget, UpperTarget, Threshold and RoundingExceptions) denote the values themselves as is, without the need for additional mathematical operations.**To get rounding result (R) for the source number (S):**If (S = Exceptionn) then R = ExceptionnIf (S < Threshold) then R = LowerTargetIf (S >= Threshold) then R = UpperTarget
2Relative Decimal targetAll the values within the specified range (LowerTarget, UpperTarget, Threshold and RoundingExceptions) represent floating point numbers between 0 (inclusive) and 1 (inclusive).
To calculate the respective absolute values, relative to the calculation base (B):
For source number (S):B = whole part of S
LowerTarget (absolute):LA = B – 1 + LowerTarget
UpperTarget (absolute):UA = B + UpperTarget
Threshold (absolute):TA = B + Threshold
Exception,n (absolute):EAn = B + Exception
If (S = EAn) then Result (R) = EAn
If (S < TA) then R = LA
If (S >= TA) then R = UA
3Relative Whole targetAll the values within the specified range (LowerTarget, UpperTarget, Threshold and RoundingExceptions) represent non-negative whole numbers.
TargetBehaviorHelperValue (V) is used to determine the calculation base (B). V must be a power of 10 (10, 100, 1000, etc.) and denotes the order of magnitude for the range “split” by the Threshold.
For example, if Threshold = 9, is this value is 9 out of 10 or 9 out of 100?
To get rounding result (R) for the source number (S):
For source number (S):B = S rounded down to the closest multiple of VFor example, if (S = 56789 and V = 1000) then B = 56000
LowerTarget (absolute):LA = B – V + LowerTarget
UpperTarget (absolute):UA = B + UpperTarget
Threshold (absolute):TA = B + Threshold
Exception (absolute):EAn = B + Exceptionn
If (S = EAn) then Result (R) = EAn
If (S < TA) then R = LA
If (S >= TA) then R = UA
4Nearest targetLowerTarget and UpperTarget represent non-negative floating point numbers.
TargetBehaviorHelperValue (V) is used to determine the calculation base (B). V must be a whole divisor of any power of 10 (5, 10, 25, 50, 100, 250, 500, 1000, etc.).
Threshold must be any floating point number between 0 (inclusive) and V (exclusive).
To get rounding result (R) for the source number (S):
For source number (S):B = S rounded down to the closest multiple of VFor example if (S = 123 and V = 5) then B = 120
LowerTarget (absolute):LA = B – 1 + LowerTarget
UpperTarget (absolute):UA = B – 1 + V + UpperTarget
Threshold (absolute):TA = B + Threshold
Exceptionn (absolute):EAn = B + Exceptionn
If (S = EAn) then Result (R) = EAn
If (S < TA) then R = LA
If (S >= TA) then R = UA
For any rounding behavior defined in the table above, if the rounding result is a negative number, it must be set to zero.If either the LowerTarget or UpperTarget value violates the MaxDecimalPlaces setting for the respective currency, this value must be truncated.For example, if UpperTarget is set to 0.999 for USD, it must be truncated to 0.99 before performing further calculations.
The following samples indicate how rounding X to Y (X → Y) is implemented using the respective settings.
Property0.25 → 03 → 01.5 → 1.52 → 222.47 → 21.9522.48 → 22.9922.50 → 22.5033.75 → 33.752047 → 19952048 → 2100122.26 → 124.99122.25 → 119.99127.26 → 129.99121.50 → 121.50127.50 → 127.50123 → 123128 → 1282047 → 19992048 → 2100
From0110001001000
To325010000100010000
Threshold3.010.48482.2648
LowerTarget00.95950.990
UpperTarget00.991000.991
RangeBehavior1Abolute2RelativeDecimal3ReltiveWhole4Nearest4Nearest
TargetBehaviorHelperValue1005100
RoundingExceptions1.520.500.751.502.503
Price Conversion and Rounding Rule Implementation in JavaScript
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.