Skip to main content

Frequently asked questions

If you can't find the answer to your question here, you can ask Instacart Technical Support by using the Enterprise Service Desk.

General​

How does Carrot Ads API work with ad blockers?​

To avoid ad blockers, integrate Carrot Ads APIs with your backend system for Ads serving and eventing. For events, send the events to the retailer's sub-domain or domain and then forward the events to Instacart by using the Track ad events endpoint.

What should I do if the Ads API returns a 5XX error due to a server outage?​

If Carrot Ads API is unavailable to serve sponsored products, continue to serve pages with the retailer's product ads. When Carrot Ads doesn't serve ads, no ad events are fired.

If Carrot Ads API is unavailable to receive ad events, try resending the failed ad events after the events service comes back online. To avoid blocking the most recent ad events, resend the failed ad events by using a separate process.

What should I do with the 4XX responses received from the Ads API?​

If Carrot Ads API receives an invalid request, Instacart returns a 400 error. If there is a high volume of invalid requests, Carrot Ads API stops serving ads to the retailer until the issue is fixed by the retailer.

Carrot Ads API stores the events that returned errors. Instacart will involve retailers to fix issues and process the invalid events offline. Retailers should proactively monitor the response codes returned by the API and fix issues promptly.

For a list of 4xx errors, see the Response Example section in the API endpoint topics. For general information about how Instacart handles errors, see Error and Status Codes.

Can I merge sponsored products with promoted or private label products?​

Not at this time. If this is something you want to be considered for a future enhancement, share your requirements with your Instacart representative.

Can I change the display position of sponsored products?​

No. If you find that you have a sponsored product showing up close to a catalog product, drop the catalog product from the result set or position the catalog product further away from the sponsored product.

Can I drop sponsored products?​

Yes. If you have more sponsored products than catalog products in your result set, you can drop any unplaced sponsored products ads after you place your last catalog product in a grid.

Can I cache the sponsored product results for a user or across users for the same search term or categories?​

No, never cache results. For each query, send a new request to get sponsored products because the results can be different for different users or sponsored product ads may have expired.

Can I make a new call to Carrot Ads API to get sponsored products for a new page when the user scrolls horizontally or vertically or clicks a page number?​

No. A new request to the Carrot Ads API is likely to return a similar set of sponsored products, which means that there is a high chance of repetition across pages. Make a single request per query and paginate the results.

What should I do if my site is under a bot attack?​

Stop serving sponsored products from the Carrot Ads API and contact Instacart to report that you have an ongoing incident.

Events​

What kind of event firing guarantee (exactly once or at least once) is required by Carrot Ads API ?​

Send ad events at least once. Carrot Ads API handles any duplicate events received in a short interval of time.

What part of the item card triggers the 1px event?​

When any edge of the item card is visible, the 1px event is triggered. To determine what is outside or inside an item card, Instacart refers to the definitions for the CSS properties margins, borders, and padding. Margins create space outside of an element, so the 1 pixel event isn't triggered when only the margin of a tile is displayed. Borders and padding create space within an element, so the 1px event is triggered when the border or padding of an item card is displayed.

Last updated on