Implement Carrot Ads API

Learn how to get sponsored products using the Carrot Ads API and display them. Then learn how to send ad events when a user views or engages with a sponsored product item card.

note

If you try out this tutorial in a development environment, you'll receive mock responses.

1. Before you begin
2. Create a Connect user account
3. Request sponsored product ads
4. Display the sponsored product ads
5. Send an ad event
6. Summary

Before you begin​

For this tutorial, you need the following items:

• A generated access token. For more information, see Get an access token.
• The base URL of your assigned Instacart server. To try out the tutorial, use the development server domain.
• A retailer ID. You are given this identifier when you sign up to use Carrot Ads API.

Variables used in this tutorial​

The following variables are used in requests in this tutorial. When you see a variable, substitute them with values that work in your development environment.

Variable	Description
<instacart_domain>	The domain of your assigned Instacart server.
<token>	The generated access token.
<retailer_id>	A string that identifies the retailer banner.

The responses in this tutorial show sample values in place of the variables. The responses that are returned in your environment should have a similar format to the example responses. If you are interested in other possible responses, see the API documentation.

Create a Connect user account​

Carrot Ads API uses Instacart Connect to create a user account. The user account contains the minimum information required by Instacart to serve ads to the user. The account must have at least a unique user ID and the customer's first name. The user ID is defined by you, but it must be unique for all retailer customers. For example, you might choose loyalty card IDs.

Production environment tip

If your e-commerce site uses Connect Fulfillment, you already have user IDs for your customers. In production, reuse a customer's user ID rather than creating a new one.

In the request, substitute your values for the variables <instacart_domain> and <token>.

curl -i -X POST -H 'X-Retailer-Id: <retailer-id>' -H 'Content-Type: application/json'
-H 'Authorization: Bearer <token>' https://<instacart_domain>/v2/fulfillment/users -d '{"user_id": "kamalsingh1234", "first_name": "Kamal"}

A successful JSON response has the status code 200 and the following fields:

{
  "user_id": "kamalsingh1234",
  "first_name": "Kamal"
}

If the user account already exists, for example if you or someone else has tried this tutorial on your development environment recently, the request returns the error 400 User already created. You can continue the tutorial with this ID or call the method again with a different user ID.

Request sponsored product ads

To retrieve ads for the user, send a request to the Get sponsored products endpoint.

In the following example, the request retrieves sponsored pasta products to display to the Connect user we created in the previous step. You need to specify contextual information, including store location, session details, page details, and placement details. In this case, the placements are item cards.

curl --location --request POST \
–-url 'https://<instacart_domain>/v2/ian/sp/' \
--header 'Content-Type: application/json' \
--header 'X-Retailer-Id: <retailer-id>' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "store_context": {
    "location_code": "111"
  },
  "session_context": {
    "user_id": "kamalsingh1234",
    "user_ip": "192.0.2.146",
    "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64)"
  },
  "page_context": {
    "page_query": {
      "search_query": {
        "page_view_id": "4291d814-8a75-4fef-9426-123c5840f7bc",
        "search_term": "pasta",
        "enable_auto_correct": "true"
      }
    }
  },
  "placement_context": {
    "placement_kind": {
      "in_grid": {
        "supported_format": "item_card"
      }
    }
  }
}'

The response contains an array of sponsored product ads, up to a maximum of 100. If no ads are available, the array is empty. If you want, you can use the RRC code to retrieve more information about the product from your data sources.

{
  "products": [
    {
      "object_tracking_id": "urn:i-ic-v1:spid:c54c08ac-842d-4cd0-930c-8923dc951efd",
      "rrc": "536071",
      "product_id": 30972167,
      "display_position": 1,
      "ad_format": "item_card"
    },
    {
      "object_tracking_id": "urn:i-ic-v1:spid:5484fd7a-7c30-4b51-916f-6edde57d207d",
      "rrc": "551211",
      "product_id": 31252705,
      "display_position": 2,
      "ad_format": "item_card"
    },
    {
      "object_tracking_id": "urn:i-ic-v1:spid:91042b3b-3edc-4b29-8626-45d4c55a0461",
      "rrc": "577037",
      "product_id": 31321560,
      "display_position": 3,
      "ad_format": "item_card"
    },
    {
      "object_tracking_id": "urn:i-ic-v1:spid:7457f9b8-054d-417b-8b27-888080cfa9b6",
      "rrc": "956121",
      "product_id": 31698838,
      "display_position": 7,
      "ad_format": "item_card"
    },
    {
      "object_tracking_id": "urn:i-ic-v1:spid:29810ef1-0fed-49d6-8ab7-4dc57ad58586",
      "rrc": "926049",
      "product_id": 30974760,
      "display_position": 8,
      "ad_format": "item_card"
    }
  ]
}

Display the sponsored product ads

Display the sponsored product ads in item cards along with your catalog products. The location of a sponsored product relative to other products in a grid is controlled by the display_position value in the response.

The following image shows an example where sponsored products are displayed in positions 1, 2, 3, 7, and 8:

When displaying sponsored product ads, you must include the "Sponsored" label on the item card to identify them as Carrot Ads.

Send an ad event

Set up your app or website to send events to Instacart whenever the user views or engages with a Carrot Ad. For a list of all event types and when to send them, see Events.

In the example, we send an event for the ad when at least half of the sponsored product item card is viewed for more than one second. If an ad is blocked by a modal, the event is not sent.

The following request sends an event when at least 50% of the ad is visible to the user:

curl --location --request POST \
--url 'https://<instacart_domain>/v2/ian/track/' \
--header 'Content-Type: application/json' \
--header 'X-Retailer-Id: the-garden' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "event": "ian.sponsored_product.viewable_in_viewport",
  "user_id": "kamalsingh1234",
  "data": {
    "sponsored_product_data": {
      "event_tracking_context": {
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36",
        "user_ip": "24.12.4.39"
      },
      "record_version": "1",
      "object_tracking_id": "urn:i-ic-v1:spid:3d01f647-12cb-4101-8543-b7419534656f",
      "format_type": "item_card",
      "page_view_id": "b1c06715-469a-44a4-bd11-ef0f3d1d287d",
      "display_position": "3",
      "event_id": "68fe21d8-4802-499f-bf12-f7315ae50091",
      "block_number": "1",
      "page": "1",
      "product_id": "907780"
    }
  },
  "sent_at": "2022-06-17T01:57:23.541268+00:00"
}'

A successful request returns a 200 response to confirm that the event was received.

{
  "message": "Successfully processed"
}

Summary​

In this tutorial, we created a Connect user, retrieved Carrot Ads content to display as sponsored products in your e-commerce site, and sent an ad event to Instacart.