Shop Now: On-Store Headless Setup

OVERVIEW

Headless stores have a custom front-end that is completely separate from its back-end performance. In other words, headless stores customize their front-end from scratch to fit their brand, so they use Shopify’s back-end software, but they do not use Shopify’s theme builder to design their stores’ user interfaces (UIs). 

Most of Loop’s interactions with your Shopify store happen through the back end. However, merchants using Loop’s Shop Now: On-Store feature must connect Loop to their store’s front end to ensure a seamless customer experience.

In this article:

• How it works
• Setup instructions
  • Handle customers coming from Loop
    • Store the query parameters
    • Optional: Clean up the URL params
    • Optional: Show the customer how much credit they have
  • Create an On-Store cart
  • Prepare to send customers back to Loop
  • Send customers back to Loop with the On-Store cart

How it works

Merchants with headless stores may have heard of Hydrogen, Shopify’s central framework for building custom storefronts. This framework uses React, a UI development library built from JavaScript programming language. You can learn more from our Loop + Hydrogen article.

Setup instructions

First, you will need an API key from your store. To get the API key:

1. Go to Loop admin > Settings > Developers.

   
   

   

2. Scroll down to the “API keys” section.

3. Ensure that the “Scopes” column shows your chosen API key as “Cart” only. (Including more scopes could expose returns data. If you don’t have a Cart-only API key yet, you can create one.)

   

4. Copy your API key from the “Key” column, or keep this window open for later use.

Handle customers coming from Loop

At the beginning of the return process, Loop sends customers to your website with a set of query parameters. For a full list of params and an example URL you can copy and paste, please reference our On-Store API documentation.

Store the query parameters:

We recommend storing certain params for easier retrieval and use later on. To store the params:

1. Open your store’s website in a new tab or window.

2. Click the “Shop Now” option, as a customer might when going through the returns process for an item.

   

3. Find the params in your store’s URL. The params include everything after the question mark (?) and start with “loop.”

4. Store the back-end data you received in some form of client-side storage (we recommend the localStorage object). Below is an example of using localStorage in store code:

   

   If using a state management library such as Redux, we recommend also tracking the data there. Doing this can help you use the data to find the customer’s credit, which we cover later in this article.

5. Modify your code to now find your stored data, in addition to the query params. For example:

   

   Pulling your stored data ensures that the customer doesn't get lost if they refresh the page, or if you're working on a multi-page app.

Optional: Clean up the URL params

Once you save the data to localStorage, you no longer need the URL params. We recommend removing the query to keep your work clean:

1. Remove the URL query. For example:

let paramsObject = null;
// Check if we already have saved params
const savedParams = localStorage.getItem('loopOnstoreParams');
paramsObject = savedParams ? JSON.parse(savedParams) : null;
if (window.location.search.includes('loop_total')) {
const params = new URLSearchParams(window.location.search);
// Remove any non-loop related query params, then convert the query string
// to an object of key/value pairs to make it easier to work with
paramsObject = [...params.entries()].filter(([key]) => key.startsWith('loop')).reduce((acc, [key, value]) => {
return {
...acc,
[key]: value
};
}, {});
localStorage.setItem('loopOnstoreParams', JSON.stringify(paramsObject));
// Remove query params from the URL
    window.history.replaceState({}, '', `${window.location.origin}${window.location.pathname}`);
}

2. Clear the customer’s cart (how you do this depends on your cart setup). A clean cart for customers shopping with return credit a) can prevent issues with products already in the cart and b) ensures we grab everything the customer adds. If you need help, please contact support@loopreturns.com.

Optional: Show the customer how much credit they have

We also recommend informing the customer persistently that they are shopping with return credit to prevent confusion. To do this:

• Add a fixed element such as a bar at the bottom of the screen, or something similar, to display the credit amount. You can find the available credit amount in the " loop_total " param within your store’s code.
• Add a "Back to Return" button in the code so that the customer doesn’t lose their place. You can find a URL to redirect them to in the " loop_redirect_url " param.

Create an On-Store cart

To complete the customer’s On-Store experience, you must create and send customers to a separate cart. To make this separate cart:

1. When the checkout button is clicked, confirm in localStorage (or your other centralized storage) if the returned params indicate that the customer has return credit. 
2. If return credit exists, stop the customer from going to their normal checkout. For example:

// Check if we already have saved params
const savedParams = localStorage.getItem('loopOnstoreParams');
paramsObject = savedParams ? JSON.parse(savedParams) : null;
// How you bind this click handler depends heavily on what tech you're using, 
// this is vanilla JS to show the basic concept 
// This assumes a link with the id "checkout" is present on the current page
document.querySelector('#checkout').addEventListener('click', (e) => {
    if (savedParams) {
        // Stop the user from going to the checkout page
        e.preventDefault();
    }
});

3. Gather a list of Shopify variant IDs from your cart. How you get these IDs depends on how your cart is set up. If you need help, please contact support@loopreturns.com.
4. Create a new cart in Loop, entering the variant IDs where needed. If you want, you can test this process first on our interactive create cart endpoint page.
5. Find a) the token sent in your code response (you will use this token to access and modify your current cart going forward) and b) the return ID from the " loop_return_id " query param.
6. Save the token and the return ID to localStorage, separate from the params data you saved earlier. Later, you will use these fields to let customers return for a second round of shopping.

Prepare to send customers back to Loop

Loop then allows the customer to continue shopping if they would like. The customer returns to your store with the same params sent beforehand, so your preexisting code will pick that up. After receiving the params, do the following:

1. While saving the params to localStorage, find the cart token you saved. 
2. Check that the return ID paired with that token matches the current return ID. 
3. Make a call to the “get cart” API endpoint to confirm what's currently in the customer’s cart. You will need your store’s API key that you found earlier (refer to the beginning of “Setup instructions”). If you want to test your API call first, please visit our get cart testing endpoint.
4. Update the cart in your store to match the customer’s current cart so that the customer can pick up where they left off.
5. When preparing to send the customer back to Loop, once again check that you have a cart token matching the current return ID. 
6. If the return IDs match, use the “update cart” endpoint instead of creating a new cart. Test this call on our interactive page.

Send customers back to Loop with the On-Store cart

1. Remove from localStorage the params data you saved at the beginning (refer to Step 2 under “Store the query parameters”). This restores your shop to the normal shopping flow.
2. Clear your shop's cart.
3. Direct the customer back to Loop using the token of the cart you just created. Your redirect should look similar to this code:

https://SHOPNAME.loopreturns.com/#/cart/v2/TOKEN

If you have any questions along the way, please reach out to support@loopreturns.com.