When a customer clicks a regional Google Shopping ad, Google expects the landing product detail page (PDP) to show the same regional price and availability that appeared in the ad without requiring the customer to enter a postal code first.

VTEX maps groups of postal codes that we call delivery regions, registers these regions in Google Merchant Center, and sends, for each product and region, regional price and availability with a destination URL that includes the region_id parameter. When the customer clicks the ad, they land on that URL, and the headless storefront must apply the region so the PDP matches the ad.

Example destination URLs:

The region_id identifies the ad region in the destination URL. The VTEX integration includes it in the product link sent to Google so the storefront knows which country and postal code to use when loading the PDP.

In the URL, the value arrives encoded in Base64. After decoding, the content follows this pattern:

Examples of the value in the URL and the content after decoding:

The example below shows how the storefront turns the region_id from the URL into a country and postal code that can be used in the session:

The full implementation of this step is in Recognize the region_id from the URL and extract country and postal code.

If the customer already has postalCode and country set in the public session, those values take precedence over region_id. Use region_id to regionalize customers who do not yet have a locality in the session.

VTEX already sends the regional feed and builds the URL with region_id. The headless storefront must apply this parameter when the customer arrives by reading region_id, saving the country and postal code in the session, and showing on the PDP the price and availability for that region.

In addition to applying the region via region_id, the PDP must fulfill the promise of the regional ad. Google evaluates whether the landing page matches what was shown in Shopping. Inconsistency between the ad and the PDP is a common cause of regional offer disapproval.

Choose where the regionalization logic will run in the headless architecture. This also defines how the PDP search and rendering will be executed:

Regardless of the pattern, the storefront flow is the same:

In practice, the store code must do three things in sequence:

When the page or middleware loads, read the region_id query param, decode the Base64, and validate the vtex:{countryCode}:{postalCode} format.

In this step, the merchant must call the POST Create new session endpoint of the Session Manager API, sending the country and postalCode extracted from region_id. This call saves the locality in the customer session and enables price and availability regionalization on VTEX.

If the customer already has the vtex_session cookie, use the PATCH Edit session endpoint with the same body; the effect on locality is the same. See an example below:

Add a sales channel

If the store operates with more than one sales channel, include the sc parameter in the call URL. The value is the ID of the channel in which price and availability must be resolved:

Example: ?sc=1 for the main channel. If the store uses a single channel, this parameter can be omitted.

Validate the session update

After saving the country and postal code in the session, check whether the locality was saved in the session with the GET Get session endpoint. Request only the public.country and public.postalCode fields, as in the example below:

Example of the expected response:

If the update worked, the response must return the same country and postalCode that you extracted from region_id. If these fields are empty or different, the PDP is not regionalized yet. Review the body of the call made in Save country and postal code in the store session and whether the vtex_session cookie is being sent in subsequent requests.

In this step, the merchant runs the product and shipping calls, if applicable, after saving the locality in the session, always sending the vtex_session cookie returned in step 2. If the calls are made without that cookie or before step 2, the PDP still shows national price and inventory.

How to execute

1. Store the session cookie
   After the POST/PATCH in step 2, persist vtex_session and send it in all subsequent PDP requests.

2. Fetch the product with the regionalized session
   Use the endpoint the store already uses on the PDP; the recommended one is GET Get product (v1) from the Intelligent Search API:

   
   

   _10

   curl --request GET \

   _10

   --url 'https://{accountName}.{environment}.com.br/api/intelligent-search/v1/products?sc=1&field=slug&value={product-slug}' \

   _10

   --header 'Cookie: vtex_session={sessionToken}'

   
   

   Adjust field and value according to the available identifier (slug, id, sku). Learn more in Headless catalog.

3. Simulate shipping or the cart with the same session
   If the PDP shows delivery time or shipping price, use the Checkout API with the same vtex_session cookie — for example, a cart simulation or a shippingData attachment with the region's postal code. See Headless cart and checkout.

4. Render the PDP with that data
   Display in the interface the price and availability returned by that fetch. Do not ask for a postal code, state, or geolocation before showing the ad price.

Apply this sequence according to the pattern chosen in Where to implement.