API reference overview

You can use the Instacart Developer Platform API to add Instacart shopping capabilities to your website or app. The REST-based API uses predictable, resource-oriented URLs, and standard HTTP methods, response codes, and authentication.

Request URL

For data privacy and security, API communications use HTTPS. When making a request, be sure to specify https in the URL or the request fails.

You receive access to the following domains for requests to the API:

• Development server: https://connect.dev.instacart.tools
• Production server: https://connect.instacart.com

The following example shows how to structure your request URL:

https://connect.instacart.com/idp/v1/<endpoint>

Authentication

You can authenticate your requests for the public endpoints by using an API key. To get a key, contact your Instacart representative.

Request headers

HTTP request headers provide contextual information about your API request. For example, you can use headers to specify your preferred response format or provide a secure string for request authentication. Some headers and values are required, while others are optional or required only under certain conditions.

The following table describes the request headers:

Header	Required	Description
Accept		The valid content types for the API response payload. Value must be application/json.
Accept-Language		The preferred natural language for the response payload. Values are en-US, en-CA, and fr-CA. If you don’t provide this header, the system uses the default value for your location: en-US for the United States or en-CA for Canada.
Authorization	✅	The API key provided to you by Instacart, passed as an HTTP Bearer token.
Content-Type	✅	The content type used in the body of the request. Value must be application/json.

The following example shows a request with all the request headers defined:

curl --request POST \
 --url 'https://connect.instacart.com/idp/v1/<endpoint>' \
 --header 'Accept: application/json' \
 --header 'Accept-Language: en-CA' \
 --header 'Authorization: Bearer <API-key>' \
 --header 'Content-Type: application/json' \
 --data '{
<parameters>
}'

Rate limiting

The API accepts a limited number of requests per second. Our goal is to accommodate an appropriate volume of legitimate requests while protecting our system against misuse, whether accidental or intentional.

If you receive a 429 Too many requests error, then your number of requests per second has exceeded the rate limit threshold. Try the request again later. If you repeatedly receive 429 errors, contact your Instacart representative.

Example languages

The endpoint documentation typically includes sample requests in the following languages:

• cURL
• Java
• Python
• Go

Data formats

The API supports various data types as defined in the OpenAPI Specification. The specification uses the optional modifier property format to differentiate between fields of the same type. For example, a number field might have a format of float or double.

Integer data

Unless otherwise stated, all integer fields support the int64 format. To ensure that your application can successfully process integer data, you should always interpret integer generally to represent any non-fractional, non-decimal number.

String data

Unless otherwise stated, all string fields use UTF-8 encoding and do not enforce any length limits.