Documentation

The Submarine Customer API

Suggest Edits

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.

Authentication

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 example.myshopify.com;
  • 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 = customer.id | append: ':' | append: api_timestamp %}
{% assign api_signature = api_data | hmac_sha256: shop.metafields.submarine.customer_api_secret %}

<script>
  window.submarine = new Submarine({
    environment: "production",
    authentication: {
      shop: "{{ shop.permanent_domain }}",
      timestamp: "{{ api_timestamp }}",
      signature: "{{ api_signature }}"
    }
  });
</script>

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:

GET https://submarine.discolabs.com/api/v1/customers/82500043234/payment_methods?shop=example.myshopify.com&timestamp=1556957501&signature=4400f4c50dc953d000a735beb5becd6460141980d3d0d5a207b47ec6b3124f5e

Updated over 3 years ago