THIS IS A FAQ FOR INTERNAL USE ONLY.
This FAQ objective to indicate solutions to problems and doubts that may arise in the Integration with Google Shopping.
NOTE: If you can't find your answer below and need to open a call with the Connections team, you must ask the customer to provide access to their Google Merchant account to the the following emails:
ATTENTION: SPLUNK CHANGES TO OPEN SEARCH
Due to log-related changes, please disregard the splunk related "queries" mentioned in this FAQ, we recommend using the following file as a reference, until the FAQ is updated. (These new queries are also available for consultation in the #team-connections channel.
Important - Help VTEX
1. Before starting an investigation, confirm that the seller is using XML and API simultaneously.
2. Also, check if the seller uses Native integration (API) or XML, in the case of a Native integration, the investigation follows with Connections, if it is XML, it must be verified with the Merch team.
THE FAQ IS CLASSIFIED AS FOLLOWS:
1. UPDATE FAQ | FOLLOW THE LATEST UPDATES OF OUR FAQ
2. TICKETS | WHAT INFORMATION CAN HELP THE PRODUCT TEAM IN AN INVESTIGATION
3. GOOGLE | GOOGLE SHOPPING TRAINING
4. DIAGRAM | PRODUCT INTEGRATION FLOW IN GOOGLE SHOPPING
5. QUESTIONS | PRODUCTS
6. QUESTIONS | SETTINGS
7. INVESTIGATIONS | PRODUCTS
8. INVESTIGATIONS | SETTINGS
UPDATE FAQ | CLICK HERE AND FOLLOW THE LATEST UPDATES OF OUR FAQ
WHAT INFORMATION CAN HELP THE PRODUCT TEAM IN AN INVESTIGATION
Did you have doubts when creating a ticket for Connections? CLICK HERE
We have some tips that can help improve our communication and reduce the "back and forth" of tickets, thus providing more agility in the service/response of the product team. Here are some tips that we think are essential for starting an investigation.
GOOGLE SHOPPING TRAINING
Have you watched our training? Here we show the integration setup, authentication, common errors and it's possible causes. https://vtex.slack.com/archives/C928RF5PC/p1609936369293200
DIAGRAM | PRODUCT INTEGRATION FLOW IN GOOGLE SHOPPING
QUESTIONS | PRODUCTS
Q: Is it possible by native means to send the multipack and mobile link fields
A: These attributes can be included in the product specifications (if included, it will be shipped)
Q: Alcoholic Drinks on Google Shopping
A: Once the integration is complete, the categorization of your products will have been carried out automatically. However, there are cases where a product is disapproved because Google considers that the category assigned to it is incorrect [more details]
Q: Why are skus being disapproved in Google Merchant Center for the following reasons: [ticket reference]
1. Desktop landing page unavailable
2. Mobile landing page unavailable
Errors:
1. The page read timed out
2. HTTP 5xx response
A: These errors are not related to the integration itself, because as an integration we only send the product URL to the Merchant Center, so if the url link was sent correctly on the integration side, everything is fine. After sending the URL, who is responsible for updating the information is the google crawler, who visits all product pages.
Q: What is the difference between "error" and "warning" in Merchant Center?
A: About Error = Google disapproves the sku and it stops being displayed in search results;
About Warning = it's just a warning, not a disapproved sku and it is displayed normally in search results, but it signals that the sku has an improvement to be reviewed.
Q: What does "Ineligible SKU" mean?
A: This means that that product has been deemed ineligible for integration. Products may become ineligible for the following reasons:
The product is priceless.
The product does not have an image.
The product is out of stock and has been configured to be deleted when out of stock.
Q: Why is idsku different in the merchant center?
A: This happens because google concatenates the PRODUCTID + SKUID. So the pattern that you will see in the merchant center in the "Item ID" column will be the following ID "999773617_913056".
First part | PRODUCT ID = 999773617
Second part | SKUID = 913056
Q: On the integration card (storeconfig) with GS we have a "send price" key with the options "without unit multiplier" and "with unit multiplier", considering this rule, as we send the price to google, when the seller selects "with unit multiplier"?
A: The checkout responds a multiplier value per item in the preflight call. The price is calculated with (sellingPrice / unitMultiplier)) / 100
Q: When an item is active on VTEX, but with an inactive category in the VTEX catalog, should it be available on the merchant?
A: The fact that the category is disabled should not be an impediment to sending the SKU. Even when sending the order to the GS there is a SendGoogleCategories flag that allows the customer to send the SKU without sending the category, resulting in. a null submission to the marketplace
Q: Does the integration consider PIX as a cash payment? (02/08/2024)
A: Yes, today the integration considers payment options such as Boleto OR PIX, but it is very important to remember that they do not work simultaneously, that is, it will work for PIX OR Boleto
Q: Do you have any plans to implement these cash discounts simultaneously?
A: No, this limitation does not apply to the integration, Google itself only accepts one “discount” source.
Q: External seller unable to integrate sku, bridge error: "Ineligible SKU"
A: The first step is to understand which seller these skus are linked to and analyze the logs, ticket with step-by-step investigation for reference: https://vtexhelp.zendesk.com/agent/tickets/621989
Q: Integration sent price and sale price correctly, but the promotional tag doesn't appear in the google ad.
A: We as a connector have no control over this tag, but it is important to keep in mind that google has some rules for display, this google documentation explains the requirements for this tag to appear in the product: https://support.google.com/merchants/answer/9017019?hl=en
Q: How does the "Price reduction" tag work?
A: If you change the price of the product to a lower than the average price listed before, Google will show the item a "Price reduction" badge. This icon is only shown when there has been a significant reduction in the price of a product that hasn't changed much in a while. It is important to keep in mind that we as a connector have no control over this tag, this google documentation explains the requirements for this tag to appear on the product: https://support.google.com/merchants/answer/11435005?hl=en
Q: Is it possible to create a field in the feed to receive the product category tree?
A: No, today the integration doesn't support this type of configuration, our documentation can help with the correct context for category mapping in GS https://help.vtex.com/en/tutorial/configurando-a-categoria-global--tutorials_188
Q: Products are being disapproved due to unsupported field: Unsupported attribute [installment]. I tried to look for such a field but I can't find it.
A: The installment configuration isn't defined by the integration, we send what the simulation returns to the integration. The installment is defined in Admin > Transactions > Payments > Settings
Q: What can cause price/stock divergence in Google Shopping?
A: Before starting an analysis, check if the seller uses Native integration (API) or XML, in the case of a Native integration the investigation follows with Connections team, if it's XML it must be verified with the Merch team. Considering these points, we recommend reviewing the following settings:
VTEX Configuration
Step 1. Check if the account is authenticated;
Step 2. Check if the endpoint has been correctly configured for the Google Shopping affiliate;
Step 3. Check the configurations running a checkout simulation , using a sample sku
Step 4. Check if the product is linked to the Trade Policy of Google Shopping
Step 5. Check if the SKU has a fixed price registered (fixed price context following the FAQ)
Splunk
Step 1. Check if the broadcaster is receiving notification for price/stock change:
index=ccnotificator account=test 2148137
Step 2. Check the log if the price/stock is being sent correctly to the marketplace:
index=sellercenterintegration account=teste
Merchant Center Setup
Step 1. Ask the seller for access to the Merchant Center;
Step 2. Automatic Improvements > Enable automatic updating of items > We recommend that the seller keep this switch turned off, as the integration already updates for price/stock, it's not necessary to enable. When enabled in a native integration it can cause conflict and divergence in price.
Step 3. What value is being written in the field "Raw feed attributes: account API"? This field within the Merchant Center is the most important, this is where the seller can validate what the integration is sending to google.
Crawler google
After that, who is responsible for updating the information is the google crawler, which visits all the product pages. When the crawler cannot see the price correctly, there is probably an error related to the structure of the page.
This google tool can help investigate errors related to page structure: https://search.google.com/test/rich-results?id=ajJ9-HfCwo7rJUd13N1glg
Important
As an integration, we do not have control of the structure and customizations of the product pages, but there is some documentation that can guide the agency/seller:
Configuring discounts for orders prepaid in full on Google Shopping:
https://help.vtex.com/en/tutorial/configuring-discounts-for-orders-prepaid-in-full-on-google-shopping--40K3R5d4NogMvCzIWdWt3e
Using Checkout API to set a discount:
https://developers.vtex.com/vtex-developer-docs/changelog/improvement-in-first-installment-payment-discount-configuration
Understanding Price Update Flow - Non VTEX Seller Products
Q: I would like to better understand the price update flow in Google Shopping integration for non-VTEX seller products that use EXTERNAL HUB for catalog integration with VTEX.
A: When the Marketplace is external, the flow must be seen with #team-marketplace. All external sellers need to notify the marketplace when the price changes, and this needs to be enough for the marketplace's own flows to update their data where necessary (like other external integrations). To confirm if the connector is updating correctly, it's possible to force a notification, if the broadcaster is notified then the connector is ok.
[Notification - Price]
http://{{AccountName}}.vtexcommercestable.com.br/api/notificator/changenotification/{{Idsku}}/price
[Notification - Inventory]
http://{{accountName}}.vtexcommercestable.com.br/api/notificator/changenotification/{{Idsku}}/stock
[Notification - Product]
http://{{AccountName}}.vtexcommercestable.com.br/api/notificator/changenotification/{{Idsku}}
Q: Why some skus show a diference of -5% in the Merchant Center over the value registered in the VTEX Catalog?
A: In these cases, check if the key "Consider discount for payment with Boleto ( Bank Slip ) on the price sent (Discount in cash)" is enabled. If so, the seller has enabled the payment method by bank slip, that is, the price of the product sent to Google Shopping will be the value with this discount. The integration will send the sku price considering the discount. (The key is inside the GS integration setup card).
Q: Will Google Shopping products without update expire in 30 days ?
A: Yes, no action is required from the seller . A system is in place that control this and sends Google an update every 30 days.
Q: How is the item_group_id attribute filled in the XML native integration ?
A: Here is how it works: ItemGroupId = sku.ProductId, this means that it will look and grab the ProductId.
Q: Is it possible to somehow configure the item_group_id in the XML native integration ?
A: No, because it gets this information from a Get in the product inserted in the GoogleShopping
Q: Is it possible to send customlabels to Google Shopping using the Native Integration?
A: Yes, it is possible to manage custom tags in VTEX Google Merchant Connector.
If the product has a specification field, the connection will send it.
As you can see below, the fields marked with (*) in Google , are custom.
Q: How does the integration of the promotional price works ?
A: The integration sends the price defined in the commercial policy linked to Google Shopping". If there is an offer price (From/By), only the "Per" price will be sent.
If there is a cash discount promotion (promotion subject to the BOLETO payment method), this benefit will be applied to the value of the product before shipment. If this boleto discount flag is enabled on the configuration card.
Q: How does the "Do not send EAN (GTIN)" flag work?
A: When the client sets this flag in the configuration card, the skus are sent to Google with the field “gtin”= null in the Json. But there is a rule in Google shopping about submitting some properties. When we don't send the "Gtin" ,in the case Gtin=null, Google requires the "mpn" field to be filled (mpn is the manufacturer's code).
If the mpn is not filled in in VTEX, the integration also sends this field as “null”.
These products appear on Google Merchant with an alert when we send them like this, but this does not invalidate the product and they can be be sold normally, however performance can be degraded.
Additional documentation: https://support.google.com/merchants/answer/6324482?hl=pt-BR
Q: When does the integration update the product feed?
A: The integration will update in two situations:
-
Initial update. (When the merchant sets up the integration.)
-
Whenever there is a change in the catalog. (SKU, price and stock.)
Q: How does the SKU updating flow work?
A: Sku reindex > Sku enters a queue (this queue is shared with all other accounts) > Skus will be reprocessed based on the queue order > If the Sku has an error in reprocessing, or it is re-queued or discarded > It goes back to the end of the queue.
Q: Is it possible to change image of an already integrated sku successfully?
A: Yes, the integration is notified whenever the sku is updated (re-indexed)
Q: What is the average time to update a sku on GS?
A: It is hard to predict as it will depend a on the queue size > It is necessary to analyze the log + data and understand if this sku went back to the end of the queue (because it received an error or was reprocessed). Please remember that if the Sku displays an error in the processing, it is either re-queued (going to the end of the queue) or discarded. Query to analyze log: index=gsintegration account= {{idsku}}
Q: When I click on the available sku link in the bridge I am getting a 404 error
A: This error can occur when the URL registered in the customer's Google Merchant Center is different, non-standard or has not been verified by GS.
Google Documentation can help with this verification:https://support.google.com/merchants/answer/176793?hl=en-BR
Example url correctly registered and verified in Merchant Center:
Example url correctly registered and verified in Merchant Center:
INVESTIGATIONS | PRODUCTS
Scenario: "Sku does not integrate with Google Shopping."
How to investigate: First step, do a checkout simulation using Postman. Here you can understand what is the situation of the sku in the moment of the integration.
In the example below, the checkout showed us an error: " A communication error with the Catalog occurred - Accessed denied to the seller 1 Neste exemplo checkout retornou erro: "Ocorreu um erro de comunicação com o Catálogo - Seller 1 does not have authorized access to the sales channel 26".
What is the meaning of this error?
This error is usually related to the store's binding configuration. You need to associate the commercial policy of Google Shopping (IdPoliticacomercial) in the {{Account}} binding. After performing this process, it indexes the products to be updated/sent to GS.
How it works?
https://help.vtex.com/en/tutorial/o-que-e-binding
Understand more about trade policies and website binding
https://help.vtex.com/tutorial/como-funciona-a-relacao-entre-websites-e-politicas-comerciais
Scenario: "Sku price not updated on Marketplace."
How to investigate: First step, analyze if the sku has a fixed price registered in the catalog and if it has been updated.
Yes, Fixed price has been updated > Skip this step and proceed with the next review (Stock/Price is not being updated (how to investigate))
No, it doesn't have a fixed price > In this case, the integration is not notified of a price change. Only "Fixed Price" changes generate notifications to the broadcaster.
Update price for marketplace
https://help.vtex.com/en/tutorial/updating-price-to-marketplace--tutorials_384
Fixed Price - Concept Definition
https://help.vtex.com/en/tracks/precos-101--6f8pwCns3PJHqMvQSugNfP/3HxF2u5VwidqnUGnFoKdDy?locale=en
I still have questions about updating the fixed price.
This is the documentation from the Merch team that explains how fixed price upgrade works.
https://help.vtex.com/en/tracks/precos-101--6f8pwCns3PJHqMvQSugNfP/3HxF2u5VwidqnUGnFoKdDy?locale=en
TheSeller does not use "Fixed Price" what to do in this case?
If the seller wants prices to notify for non-fixed price updates, they can define a price rule, even if empty for that specific policy the pricing workflow of pricing notification will call the broadcaster.
How to configure this price rule?
Go to Admin > Products > Prices > Pricing Rules > New Rule
New rule: What are general rules that I should use ? Select the commercial policy (we recommend creating a rule for each existing commercial policy in the store). On which items will this rule be applied? Select the option "Apply to all products"
For the other fields no selection is necessary > Click on "Save". Perform the same procedure for other trade policies.
Important: After registering fixed price, request a bulk upgrade for all skus.
Scenario: "Sku does not integrate. Error message "insertion error: Ineligible Sku."
How to Investigate: To better understand the status of the sku you are trying to integrate, the ideal perform a fulfillment simulation:
cURL
curl --location --request POST 'https://{{Accountname}}.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={{Pol%C3%ADticaComercial}}&affiliateId={{Afiliado}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"items": [{
"id": "32309",
"quantity": 1,
"seller": "1"
}],
"marketingData": null,
"postalCode": "22250040",
"country": "BRA",
"selectedSla": null,
"clientProfileData": null,
"geoCoordinates": [],
"isCheckedIn": false,
"storeId": null
}'
"Price" to validate if the sku has a valid price; In the result of this simulation it is necessary to analyze the following fields:
-
“Stockbalance” to validate if the sku has stock;
-
“Message” to validate sku availability.
If the above information is all correct, try to reprocess the sku. If the error message persists, it is necessary to open ticket with the Connections team, sharing the analysis done above.
Scenario: "Seller White Label does not update price on Google Shopping".
How to Investigate: It is very important to remember that the integration is passive, that is, it will update the GS with what CHK returns, considering this, the first step is to understand how the seller was configured:
-
Which integrator does the seller use to notify VTEX?
-
Which VTEX route does the integrator uses to notify these SKU changes, be it price or stock?
If you do not have any integrator, check with the seller how the integration was created and which routes are being used for price and stock notification.
Second step: When the seller has a store that operates as an Marketplace, receiving prices and stocks from several sellers, to notify the integrations of possible changes we must use the routes from the documentation.
Third step: Check which route is being used to notify the Marketplace. To notify marketplace, these are the routes found in the documentation here → Notification , to change the price use this route here
How does communication work?
External Seller → VTEX MKP Store → Broadcaster → Affiliates → Marketplaces
Scenario: "Sku has GTIN(EAN) error even with GTIN(EAN) filled."
How to Investigate: This usually occurs when gtin/ean has an invalid format. If the client does not have valid Gtin to use on the skus, it is possible to use the configuration key on the Google card, in which case google will ignore gtin registered because the integration sends this field as null.
NOTE: All Barcodes supplied to Brazil must MUST start with the sequence "789". Currently in Brazil, all prefixes are released with the beginning "789".
In this documentation, google explains the accepted formats: doc google
Scenario: "Products do not appear in Bridge".
How to Investigate: Usually this issue is related to Google Shopping settings, to identify the cause of this issue, you need to follow the steps below:
Step 1. Check if the account is authenticated;
Step 2. Check if the endpoint has been correctly configured for the Google Shopping affiliate;
Step 3. Check if the card settings are consistent with the affiliate's information;
Step 4. Check if the product is linked to the GS commercial policy;
Step 5. Using a sample/test SKU do a checkout simulation.
Scenario: "Even with correct settings, product does not update price".
How to Investigate: Before proceeding with the investigation, you need to understand how the Price and Inventory Update Flow for the Marketplace works:
Customer changes stock/price in catalog/pricing -> catalog/pricing notifies Broadcaster ->
Broadcaster notifies integration -> integration changes stock/price in marketplace.
-
First half of flow = Team Merch
-
Second half = Team Connections
It is necessary to investigate each step to identify the flow failure. Since in Google Shopping there is no stock quantity sent (only available or unavailable sku), we will only look into the price update portion of it:
1. Customer changes price in Pricing:
Check information change history in splunk. Here you can the date and time data of the last update.
2. Pricing notifies Broadcaster:
The Broadcaster (or ccnotificator) is the sub-system responsible for distributing and triggering notifications on any change in product, price or stock to each of the affiliates. In order for it to trigger this information, it is necessary for it to be notified of any change that has occurred.
Therefore, it is necessary to search for the notification log in splunk.
If it's price, search for the following query: index=ccnotificator account={{accountName}} workflow_instance={{idSku}} workflow_type=EnqueuePriceChangeNotification
If on the date and time when the information was last changed (step 1) there are no notification logs, the flow failure must be dealt with by the Merch team.
3. Broadcaster notifies integration:
After the broadcaster is notified that there has been a change in information, it is necessary for it to send this information to all affiliates.
Therefore, you need to check the splunk for logs that this information has been sent.
For price, search for the following query: index=ccnotificator account={{accountName}} workflow_instance={{idSku}} workflow_type=NotifyAffiliatesAboutPriceChangeAsync
If this log shows an error message “A communication error occurred with the product catalog. Seller 1 unauthorized access to sales channel “x”.” it is necessary to verify the binding for the commercial policy registered in the marketplace (both account and sub-account).
If this log is pointing to an endpoint other than “https://portal.vtexcommercestable.com.br/api/googleshoppingintegration/notification?accountName={{account}}” it is necessary to adjust for this endpoint, as the customer most likely has made a manual change to it.
In case this log presents an unidentifiable error, the flow failure must be dealt with by the Connections team, and it is essential to include in the ticket the query used in splunk and the error identified
4. Integration changes the price on the marketplace:
Considering that step 3 was performed successfully in the flow, it is necessary to check now if the integration made the necessary change in the marketplace.
In the case of Google Shopping, you need to check in the splunk logs for data showing the sending of this information, search for the following query: index=gsintegration accountName={{accountName}} idSku={{skuId}} action=PRODUCT_INSERTION
In case this log presents an unidentifiable error, the flow failure must be dealt with by the Connections team, and it is essential to include in the ticket the query used in splunk.
If this log has a different value from the one registered in the VTEX admin or in the Pricing module, it is necessary to perform a checkout simulation to analyze which stock and price information is being passed on to the integration, as the integration uses the returned information by the checkout simulation to consult the stock and price values that will be sent to the marketplace.
CHECKOUT API
POST http://{{accountName}}.vtexcommercestable.com.br/api/checkout/pvt/orderForms/simulation?sc={{commercial policy}}
1. If the checkout simulation returns the same value that the integration sent, then this is indeed the value registered in the sku. It is necessary to understand with the Checkout team the reason for the divergence of values.
2. If the checkout simulation returns a different value than what the integration sent, then there was a recent change in the sku values. To update the information, just make a change to the sku so that it is updated again on the marketplace.
INVESTIGATIONS | SETUP
Comments