> For the complete documentation index, see [llms.txt](https://help.smartrr.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartrr.com/docs/getting-started/implementation/installing-smartrr-on-a-headless-store.md).

# Installing Smartrr on a headless store

Implementing Smartrr on headless storefronts using the Shopify Plus API

{% hint style="warning" %}
**Note:** before implementing Smartrr, it's important to [<mark style="color:blue;">review Shopify's subscription requirements</mark>](https://help.shopify.com/en/manual/products/purchase-options/subscriptions/shopify-subscriptions/considerations) to determine your eligibility for offering subscriptions on your storefront. In the linked article, Shopify confirms what payment gateways are supported, and lists all other considerations to keep in mind before offering subscriptions.
{% endhint %}

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FRFKLvxSPBSbD3AfjxPgB%2Fimage.png?alt=media&amp;token=246e6e75-fc2a-41c9-a1bc-04ec39fd04eb" alt="Table listing considerations for subscription products (sales channel support, discounts, payment gateways, draft order restrictions) and the five supported payment gateways: Shopify Payments, PayPal Express, Authorize.net, Adyen and Stripe."><figcaption></figcaption></figure>

{% hint style="info" %}
**Smartrr works with New customer accounts, with one difference:** Smartrr's modern account portal doesn't replace Shopify's account page. Instead, you link customers to it from a menu, in one of two ways:

* **Link the app proxy URL (no theme edits needed).** Add your store's Smartrr proxy URL as a menu item in the New customer accounts menu or your store's main menu. For new installs, the proxy path is `/a/subscriptions/customer-portal`, for example `https://yourstore.com/a/subscriptions/customer-portal`. To confirm your store's path, open Shopify's app settings and find the proxy URL in Smartrr's app details.
* **Render the portal on its own page.** Create a page that displays the portal, then link that page from a menu. [\[See how to set up the Smartrr account portal on its own page →\]](https://relay-commerce.notion.site/How-to-Use-New-Customer-Accounts-public-facing-2a21e0df860a8053a66bd5294384a769)

![The customer account settings page in the Shopify admin. Shopify's new customer account doesn't provide a liquid file for the Smartrr customer portal to inject into. Instead, the Smartrr customer portal needs to be rendered on its own page and added to Shopify's customer account portal's menu options.](https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FwBEi2G2QrcDlsYq7BLbH%2FScreenshot%202023-02-24%20at%2008.39.57.png?alt=media\&token=23c62ad1-efb9-48b4-84b9-354faa56f51d)
{% endhint %}

## App Installation&#x20;

From the [<mark style="color:blue;">Shopify app store</mark>](https://apps.shopify.com/), install the Smartrr app.

![Add the Smartrr app to your Shopify store, and approve billing. You will enroll in a 14-day free trial before your approved plan goes into effect.](https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FxwTTdvswmyI175fUKWvg%2FSmartrr%20Help%20Docs%20%E2%80%93%209.jpg?alt=media\&token=0fbfd35c-05c0-4442-89f8-e3296c1f9cd8)

In your Shopify admin **(\[your-store-name].myshopify.com)**, navigate to 'Apps'. The Smartrr app should now show on your app list.

![Once Smartrr is installed, search for the Smartrr app in your app list. You can navigate here by going to Settings > Apps.](https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FPtmEhB5bpQpC21MtX4js%2FSmartrr%20App.png?alt=media\&token=4721a7b0-62f8-441e-8b0f-05c48af38c18)

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**.

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2Fi5nvNdtRZlOVXQbAzu3Y%2Fadd-api-key.png?alt=media&amp;token=9b38a9d3-1359-45f3-9f22-93854ae6fd8a" alt="API keys are found under the Integrations menu in the Smartrr admin. If you don&#x27;t have an API key, click on the &#x22;Create Key&#x22; button to create one."><figcaption></figcaption></figure>

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.

<figure><img src="https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FAy3QMSmTkcff9BIVU30J%2FSmartrr%20Help%20Docs%20%E2%80%93%2012.jpg?alt=media&amp;token=a1cff12f-51e1-4cdc-a52b-93115fc4850e" alt="When creating a Smartrr API key, you only need to set a nickname for your token and the application name (example: Nickname - Gorgias Key, Application Name - Gorgias)"><figcaption></figcaption></figure>

{% 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.

![Set the permissions for your token. You could choose read for all permissions and "read and write" where applicable.](https://3658670565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FndNAuxS4koYyI8AQTpS9%2Fuploads%2FDfyjY3SwT2xzgsbqSgx0%2FScreen%20Shot%202022-03-18%20at%202.26.31%20PM.png?alt=media\&token=6cb8d5eb-51c2-416e-bc9e-707ac4dea0cf)
{% endhint %}

## Headless Implementation

Use the below endpoint to call for information about product Subscription Programs.&#x20;

## 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:

<https://shopify.dev/docs/api/storefront/2024-10/queries/product>

### Method 2: Smartrr API

```
GET https://api.smartrr.com/vendor/selling-plan-group
```

This [get request](https://api.smartrr.com/docs/redoc/) queries your Smartrr account for all subscription programs you have created, and their selling plans.

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://<shopify domain>/cart/add
```

Be sure to replace \<shopify domain> 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](/docs/getting-started/implementation/installing-smartrr-on-a-custom-shopify-theme-guided-install.md) 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.&#x20;
   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 \<iframe> to display it. This works for headless shops using React.
3. Duplicate smartrr-account.liquid in HTML, replacing the liquid code with the corresponding HTML Code. This works for headless shops not using React.

For methods 2 and 3, please follow these additional instructions:

### Pulling in data for liquidCustomer

The /customer/auth/session endpoint expects a liquidCustomer object. If the [myshopify.com/account](http://myshopify.com/account) page is not used, the data may need to be pulled elsewhere. The customer data can be retrieved from[ Shopify Storefront API](https://shopify.dev/docs/api/storefront/2024-10/objects/Customer).&#x20;

Below is the schema for the object.

<pre><code>{
 shopifyId: string,
 email?: string,
<strong> phone?: string,
</strong> firstName?: string,
 lastName?: string,
<strong> trackShipmentText: string,
</strong> defaultAddressId?: number,
 defaultAddress?: MailingAddress,
 state?: string,
 customerCurrency: string,
 orderCount: number,
 totalSpent: number,
 addresses: MailingAddress[]
}
</code></pre>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartrr.com/docs/getting-started/implementation/installing-smartrr-on-a-headless-store.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.