LogoLogo
  • πŸ› οΈWelcome to Smartrr help docs
  • Links
    • Changelog
    • API Docs
  • Getting Started
    • Implementation
      • πŸͺ„Installing Smartrr on a Shopify 2.0 theme (Automatic Install)
      • πŸ—ΊοΈInstalling Smartrr on a custom Shopify theme (Guided Install)
      • πŸ§Ÿβ€β™‚οΈInstalling Smartrr on a headless store
      • πŸ’»Adding Smartrr to a custom page (Shopify Liquid)
    • Onboarding
      • ⛑️Basic onboarding process
      • 🧀Smartrr team led onboarding
      • πŸ’΅Plans
      • πŸ’³Migrating subscriptions from payment processors
  • Support
    • Subscription Setup
      • πŸ“‡Subscription Programs
      • βš“Subscription anchor dates
      • πŸ—“οΈMaximum/minimum (finite) subscription plans
      • πŸ“§Email subscription notifications (Customer Notifications)
      • πŸ“²SMS subscription notifications (via Twilio)
      • πŸ›οΈSubscription discount codes
      • πŸ’ΈPrepaid subscriptions
      • πŸͺœSequential Flow Builder?
      • πŸ“¦Shipping methods
      • ❔Subscriptions when an item is unavailable
      • πŸ’²Buy-now-pay-later payment methods for subscriptions
      • 🏁Checkout Extensions
    • Admin Portal
      • πŸ”Adjusting customers’ subscriptions
      • πŸ“‡Adjusting customers' information
      • πŸ€Έβ€β™‚οΈ"View as customer" feature
      • πŸ•’Event log
      • πŸ“ŠAdvanced Analytics reporting
      • πŸ–ŒοΈCustomer account portal theming
      • πŸ”€Translations
      • πŸ’»Available actions for customers in account portal
      • 🎨CSS overrides
      • πŸ” Adjusting typography with CSS overrides
      • πŸ“£Marketing Banners
      • πŸ’­Retention
      • 🧺Bundles
      • 🎁Loyalty
      • πŸ”Passwordless login
      • πŸ’ŸCreator upsells
      • 🎞️Instagram feed
    • Customer Account Portal
      • πŸšͺAccessing the Customer Account Portal
      • πŸ”„Creating an account
      • πŸ”œViewing next orders
      • πŸ“Manage subscriptions
      • πŸ—ƒοΈOrder history
      • πŸ“§Updating email address
    • Transactions
      • 🀝Subscription transactions
      • 🚫Failed payments
      • πŸ“†Billing schedule
    • Integrations
      • 🌐Available integrations with Smartrr
      • πŸ“±Attentive x Smartrr Integration
      • πŸ“±Blueprint x Smartrr Integration
      • πŸ“¬Gorgias x Smartrr Integration
      • πŸ“©Klaviyo x Smartrr Integration
      • 🦁Loyalty Lion x Smartrr Integration
      • πŸ“±Postscript x Smartrr Integration
      • πŸ”Recharge x Smartrr Integration
      • 🟩Shopify Flow x Smartrr Integration
      • πŸͺWebhooks
    • Shopify Questions
      • πŸ’²Will updating product prices in Shopify reflect in Smartrr?
    • Developer Documentation
      • Bundles: Developer Documentation
    • Troubleshooting
      • ⏸️Why did my customer's subscription automatically pause?
      • πŸ“žWhy is my customer's shipping address invalid? (Phone number formatting)
      • πŸ†˜Can’t find the answer to your question?
    • RSS Feed
      • πŸ“³Smartrr’s changelog: Stay up-to-date with Slack
Powered by GitBook
On this page
  • App Installation
  • Headless Implementation
  • Call Subscription Program Information
  • Method 1: Shopify Storefront API
  • Method 2: Smartrr API
  • Attach Subscription Group to Item Added to Cart
  • Displaying Account Portal
  • Pulling in data for liquidCustomer

Was this helpful?

Export as PDF
  1. Getting Started
  2. Implementation

Installing Smartrr on a headless store

Implementing Smartrr on headless storefronts using the Shopify Plus API

PreviousInstalling Smartrr on a custom Shopify theme (Guided Install)NextAdding Smartrr to a custom page (Shopify Liquid)

Last updated 5 months ago

Was this helpful?

Last updated: April 3, 2024

Note: before implementing Smartrr, it's important to to determine your eligibility for offering subscriptions on your storefront. You must also have enabled for a product to be subscription-eligible.

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 where your customers will be able to access and manage their subscriptions.

App Installation

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.

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.

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

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

200: OK Successful responseCopy
{
    // Response
}

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.

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.

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

{

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

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

Below is the schema for the object.

{
 shopifyId: string,
 email?: string,
 phone?: string,
 firstName?: string,
 lastName?: string,
 trackShipmentText: string,
 defaultAddressId?: number,
 defaultAddress?: MailingAddress,
 state?: string,
 customerCurrency: string,
 orderCount: number,
 totalSpent: number,
 addresses: MailingAddress[]
}

From the , install the Smartrr app.

Shopify selling plan group documentation:

For more information on this POST method, visit Shopify's documentation on.

Shopify cartlinesAdd documentation:

We still recommend completing 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.

The /customer/auth/session endpoint expects a liquidCustomer object. If the page is not used, the data may need to be pulled elsewhere. The customer data can be retrieved from.

πŸ§Ÿβ€β™‚οΈ
Shopify app store
https://shopify.dev/docs/api/storefront/2024-10/objects/SellingPlanGroup#top
Cart API References
https://shopify.dev/docs/api/storefront/2024-10/mutations/cartLinesAdd#argument-lines
Smartrr's in-app Setup instructions
myshopify.com/account
Shopify Storefront API
review Shopify's subscription requirements
inventory tracking
Modern Account Portal