Skip to main content

Changelog

The changelog summarizes the updates and enhancements made to the Carrot Ads API. The most recent changes are listed first. All changes are non-breaking changes.

May 22, 2026​

  • Consolidated pagination documentation into Get sponsored products and Get display placements. This change removes the standalone Sponsored Products pagination and Display banners API reference topics.
  • Added the ian.display.viewport_video_view_completion event type for shoppable video ads to the Track ad events endpoint.
  • Updated the following FilterQuery field descriptions on the Get display placements endpoint.
    • filter_tags. Products must match all tags in the request, not at least one.
    • brand_ids. Not applicable to display banner requests.
    • product_category_filter_query. Not applicable to display placement requests (display banner, shoppable display, and shoppable video).

May 14, 2026​

  • Added the following API Reference topics:
    • Get sponsored products. This endpoint returns sponsored product placements for item cards so you can render them with organic catalog results. For pagination, see Get sponsored products.
    • Get display placements. This endpoint returns display creatives (for example image banners or shoppable placements) for supported storefront and content pages. For pagination, see Get display placements.

April 30, 2026​

  • Updated the Available Placement Types for the Buy It Again (carousel) query type in the Get sponsored products endpoint from InCarousel to MixedAdsCarousel.
  • Updated the Available Placement Types for the Candidate Carousel query type in the Get sponsored products endpoint to add MixedAdsCarousel in addition to InGrid.

April 24, 2026​

  • Updated the Available Placement Types for the Candidate Carousel query type in the Get sponsored products endpoint from MixedAdsCarousel to InGrid.

April 7, 2026​

  • In the TrackingParams object in the Get a brand page response, brand_page_id is now required.
  • In the DisplayBannerEventProperties object in the Track ad events request, event_id is now required.

March 11, 2026​

  • Updated the FilterQuery object description in the Get display placements and Get sponsored products endpoints to clarify that the FilterQuery object can be used for both Display and Sponsored Products requests, and that the page_context field determines which ad type the filter applies to.
  • Updated the filter_tags description in the FilterQuery object for the Get sponsored products endpoint to clarify that filter tags apply to shoppable display and shoppable video requests only, and do not apply to display (image_banner) ads.
  • Updated the field descriptions in the Get sponsored products and Get display placements endpoints to reflect their current operation. As part of this update, the following fields are now Required:
  • Added the pagination_context field to the Get sponsored products request to support paginated ad results.

February 4, 2026​

  • Added the Candidate Carousel query type to the Get sponsored products endpoint. This new query type allows you to request ads for a carousel based on a provided list of UPCs, with support for the MixedAdsCarousel placement type.

December 8, 2025​

  • Reorganized the Get started section for improved navigation and clarity:
    • Moved API keys from Authentication to Get started.
    • Consolidated tutorial assets into Get started section.

November 3, 2025​

  • Added shoppable video event types. For more information, see Track ad events.

October 10, 2025​

May 21, 2025​

May 1, 2025​

  • Added the tracking_param field to the BrandPage object in the Get a brand page response.
  • Updated the Track ad events endpoint to correct some of the required fields:
    • In the FeaturedProductEventProperties object, object_tracking_id is required.
    • In the DisplayBannerEventProperties object, object_tracking_id,record_version, event_id, and interaction_id are required.
    • In the ShoppableDisplayEventData object, interaction_id is required.
    • In the ShoppableVideoEventData object, interaction_id is required.
    • In the ShoppableDisplayItemEventData object, interaction_id is required.
    • In the ShoppableVideoItemEventData object, interaction_id is required.

February 18, 2025​

  • Updated the endpoint documentation:
    • Removed information about user tokens. Retailers must use client tokens only.
    • In the SessionContext object and the EventTrackingContext object, updated the user_id, user_ip, and user_agent fields to be required.
    • In the FeaturedProductEventProperties object, removed the rrc and upc fields, added the product_id field, and clarified the descriptions for the page and record_version fields.
    • In the FilterQuery object, clarified that the catalog inventory file must contain the filters and product tags you want to use with Carrot Ads requests.
  • Added the Filters and catalog identifiers topic.
  • Update other concepts to include image sizes for ads assets.

October 25, 2024​

  • Removed the currency field from the OrderProperties object in the Ingest orders request.

October 16, 2024​

  • Updated the Brand page topic with examples of brand page blocks.

Sept 19, 2024​

  • Corrected the Ads domain in all request examples from connect.instacart.com to connect-ian.instacart.com.

August 1, 2024​

June 7, 2024​

March 18, 2024​

  • Published this documentation site.

Last updated on