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 state processing, 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, either current, completed or future.
• 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; either old or months_to_own.
• remainingMonths: Int, remaining months until €1 offer, if type months_to_own.
• unavailableReason: String, either in_replacement or in_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, always print_return_label.
• remainingMonths: String, if unavailable for too_early, indicates after how many more months return will be possible.
• unavailableReason: String, too_early if it’s too early to return, in_replacement or in_return.

ReportDamage

The ReportDamage action includes data about reporting damage for a subscription asset to our insurance partners.

... on ReportDamage {
  action
  claimFormUrl
}

• action: String, always report_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, always support_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.