Skip to main content

Get started with custom widgets

Learn how to establish a user session. Custom widgets require a valid user session to authenticate requests to the Instacart Developer Platform. A user session enables Instacart to build a connection between a customer’s shopping interactions on your retailer site and storefront site. For example, if a customer adds items to their cart on your retailer site and then navigates to your storefront site, the cart accurately shows the number of items in their cart on your storefront.

  1. Before you begin
  2. Establish a user session
  3. After establishing a user session

Before you begin​

  • Work with your Instacart representative to set up your storefront site and configurations, and verify your external SSO.
  • Ensure that your retailer site and storefront site use the same registered domain. For example, your retailer site is www.freshgrocery.com. Your storefront is shop.freshgrocery.com. They both use the same freshgrocery.com registered domain.

Establish a user session​

Custom widgets require a valid user session to authenticate requests to the Instacart Developer Platform endpoints. Before your content page loads the widgets, the page must send a request to the init endpoint. This request creates a user session if one does not exist.

In your request, substitute your storefront site for the <retailer-storefront-site>. For example, shop.freshgrocery.com.

var initRequest = new XMLHttpRequest();
initRequest.onreadystatechange = function () {
  if (this.readyState == 4 && this.status == 200) {
    // Init request completed successfully
    // Dispatch a custom event
    var event = new Event('initRequestCompleted');
    document.dispatchEvent(event);
  }
};
initRequest.open('POST', 'https://<retailer-storefront-site>/idp/v1/init', true);
initRequest.withCredentials = true;
initRequest.send(null);

A successful response returns the status code 200. If there's an authentication issue, the response returns the status code 403.

After establishing a user session​

After establishing a user session, you can implement custom widgets that leverage the Instacart Developer Platform. For example, if you want your custom widget to use the customer context to apply loyalty discounts, use the Get user details endpoint.

Last updated on