Skip to main content

Overview

The International Prices APIs provide merchants with the most updated international prices of their products in the territories operated by Global‑e. Two methods are available, depending on how you consume the prices.

GetCatalogPrices

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/<MerchantID>?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.
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.

GetMerchantPriceDetails

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.

API reference

Get Catalog Prices — full request & response

Parameters, schema, examples for POST /Browsing/GetCatalogPrices.

Get Merchant Price Details — full request & response

Query parameters, response schema, examples for GET /externalapi/GetMerchantPriceDetails.

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. Calculate product price flow To implement the Product Price Logic and Flow:
  1. Call the GetMerchantPriceDetails REST API 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. Scenario 1 — 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 = 6 and useDistanceSellingVAT = 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.
    Scenario 2 — 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 = 6 and useDistanceSellingVAT = 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 = 6 and useDistanceSellingVAT = 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 productClassCoefficient is 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 roundingIf 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.

VAT Settings

This section lists the VAT properties and provides an example on how to calculate the VAT based on the selected VATTypeId option. VatTypeID Descriptions 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%:

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 Calculating Prices: Logic and Flow. The following tables provide the list of properties required to implement the remaining rounding rules. RangeBehaviors Enumeration
Important. 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.

Use Cases

Rounding Rules Samples

The following samples indicate how rounding X to Y (X → Y) is implemented using the respective settings.

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.