Skip to main content

How to link a user account with an Instacart account

Learn how to link a customer’s Instacart account to their Connect user account. For more information, see Account linking.

Prerequisites​

You need the following things:

  • Account linking is enabled for your site
  • A billing reconciliation process is set up to handle the delivery discounts
  • The Login with Instacart URL

For help with prerequisites, contact your Instacart representative.

Best practices​

Consider the following recommendations in your implementation plan:

  • Manage account linking from the account profile page on your site.
  • Market the advantage of using an Instacart+ membership on your site. For example, you might add the following type of text to your checkout flow: Instacart+ Member? Link your account to receive free delivery!
  • Show users their savings at checkout.
  • Optionally, check the Instacart+ membership status when a customer signs in to your site so that you can display messages or other incentives.
  • Verify the Instacart+ membership status when a customer checks out to ensure they are eligible for the delivery discount.

For an example of a customer journey, see Account linking.

Configure your storefront​

Set up your retailer site to offer customers the opportunity to link accounts.

  • Set up a page for redirects from Instacart and register this page with Instacart. This is referred to as the redirect URI.
  • Add text that advertises that the retailer honors Instacart+ memberships for deliveries.
  • Add text that says that customers can unlink accounts by contacting Instacart Customer Experience.
  • On the account profile page, add a Link Instacart Account button that is visible only when the customer profile is not yet linked to an Instacart account. Configure the button to launch the URL that you received when you set up the account linking feature with your Instacart Connect representative.
  • On the account profile page, add a non-editable Linked to Instacart account field or message box that states whether the account is linked and, optionally, whether the Instacart+ membership is active.
  • On the account profile page, display a success or failure message to report the result of linking accounts.
  • On a checkout page, prompt customers to link an Instacart account with Instacart+ membership to receive free delivery.
  • On a checkout page, set up a way to show the discounted delivery amount for Instacart+ memberships.

Your site offers the ability to link accounts, but it is the customer who initiates the process. Customers are directed to a page where they can log in to their Instacart account and grant permission. If successful, your site receives a CSRF token and an authorization code.

  1. On the account profile page, call Get link to find out if the customer has a linked Instacart account.

    curl --location --request GET 'https://<instacart_development_domain>/v2/fulfillment/users/38b15dd0-150d-40cf-9c8a-963b0e6c6b9f/link' \
    --header 'Content-Type: application/json' \
    --header 'X-Retailer-Id: <retailer_ID>' \
    --header 'Authorization: Bearer <access_token>'
    • If a 400 response is returned, the Instacart account is not linked. The account profile page displays the Link Instacart Account button.
    • If a 200 response is returned, the Instacart account is linked already. The response contains the status of the linked Instacart account and the account profile page doesn't show the Link Instacart Account button.

  2. The customer clicks Link Instacart Account.

  3. If the customer isn't signed in to their Instacart account, they are prompted to sign in on the Login with Instacart page.

  4. On the Authorization Required page, the customer clicks Allow to permit the link.

  5. Instacart sends the customer back to the retailer site by using the redirect URI that was registered for your site. Instacart also returns a CSRF token and an authorization code.

Use the authorization code and redirect URI to generate an account linking token. Then link the accounts.

  1. Verify the CSRF token.

  2. Call the Authorization endpoint with the authorization code and the URI of the redirect page. This call generates the account linking token.

    curl --location --request POST 'https://<instacart_development_domain>/v2/oauth/token' \
    --header 'Content-Type: application/json' \
    --header 'X-Retailer-Id: <retailer_ID>' \
    --data-raw '{
      "grant_type": "authorization_code",
      "client_id": "<client_id>",
      "client_secret": "<client_secret>",
      "code":"9fa2bd7ccbac330c19f7417404b7457de06f9fcbf99458bd67cd5f0eebb982f2",
      "redirect_uri": "https://example.org"
    }'

    The response contains the linking token in the access_token field.

    {
      "access_token": "l0ebkrG2JAXEuNI9UBpWXO-yC7asltvuyw4RjELk3Hc",
      "token_type": "Bearer",
      "expires_in": 86400,
      "scope": "account_linking",
      "created_at": 1615821019
    }

  3. Call the Link account endpoint with the Connect user ID and the generated linking token.

    curl --location --request POST 'https://<instacart_development_domain>/v2/fulfillment/users/38b15dd0-150d-40cf-9c8a-963b0e6c6b9f/link' \
    --header 'Content-Type: application/json' \
    --header 'X-Retailer-Id: <retailer_ID>' \
    --header 'Authorization: Bearer <access_token>' \
    --data-raw '{
      "linking_token": "l0ebkrG2JAXEuNI9UBpWXO-yC7asltvuyw4RjELk3Hc"
    }'

    The accounts are now linked.

  4. Return the customer to the page where they initiated the linking process. A message confirms if the link was successful.

  5. Call Get link to access the customer's linked Instacart account.

    curl --location --request GET 'https://<instacart_development_domain>/v2/fulfillment/users/38b15dd0-150d-40cf-9c8a-963b0e6c6b9f/link' \
    --header 'Content-Type: application/json' \
    --header 'X-Retailer-Id: <retailer_ID>' \
    --header 'Authorization: Bearer <access_token>'

    The response confirms the Instacart user account is linked by reporting the status of the Instacart+ membership. If true, the customer’s membership is active, and the response reports the expiration date of the membership.

    {
      "express_member": true,
      "expired_at": "2023-03-12T07:59:59Z"
    }
Last updated on