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 formatYYYY.MM.DD
?delivery_time
: Relative estimated delivery time in days from now
?eans
: See Passing EANs
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.
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.