API Basics

The following sections cover basic functionality of our APIs.

Rate Limiting

All public APIs have a daily rate limit that is applied equally across all clients. Since the rate limits are applied to individual endpoints, we do not currently support individual rate limits by client. Rate limits reset 24 hours after the first call to an endpoint.

At this time, there is no rate limits on the number of requests to Partner APIs.

To reduce the number of requests needed for rate limited APIs, we recommend using parameters to fetch multiple resources in a single request. For example, if you need to return several products from the same location to complete an action, use the productId filter to return all of the products instead of making individual requests for each.

Responses

All API responses are returned as a JSON Object.

Status Codes

Partner and Public APIs support the following HTTP status codes:

Status Code Description
200 OK - The request was successful.
201 Created - The request was successful, and a new resource was created.
204 No Content - The request was successful but returned no body.
400 Bad Request - The request could not be completed due to invalid syntax.
401 Unauthorized - The request could not be completed because the client is not authorized to access the resources. While the request is unauthorized, this error often means that the client has not authenticated.
403 Forbidden - The request could not be completed because the client does not have access to the resource.
404 Not Found - The requested resource could not be found.
409 Conflict - The request conflicts with the current state of the server.
500 Internal Server Error - There was an internal error, and the request could not be completed.

Pagination

Since some of our APIs return large sets of data, pagination is returned in the metadata for all APIs that return a response body. The pagination object always returns the following values as a JSON object:

Value Type Description
total integer The total number of resources in a response.
start integer The starting point of results in a response.
limit integer The limit of results in a response.

Some APIs accept query parameters such as filter.limit and filter.start to limit the amount of data returned. As an example, the following product API request uses the filter.limit query parameter to limit the results to two products.

Request

curl -X GET \
  'https://api.kroger.com/v1/products?filter.term=milk&filter.limit=2' \
  -H 'Accept: application/json\' \
  -H 'Authorization: Bearer {{TOKEN}}' 

While 3104 total products are matching the given term, the response only returns two, starting with the first resource.

Response

{
    "data": [
        {
            "productId": "0001111043115",
            "upc": "0001111043115",
            "aisleLocations": [ ... ],
            "brand": "Kroger",
            "categories": [ ... ],
            "description": "Kroger®  Low Fat Chocolate Milk",
            "images": [ ... ],
            "items": [ ... ],
            "itemInformation": { ... },
            "temperature": { ... },
            "taxonomies": [ ... ]
        },
        {
            "productId": "0001111042210",
            "upc": "0001111042210",
            "aisleLocations": [ ... ],
            "brand": "Kroger",
            "categories": [ ... ],
            "description": "Kroger®  Sweet Acidophilus Low Fat Milk",
            "images": [ ... ],
            "items": [ ... ],
            "itemInformation": { ... },
            "temperature": { ... },
            "taxonomies": [ ... ]
        }
    ],
    "meta": {
        "pagination": {
            "start": 1,
            "limit": 2,
            "total": 3104
        }
    }
}

Error Objects

Whenever a request is unsuccessful, one of the following two types of errors is returned:

Auth Error

When the error is related to authentication or authorization, the following information is returned as a JSON object:

Value Type Description
error string A brief description of the error.
error_description string A more detailed description of the error.
{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has expired"
}

API Error

When the error is related to an API request, the following information is returned as a JSON object:

Value Type Description
timestamp string The time the error occurred.
code string The code returned from the server. In many cases, the code is a combination of the API name, an identification number, and the status code of the response.
reason string A short description explaining the cause of the error.
{
    "errors": {
        "timestamp": 1568391692365,
        "code": "PRODUCT-2011-400",
        "reason": "Field 'locationId' must have a length of 8 characters"
    }
}