Kroger...

Public APIs

Our RESTful public APIs are available for all clients to build new products, services, or customer experiences that leverage the unique data, functions, and applications of Kroger.

Authorization

All API requests are authorized using OAuth2 access tokens. When obtaining an access token, the following OAuth2 grant types are accepted:

Client Credentials

The Client Credentials grant type is for all service-to-service interactions, such as those between an application and a Kroger API. For more details on the Client Credentials grant type, see service to service authentication.

Authorization Code

The Authorization Code Grant is used for all interactions between third-party applications and customers, such as making a request on their behalf. For more details on the Authorization Code grant type, see customer authentication.

Requests

All APIs accept standard HTTPS requests. Public APIs support the following HTTP verbs when applicable:

Method Action
GET Retrieves resources
HEAD Acknowledges that a resource exists
POST Creates new resources
PUT Updates existing resources

Rate Limiting

All public APIs have a daily rate limit that is applied equally across all clients. Since the rate limits are applied to the API, we do not currently support individual rate limits by client.

To reduce the number of requests needed to complete an action, use 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 get several products instead of making individual requests for each product.

Responses

All API responses are returned as a JSON Object.

Response Status Codes

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.
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:

Authentication Errors

When the error is related to authentication, such as when getting an access token, 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 Errors

When the error is related to an API or API authorization, 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"
    }
}

API Quick Reference

The following table is a quick reference for all public APIs. For requirements and example data, see our full API Reference.

Path Query Parameters Scope API Rate Limit Description
/locations
/locations/{locationId}
  • filter.zipCode.near
  • filter.latLong.near
  • filter.lat.near
  • filter.lon.near
  • filter.radiusInMiles
  • filter.limit
  • filter.chain
  • filter.department
    Not required 1,600 per day Returns a list of store locations.
    /departments
    /departments/{id}
    • None
    Not required 1,600 per day Returns a list of departments.
    /chains
    /chains/{name}
    • None
    Not required 1,600 per day Returns a list of chains.
    /products
    /products/{id}
    • filter.term
    • filter.locationId
    • filter.productId
    • filter.brand
    • filter.fulfillment
    • filter.start
    • filter.limit
      product.compact 10,000 per day Returns a list of products.
      /coupons
      • filter.merchant (required)
      • filter.locationId
      • filter.productId
      • filter.channels
        coupons.basic 10,000 per day Returns a list of coupons.
        /identity/profile
          None
          profile.compact 5,000 per day Returns customer profile ID. Note: Requires customer authentication.
          /cart/add
            None
          cart.basic:write 5,000 per day Adds an item to a customer's cart. Note: Requires customer authentication.