# Installing Smartrr on a headless store
Last updated: May 14, 2025
{% hint style="warning" %}
**Note:** before implementing Smartrr, it's important to [review Shopify's subscription requirements](https://help.shopify.com/en/manual/products/subscriptions/setup#eligibility-requirements) to determine your eligibility for offering subscriptions on your storefront. You must also have [inventory tracking](https://help.shopify.com/en/manual/products/inventory/transfers/enable-tracking) enabled for a product to be subscription-eligible.
{% endhint %}
{% hint style="info" %}
As of 2023, Shopify has begun offering **New customer accounts** as a setting option. New customer accounts are not compatible with apps; please ensure you are using **Classic customer accounts** with Smartrr in order to display our [Modern Account Portal](/docs/support/customer-account-portal/viewing-next-orders.md) where your customers will be able to access and manage their subscriptions.
{% endhint %}
## App Installation
From the [Shopify app store](https://apps.shopify.com/), install the Smartrr app.
In your Shopify admin **(\[your-store-name].myshopify.com)**, navigate to 'Apps'. The Smartrr app should now show on your app list.
Click on the Smartrr app to open. Navigate to the **Integrations** tab in the left-hand navigation and generate a new API token using the button that reads **Add Key**.
We recommend setting both your Token Nickname and your Application Name as the name of the platform you are authorizing for. We also recommend that Application Name specifically be in all capital letters, without spaces.
{% hint style="info" %}
**Important:** Ensure that token's permissions for Selling Plan are left set at the default selection: **Selling Plan: Read**. If permissions are toggled to "None" you will not be able to read Selling Plans from the API.
{% endhint %}
## Headless Implementation
Use the below endpoint to call for information about product Subscription Programs.
## Call Subscription Program Information
### Method 1: Shopify Storefront API
Using Shopify’s Storefront API, product’s selling plan groups can be pulled. To get only Smartrr selling plan groups, filter by appName and limit to Smartrr. Selling plans can be accessed from the selling plan groups.
To retrieve selling plans using Shopify's Storefront API, you can use a GraphQL query. Below is an example of how you might construct a query to fetch selling plans and their details based on a selling plan group:
```
query GetSellingPlansByProduct($first: Int, $productId: ID!) {
product(id: $productId) {
title
sellingPlanGroups(first: $first) {
edges {
node {
name
appName
options {
name
values
}
sellingPlans(first: $first) {
edges {
node {
id
name
description
options {
name
value
}
}
}
}
}
}
}
}
}
```
Shopify selling plan group documentation:[ https://shopify.dev/docs/api/storefront/2024-10/objects/SellingPlanGroup#top](https://shopify.dev/docs/api/storefront/2024-10/objects/SellingPlanGroup#top)
Shopify product documentation:
### Method 2: Smartrr API
```
GET https://api.smartrr.com/vendor/selling-plan-group
```
Subscription Programs are configured in the Subscription Programs tab in the left hand navigation of the Smartrr app.
#### Query Parameters
| Name | Type | Description |
| ----- | ---------- | -------------------------------- |
| cache | true/false | *Available values* : true, false |
{% code title="200: OK Successful responseCopy" %}
```
{
// Response
}
```
{% endcode %}
From the call response, use the data provided in the sellingPlans\[ ] array to power the storefront display. Submit the shopifyNumericId value for the field selling\_plan in the form POST submission in order to attach a Subscription Group alongside an item added to a customer’s cart.
## Attach Subscription Group to Item Added to Cart
```
POST https:///cart/add
```
Be sure to replace \ with your store's shopify domain. Note, this is required to be a part of cart workflow and not checkout workflow as Shopify does not support subscriptions within the checkout workflow.
For more information on this POST method, visit Shopify's documentation on[ ](https://shopify.dev/api/ajax/reference/cart)[Cart API References](https://shopify.dev/docs/api/storefront/2024-10/mutations/cartLinesAdd).
The selling\_plan property NEEDS to be provided for any subscription line item that is added to cart. Use the cartLinesAdd mutation from Shopify Storefront API to do this.
Shopify cartlinesAdd documentation:[ https://shopify.dev/docs/api/storefront/2024-10/mutations/cartLinesAdd#argument-lines](https://shopify.dev/docs/api/storefront/2024-10/mutations/cartLinesAdd#argument-lines)
200: OK JSON object of the line items associated with the added items422: Unprocessable Entity Occurs when the exact quantity specified for one of the items can't be added to the cart
```javascript
{
// Response
}
```
Important: The product/variant will need to be enabled for the respective Subscription Program in the Smartrr admin portal. These can be detected with the productIds\[ ] and/or variantIds\[ ] array.
## Displaying Account Portal
There are three methods for brands to display the Smartrr's Shopify liquid account portal on a headless shop.
We still recommend completing[ Smartrr's in-app Setup instructions](https://help.smartrr.com/docs/getting-started/implementation/how-do-i-install-smartrr-on-a-modified-or-custom-shopify-theme-guided-install) up to step 3. Smartrr Installation – part 1. Install Snippets onto a dummy theme for developers to see how Smartrr renders the account portal, or if your developers would like to duplicate a piece of liquid functionality to headless.
1. **\[Recommended]** Forward /account –related URLs to your {your-store}.myshopify.com domain.
1. This is our recommended method as it allows Shopify to continue handling all account actions (Login/Logout/Register/Checkout).
2. Create an account page on your site using the code found in your Shopify theme customers/account.liquid and use \