The Submarine Customer API

The Customer API is used to build bespoke interfaces to allow customers to manage their stored payment methods and subscriptions.

It's designed to be called from within the context of a customer logged in to their Shopify account, either from a browser or other client (such as a mobile app).

The API follows the JSON API Specification, and provide endpoints for retrieving, creating and updating stored payment methods, subscriptions, and individual subscription orders.

A Javascript client library, Submarine.js is provided by Disco Labs to simplify interaction with the Customer API. This library can be imported into an existing theme development workflow, or included via a <script> tag.


Because the API is returning sensitive customer information (a list of their stored payment methods, saved subscriptions, and the contents of those subscriptions), authentication in required to retrieve or update any customer information.

Requests to the API are authenticated by providing three parameters in the querystring of all HTTP requests (whether GET or POST requests):

  • shop - the Shopify domain of the current store, eg;
  • timestamp - a UNIX timestamp of when the request was generated;
  • signature - a SHA256 HMAC signature generated from the ID of the logged in customer, the timestamp value, and a secret key made available to your theme via a shop-level metafield shop.metafields.submarine.customer_api_secret.

For Shopify themes, these values should be generated within your Liquid templates and passed to the Javascript code that will be making calls to the Customer API.

For other clients, such as mobile apps, these values should be generated within your application code before making calls.

Example generation

{% assign api_timestamp = 'now' | date: '%s' %}
{% assign api_data = | append: ':' | append: api_timestamp %}
{% assign api_signature = api_data | hmac_sha256: shop.metafields.submarine.customer_api_secret %}

  window.submarine = new Submarine({
    environment: "production",
    authentication: {
      shop: "{{ shop.permanent_domain }}",
      timestamp: "{{ api_timestamp }}",
      signature: "{{ api_signature }}"

Example request

An example authenticated API request to fetch the list of payment methods for the current customer (with an ID of 82500043234) may therefore look like the following: