The Grover E-Commerce API V1 provides all information needed to display a Rent With Grover widget on third party pages. Availability of products are retrievable, along with rental plans and promotion information about a given product.

Management API

The first release includes an endpoint for displaying user-facing widgets only. A subsequent release will add management endpoints including one to retrieve rental plans – which can be used for reports or synchronising availability information, for example. Please do not call non-management APIs for these purposes, as any request will be treated as an impression in analytics.

Authentication

You have received a unique accessToken which authenticates your request and indentifies you and your store. Authenticate every request by including the ?accessToken=<token> parameter.

Authentication via Request Header is planned for a future version.

Endpoints

GET Product variant availability & rental plans

Use this endpoint to retrieve information needed to display a Rent with Grover button.

GET /api/v1/partners/products/{ articleID }

Endpoint returns information about matched product variant for the given partner store. Response will be 404 if the product is not known.

Request

https://api.getgrover.com/api/v1/partners/products/< article id >?access_token=< access token >&stock_absolute=< absolute stock level >&eans=< ean >

Request product variant information by providing the articleID parameter. API will match based on previously exchanged Article ID lists. Here’s a list of possible parameters:

Stock Level (Required, either-or)
- ?stock_absolute: Absolute number of assets in stock for given product variant.
- ?stock_enumerated: Enumerated amount of assets in stock for given product variant. (e.g. “low”, “medium”, “none”)
Delivery Time (either-or)
- ?delivery_date: Absolute estimated delivery date in format YYYY.MM.DD
- ?delivery_time: Relative estimated delivery time in days from now
?eans: See Passing EANs

Set your `Content-Type` header to `application/json`

Passing EANs

The EAN parameter is optional and can currently not be used for article matching. Its only purpose is for us to collect EAN information and build up a reliable database of EAN information, should such an agreement have been contractually made.

Most of the time, you will have only a single EAN to pass. In that case, just add the parameter like usually. If you have multiple EANs for the same product variant available, simply chain the parameter together multiple times, adding the [] denotion, for each EAN you would like to send.

...&eans[]=0077774865418&eans[]=0077774865425...

You can send as many EANs as you’d like.

Response

{
  "checkout_url": "www.wikipedia.com",
  "state": "available",
  "rental_plans": [
    {
      // rental plan object...
    },
    // ...
  ]
}

checkout:url: URL for “Rent now” button. Will forward user to Grover partner- and variant-specific landing page.

state: Available or hidden. See States.

rental_plans: Array of rental plan objects, contains pricing information for given variant.

If the endpoint replies 404, the provided article ID could not be matched to any product variant. This is a normal occurence if the rental portfolio agreed upon with Grover does not span your whole catalogue. For this reason, make sure you don't display the button at all if the API responds with a 404.

Common Objects

Rental Plan

A “Rental Plan” contains information about a specific minimum subscription length available for customers to choose from for a given product. If a product variant only has a single rental plan, treat it as a fixed base price (with minimum subscription length of that plan).

{
      "minimum_term_months": 12,
      "id": 27626,
      "price": {
          "cents": 5990,
          "currency": "eur",
      },
      "promotion_price": {
          "cents": 4900,
          "currency": "eur",
      },
      "is_cheapest": true,
      "description": null
}

id: Rental Plan ID.

rental_plan_price: Currency object containing rental plan monthly price. Includes price in cents and currency identifier according to ISO 4217.

minimum_term_month: Length of the plan’s minimum rental period.

promotion_price: If there is a promotion for this plan, this will include a currency object with the promotional price to display, otherwise null.

cheapest: If true, this rental plan is the cheapest available plan for this product.

description: Rental plan description. Might contain promotion information for this specific plan, otherwise null.

Concepts

State

State dictates what “state” a customer-facing widget should be in for the given product variant. Exact behaviour is determined by partner-specific agreements. The API returns either available, unavailable or hidden as state. As a standard, UI should behave as follows for a given state:

available: Product is ready to rent. Customer should see standard rental button.

unavailable: Customer can see the button, but it is in a disabled state due to unavailability at this time.

hidden: The button should not be shown for this product. 404 response will be interpreted as hidden state in frontend.

Testing and QA environments

We can provide you with special tokens for your QA and Staging environments. To set up a new environment, please contact us. We’ll synchronize some Article IDs and set up some example products so that you can get testing.