The Grover Management GraphQL API provides information on users and subscriptions for your application, allowing you to, for example, retrieve statuses of orders placed from your store. In the future, the API will be expanded to allow querying of amongst other things, Products, giving you the ability to fully integrate with Grover.
E-Commerce API
Looking to add a “Rent with Grover” button on your site? Use the Grover E-Commerce API instead.
Authentication
If you need to access secure fields (such as user information), you will receive a unique ID and client secret for your application. With this information, you can request an oAuth access token.
Request Access Token
In order to receive an access token, POST your credentials to the following endpoint.
POST https://api.getgrover.com/api/v1/oauth/token/
We expect a JSON payload with the following contents:
{
"grant_type": "client_credentials", // always client_credentials
"client_id": "< clientId >", // your client ID
"client_secret": "< clientSecret >" // your client secret
"scope": "< grantScopes >" // your requested scopes
}
The reponse will include a JSON object with an access_token
. This Bearer token grants you access to requested scopes. It is valid for a short amount of time – if requests for private fields fail, simply request a new access_token
and retry.
Grant Scopes
Available scopes are public
, personal
, sensitive
. You may request multiple scopes at the same time by seperating them with spaces. Your scope determines the fields you can access, and your access token may only grant you access to a limited amount of scopes. Please contact your account manager for more details.
Authenticating with GraphQL requests
Available types and fields depend on your credential’s access level, which is negotiated with you specifically. If you request the GraphQL schema, only fields available with your access level will be returned.
In order to include your access_token
with your GraphQL queries, simply set an Authorization
header containing “Bearer “ followed by the access_token
you received from the oauth token endpoint.
Querying Data
All following types are available at a single GraphQL endpoint.
POST https://api.getgrover.com/graphql
GraphQL Introspection
When you request available GraphQL fields as __schema
, be aware that only fields you have permissions to access are displayed. Querying the schema is supported exactly as per the specification.
Handling nulls
In some expected cases, some fields may not be available. In this case, we will return null
. Please generally treat null
as an expected response — for example, a subscription in state processing
may not yet have an asset assigned to it, which results in asset
to be null
. If there are any errors, we will always return an error on either the specific field or full response, never a null
.
Query types
Requesting a user
Request a specific user with the user
type and an id
variable. The following fields are available:
user(id: 'userId') {
birthdate
email
firstName
id
lastName
phone
phoneVerified
subscriptionAllowance
subscriptionLimit
subscriptionsTotal
}
birthdate
: String, user’s birthdate expressed in YYYY-MM-DD format.email
: String, email user signed up with.firstName
: String, first name(s).lastName
: String, last name(s).id
: ID, user ID (same as used for querying).phone
: String, user’s phone, with country code, but without leading + (e.g. “4912837584”).phoneVerified
: Boolean, if the phone number has been verified using a standard SMS code process.subscriptionLimit
: Number, the subscription limit assigned to this user (may not rent more than this sum monthly) in euros.subscriptionsTotal
: Number, the total monthly amount of all subscriptions for this user in euros.subscriptionAllowance
: Number, limit minus total.
Requesting a subscription
Request a specific subscription with the subscription
type and an id
or number
.
subscription(number: 'subscriptionNumber') {
asset
contractNumber
id
name
number
paymentMethod
shippingProgress
subscriptionActions
variant
}
state
: String, see “Subscription States”.asset
: Asset, the asset assigned to this subscription. See “Asset”.contractNumber
: String, contract number used for insurance purposes.id
: ID, subscription ID.name
: String, returns custom name for subscription given by the customer or the product’s name if unnamed.number
: String, subscription number.paymentMethod
: PaymentMethod, the payment method currently assigned to this subscription. See “Payment Method”.shippingProgress
: Array of ShippingProgress, if currently in stateprocessing
, otherwise null. See “Shipping Progress”.subscriptionActions
: Array of SubscriptionAction, or null if none. See “Subscription Actions”.variant
: Variant, includes information about the product variant this subscription is for. See “Variant”.
Subscription States
processing
: The subscription is currently being processed by Grover and has not yet entered it’s usual billing cycle. See “Shipping Progress” for more details.active
: Subscription is on its nominal billing cycle.paused
: Subscription billing is temporarily suspended, for example for a replacement or shortly before a return is processed.ended
: Subscription contract is irreversably cancelled, for example after a return.
Asset
asset {
productNumber
serialNumber
}
productNumber
: String, special asset ID used for insurance purposes.serialNumber
: String, the serial number of specific asset, or IMEI for GSM-enabled assets.
Shipping Progress
shippingProgress {
name
state
description
subSteps {
name
state
description
}
}
Shipping Progress includes user-facing information about the current status for a processing
subscription. The shippingProgress resolver returns an ordered array of Progress objects, each containing name
, state
and description
. The subSteps
is a nested array of the same object shape, giving more details about a given top-level step.
name
: String, the representational name of the step.description
: String, the representational description of the step.state
: ProgessState, eithercurrent
,completed
orfuture
.subSteps
: Array of shippingProgress.
This is how we display Shipping Progress on our customer-facing dashboard using this data:
Subscription Actions
An Action encodes a possible action a user may take on a subscription, together with representational data in order to explain why an action may be unavailable or when it might become available. subscriptionActions
is a union type of the currently possible actions: Buyout, PrintReturnLabel, ReportDamage, and SupportRequest. If an action is null
, assume it should currently not be shown to the customer at all. If an action has an unavailableReason
, it should be displayed as disabled.
Buyout
The Buyout action includes data about the purchase option for this subscription.
If the subscription uses our new purchase option (type months_to_own
), it will return a number of remaining months after which the asset may be acquired for a transaction of €1. The customer may also at any point in time purchase the asset by paying out remaining months * monthly price.
If the subscription uses our legacy purchase option (type old
), we can not unfortunately not give any data about the current purchase price with GraphQL. The action in this case should just lead the user to their Dashboard, where they can trigger the old purchase flow and get educated about their offer.
... on Buyout {
action
remainingMonths
type
unavailableReason
}
action
: String, always “buyout”.type
: String, type of purchase option; eitherold
ormonths_to_own
.remainingMonths
: Int, remaining months until €1 offer, if typemonths_to_own
.unavailableReason
: String, eitherin_replacement
orin_return
.
PrintReturnLabel
The PrintReturnLabel action includes data about the ability to return the device and end the rental.
... on PrintReturnLabel {
action: String!
remainingMonths: String
unavailableReason: String
}
action
: String, alwaysprint_return_label
.remainingMonths
: String, if unavailable fortoo_early
, indicates after how many more months return will be possible.unavailableReason
: String,too_early
if it’s too early to return,in_replacement
orin_return
.
ReportDamage
The ReportDamage action includes data about reporting damage for a subscription asset to our insurance partners.
... on ReportDamage {
action
claimFormUrl
}
action
: String, alwaysreport_damage
.claimFormUrl
: String, URL to the report damage form for the appropriate insurance provider.
SupportRequest
The Support Request action includes data for a customer support request action. This action is usually available, but may be temporarily disabled to manage CS ticket volumes. In a subscription representation, only offer a direct customer support request if this action is available.
... on SupportRequest {
action
}
action
: String, alwayssupport_request
.
PaymentMethod
PaymentMethod is a union type that includes representational information about the payment method currently assigned to the subscription.
paymentMethod {
... on Card {
lastDigits
}
... on PayPal {
email
}
}
If Card
, resolves the last 4 digits as lastDigits
. If PayPal
, resolves the PayPal account email as email
.
Variant
Variant includes information about the product variant that this subscription is for. A product variant is a specific color of a product.
variant {
colorCodes
colorTitle
imageUrl
}
colorCodes
: Array, variant’s product color as hex in string format. For representational purposes, simply select index 0.colorTitle
: String, name of the color.imageUrl
: String, URL to an image of this specific variant.