Skip to main content

Documentation Portal

International Prices

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.

Note

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=gb

In 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

Note

This API endpoint is used to pull the catalog 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 catalogs 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 catalog conversion request from a merchant and returns the requested list of country and currency prices for the catalog.

SAMPLE:

Request Body:

{    
    "Countries": [
        {         
            "CountryCode": "FR"         
        },
        {            
            "CountryCode": "DE"            
        }
    ],    
    "Products": [{            
            "ProductCode": "565571",            
            "OriginalCurrencyCode": "GBP",            
            "OriginalSalePrice": 100.0000,            
            "VATRate": 0.0,            
            "ProductClassCode": null,            
            "IsPriceIncludeVAT": null            
        },
        {            
            "ProductCode": "565571",            
            "OriginalCurrencyCode": "GBP",            
            "OriginalSalePrice": 20.000,            
            "VATRate": 20.0,            
            "ProductClassCode": null,            
            "IsPriceIncludeVAT": null            
        }
    ]    
}

Request URL (link to the QA environment):

http://connect-qa.bglobale.com/Browsing/GetCatalogPrices?merchantGUID=XXXXXXXX&merchantId=XXX

Response:

{    
    "Products": [
        {            
            "ProductCode": "P1",            
            "Countries": [
                {                    
                    "CountryCode": "FR",                    
                    "Currency": {                        
                        "CurrencyCode": "EUR",                        
                        "Price": 142.95                        
                    }                    
                },
                {                    
                    "CountryCode": "DE",                    
                    "Currency": {                        
                        "CurrencyCode": "EUR",                        
                        "Price": 141.95                        
                    }                    
                }                
            ]            
        },
        {            
            "ProductCode": "P2",            
            "Countries": [
                {                    
                    "CountryCode": "FR",                    
                    "Currency": {                        
                        "CurrencyCode": "EUR",                        
                        "Price": 23.95                        
                    }                    
                },
                {                    
                    "CountryCode": "DE",                    
                    "Currency": {                        
                        "CurrencyCode": "EUR",                        
                        "Price": 23.95                        
                    }                    
                }                
            ]            
        }        
    ]    
}

ACCEPTS:

FullProductCatalogRequest request

Full request specification.

Includes: Products.

For each product: Countries.

RETURNS:

FullProductCatalogResponse class

FullProductCatalogRequest

List<FullCatalogCountryRequest> Countries

List of countries required for the response – Mandatory.

List<CatalogProductRequest> Products

List of product information. Will include the entire catalog required for the response – Mandatory.

CatalogProductRequest

string ProductCode

ProductCode (SKU) for the product. Returned with the response for product identification.

string OriginalCurrencyCode

Optional - Currency code for the received product. If left empty, the configured merchant currency is assumed.

decimal OriginalSalePrice

Price in original currency.

decimal VATRate

Local VAT rate of the product in the merchant country.

string ProductClassCode

Optional. Product class code used by the merchant to overwrite country coefficient rate.

Boolean IsPriceIncludeVAT

Optional – If not set, the default is True. Indicates whether the price includes merchant VAT rate.

FullCatalogCountryRequest

string CountryCode

Country code for the requested country.

FullProductCatalogResponse

List<CatalogProductResponse> Products

List of requested products with a list of prices for each required country.

CatalogProductResponse

string ProductCode

ProductCode (SKU) for the product. Same as the received value in the request.

List<CatalogCountryResponse> Countries

List of relevant country results for the product.

CatalogCountryResponse

string CountryCode

CountryCode of the current returned country.

CatalogCurrencyResponse Currency

List of relevant currency values for the current product and country.

CatalogCurrencyResponse

string CurrencyCode

CurrencyCode of the current returned currency.

decimal Price

Price for the specific product in the relevant country and currency.

International Price Calculation (Mobile Platforms)
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 GetMerchantPriceDetails Parameter Descriptions, 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.

Calculate_product_Price_GOOD.svg

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:

      [price] = [price before VAT] / (1 + [VAT] / 100)

    3. Add the destination country VAT to the base price of the product if:

      VATTypeID = 6 (force VAT).

      Formula:

      [price] = [price without VAT] * (1 + [VAT]/ 100)

      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:

        [price] = [price before VAT] * (1 + [destination VAT] / 100)

      • 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:

        [price] = [price before VAT] * (1 + [VAT] / 100)

    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 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.