Kroger...

Partner APIs

Our RESTful partner APIs enable official partners to access strategic functionality and data. Since the needs of our partners determine these APIs, they are not open for public consumption.

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 detail on the Authorization Code grant type, see customer authentication.

Requests

All APIs accept standard HTTPS requests. Partner 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
DELETE Deletes resources

Rate Limiting

There are currently no rate limits on the number of requests to partner APIs.

Responses

All API responses are returned as a JSON Object.

Status Codes

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

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 partner APIs. For requirements and example data, see our full API Reference.

Path Actions Query Parameters Scope Description
/locations
/locations/{locationId}
GET
HEAD
  • filter.zipCode.near
  • filter.latLong.near
  • filter.lat.near
  • filter.lon.near
  • filter.radiusInMiles
  • filter.limit
  • filter.chain
  • filter.department
    Not required Returns a list of store locations.
    /departments
    /departments/{id}
    GET
    HEAD
    • None
    Not required Returns a list of departments.
    /chains
    /chains/{name}
    GET
    HEAD
    • None
    Not required Returns a list of chains.
    /products
    /products/{id}
    GET
    • filter.term
    • filter.locationId
    • filter.productId
    • filter.brand
    • filter.fulfillment
    • filter.start
    • filter.limit
      product.basic
      product.personalized
      Returns a list of products.
      /coupons GET
      • filter.merchant
      • filter.locationId
      • filter.productId
      • filter.channels
        coupons.basic Returns a list of coupons.
        /my_coupons POST
        DELETE
        • filter.merchant
          coupon.personalized:rw Add or delete a coupons from a customer's loyalty card. Note: Requires customer authentication.
          /identity/profile GET
          HEAD
            email
            profile.name
            profile.basic
            profile.full
            profile.loyalty
            profile.exists
            Returns customer profile ID or queries a profile by email. Note: Requires customer authentication when returning profile information.
            /identity/profile/loyalty GET
              email
              profile.loyalty
              profile.full
              Returns profile loyalty information. Note: Requires customer authentication.
              /carts
              /carts/{id}/items
              /carts/{id}/items/{upc}
              GET
              POST
              PUT
              DELETE
              • None
              cart.basic
              cart.basic:rw
              Adds an item to a customer's cart. Note: Requires customer authentication.
              /collections GET
              • filter.name
              • filter.type
              collection.basic
              collection.basic:rw
              Returns a list of customer collections. Note: Requires customer authentication.
              /courier/deliveries GET
              POST
              • filter.followingAction
              • delivery_id
              delivery.basic
              delivery.basic:rw
              Returns a list of available deliveries for courier confirmation.