Front-end integration

Building world-class customer experiences, one front end at a time.

Introduction

One of Submarine’s core principles is to empower merchants (and front-end developers) to build creative and innovative customer experiences without limitation.

As such, our philosophy around integration of Submarine’s functionality into a Shopify store’s front end can be summed up as: do whatever you want!

To support this, Submarine doesn’t attempt to automatically add any code to a Shopify theme, or force you to use any Submarine-hosted “out of the box” customer-facing pages. Instead, we:

provide a comprehensive client-facing GraphQL API for retrieving and modifying data on behalf of customers;

maintain Shopify Purchase Option configurations on Shopify products and variants; and

further augment Shopify products and variants with Submarine-specific metadata for access via Liquid and the Storefront API.

These three features provide everything you need to build completely bespoke presale and crowdfunding experiences for customers, whether you’re working with a Liquid-based Online Store theme or a headless build.

Submarine GraphQL API

Submarine provides a universal GraphQL API that can be accessed from both front-end (client) and back-end (server) contexts. Different levels of access are granted depending on context the API is being used in — for example, using the API on behalf of a merchant from a back-end server will likely use a channel token with access to all of a merchant’s resources, while using it on behalf of an end customer within a browser context will almost certainly use a customer token scoped only to a specific set of resources (see Authentication for more).

In the vast majority of cases, developers building front end integrations for Submarine will be writing Javascript that (a) obtains a token for a currently logged-in customer, and (b) uses that token to retrieve information and perform actions on behalf of that customer.

To make that event more explicit, a typical theme integration involves writing some code within the logged-in customer account pages to fetch a list of a customer’s active presales via the Submarine GraphQL API, present them to the customer, and give them the option of modifying them (for example, the option of cancelling them), also via the API.

You can read the dedicated

Submarine GraphQL API page for more detail on how the API works, or read the guide for an end-to-end example.

Purchase Option configurations

To support presale and crowdfunding campaigns, Submarine makes use of Shopify’s native Purchase Option functionality. As such, key information such as whether a particular product or variant is part of a campaign and its resulting pricing configuration, is available through native Shopify selling plan information.

When building a front-end integration for Submarine, the product page for your presale and crowdfunded products will need to be updated to support the display of purchase option selling plans, and ensure that line items added to the cart from the product page are linked to the appropriate selling plan allocation.

It’s possible that the theme you’re working on already supports purchase options — if not, you can refer to Shopify’s guide on supporting purchase options in a Shopify theme, or see how they can be used in practice as part of the 🎨Creating presale product pages guide.

Submarine metafields

While Shopify’s selling plan information will indicate whether a product or variant is part of an active presale or crowdfunding campaign, there’s additional campaign information that’s useful to surface and display to customers on the product page for a presale or crowdfunded product. This information includes the current status of the campaign, the campaign timeline (launch, end and anticipated fulfilment dates), and the number of units currently sold.

Rather than require front end developers to retrieve this information via a call to the Submarine GraphQL API, Submarine augments products and variants with metafields that can easily be used to obtain up-to-date information about currently-running campaigns.

These metafields are attached in the submarine namespace on products and variants as JSON objects and can be accessed by both Liquid templates and the Shopify Storefront API.

The product-level metafield (eg product.metafields.submarine.presales) contains information about all of the presale campaigns the product has been part of (regardless of current campaign status), the timeline for each of those campaigns, and campaign-level stats like the number of units purchased.

The variant-level metafield (eg variant.metafields.submarine.presales) simply contains a map linking the ID of campaigns the variant has been a part of with the number of variant units sold for that campaign.

You can get a detailed breakdown of the field attributes in our 📖Front-end metafield reference, or see how they can be used in practice in the 🎨Creating presale product pages guide.

Shopify Storefront API

If you’re working in a headless environment, Submarine metafields can be retrieved via the Shopify Storefront API, and used to display information about the presale or crowdfunding status of a product or variants.

Example request

graphql
query getProductById($id: ID!) {
  product(id: $id) {
    id
    title,
    metafield(namespace: "submarine", key: "presales") {
      value
      type      
    },
    variants(first: 100) {
      edges {
        node {
          id
          title
          metafield(namespace: "submarine", key: "presales") {
            value
            type
          }
        }
      }
    }
  }
}

Example response

json
{
  "data": {
    "product": {
      "id": "gid://shopify/Product/8020835500322",
      "title": "DEEPS® Liquid - Lemon",
      "metafield": {
        "value": "[{\"cancelled_at\":\"2023-03-07T06:02:35.000Z\",\"completed_at\":null,\"deleted_at\":null,\"deposit_type\":\"percentage\",\"deposit_value\":\"0.0\",\"end_at\":\"2023-03-31T00:52:00.000Z\",\"ended_at\":\"2023-03-03T03:20:36.000Z\",\"fulfil_at\":\"2023-04-06T14:00:00.000Z\",\"fulfilling_at\":null,\"id\":\"0184c0df-775b-1d55-1bd7-a395e0f5e0b2\",\"launch_at\":\"2022-12-29T00:52:24.000Z\",\"launched_at\":\"2022-12-29T01:03:01.000Z\",\"limit\":100,\"reserved\":0,\"selling_plan_gid\":\"gid://shopify/SellingPlan/4464279842\",\"selling_plan_group_gid\":\"gid://shopify/SellingPlanGroup/746324258\",\"status\":\"cancelled\",\"total_campaign_reserved\":0}]",
        "type": "json"
      },
      "variants": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/ProductVariant/44108197757218",
              "title": "Mild (400mg)",
              "metafield": {
                "value": "[{\"0184c0df-775b-1d55-1bd7-a395e0f5e0b2\":{\"reserved\":0}},{\"0186b467-958b-3bed-9923-263684148a86\":{\"reserved\":9}}]",
                "type": "json"
              }
            }
          },
          {
            "node": {
              "id": "gid://shopify/ProductVariant/44108197789986",
              "title": "Medium (800mg)",
              "metafield": {
                "value": "[{\"0184c0df-775b-1d55-1bd7-a395e0f5e0b2\":{\"reserved\":0}},{\"0186b467-958b-3bed-9923-263684148a86\":{\"reserved\":0}}]",
                "type": "json"
              }
            }
          },
          {
            "node": {
              "id": "gid://shopify/ProductVariant/44108197822754",
              "title": "Strong (1200mg)",
              "metafield": {
                "value": "[{\"0184c0df-775b-1d55-1bd7-a395e0f5e0b2\":{\"reserved\":0}},{\"0186b467-958b-3bed-9923-263684148a86\":{\"reserved\":0}}]",
                "type": "json"
              }
            }
          }
        ]
      }
    }
  }
}

The structure of the returned metafield data is documented in the 📖Front-end metafield reference.

Note that the metafield data includes the Shopify selling plan ID (selling_plan_gid), which can be used to link a line item to the presale campaign via the sellingPlanId attribute when calling the cartLinesAdd mutation on the Storefront API.

Theme-development resources

While Submarine leaves a lot of control in the hands of front-end developers, we don’t want to leave you completely on your own to build everything from scratch, so we provide a number of resources to help get you up and running quickly with front end Submarine development.

Theme app extension

No one wants to spend time doing a bunch of theme development just to see how an application works or to place test orders.

To avoid front-end developers having to do this when getting started with Submarine, our application provides a theme app extension that can be drag-and-dropped into the product page form of any Online Store 2.0 Shopify theme.

While this selector isn’t super pretty, it hooks into the current selling plan options for a product and its variants, reads the relevant Submarine metafields, and displays a basic UI to the user that allows them to select a variant and purchase option before adding to cart.

Replacing the default variant selector with Submarine’s selling-plan selector.

Detailed instructions on how to add the theme app extension to an Online Store 2.0 theme and start placing presale or crowdfunding orders are available here.

Submarine.js client library

While we encourage front-end developers to interface with the Submarine GraphQL API as directly as possible, it’s never nice to have to implement your own boilerplate code for things like authentication or query execution.

To avoid this, we provider a minimalistic Submarine.js client library, which is designed to abstract away that boilerplate with a minimal JS library based on the Apollo Client JS framework.

🚧

The Submarine.js client library is currently in beta. Please contact us if you’re interested in using it for your implementation.

Reference implementations

Nothing is more helpful when you're building something for the first time than seeing how others have done it. That's why the Submarine team is creating a library of reference implementations for various Submarine integration points. The goal is to provide open-source examples that can be copied and pasted, or used as learning material for front-end developers.

🚧

Reference implementations for product page and customer account integrations using React components on Online Store 2.0 themes are in beta. Please contact us if you’re interested in accessing them for your implementation. Please also reach out if you have a particular technology or integration path you’re interested in seeing a reference implementation for.

Guides

Hand-in-hand with our reference implementations come a series of guides that step through the process of integrating Submarine with various components of a store's front-end.

🎨Creating presale product pages 🎨Creating crowdfunding product pages 🎨Creating customer account pages

Integration checklist

Boiling down all of the information above, here’s a list of the steps you’d take to fully integrate Submarine’s presale or crowdfunding functionality into a Shopify front end.

1. Install and configure Submarine

You can read step-by-step instructions on how to do this in

Getting started with Presales .

2. Customise the product page

Add support for displaying presale or crowdfunding information and purchase options to customers within your add to cart form.

You can follow the 🎨Creating presale product pages or guides in conjunction with the 📖Front-end metafield reference.

3. Customise customer account pages

If you want customers to be able to review and manage their active presale or crowdfunding campaign orders, you’ll need to build management functionality into the logged-in customer account section.

You can follow the guide and optionally leverage the Submarine.js client library to achieve this.

References

📖Front-end metafield reference

Submarine GraphQL API