Submarine
Search…
Customer API
Documentation for 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.
Instructions and code examples for using the Submarine.js client library are available on Github.

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

accounts.liquid
1
{% assign api_timestamp = 'now' | date: '%s' %}
2
{% assign api_data = customer.id | append: ':' | append: api_timestamp %}
3
{% assign api_signature = api_data | hmac_sha256: shop.metafields.submarine.customer_api_secret %}
4
5
<script>
6
window.submarine = new Submarine({
7
environment: "production",
8
authentication: {
9
shop: "{{ shop.permanent_domain }}",
10
timestamp: "{{ api_timestamp }}",
11
signature: "{{ api_signature }}"
12
}
13
});
14
</script>
Copied!

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:
1
GET https://submarine.discolabs.com/api/v1/customers/82500043234/payment_methods?shop=example.myshopify.com&timestamp=1556957501&signature=4400f4c50dc953d000a735beb5becd6460141980d3d0d5a207b47ec6b3124f5e
Copied!
For brevity, we omit these authentication parameters from the endpoint documentation below, but note that they are required for all requests.

Payment method endpoints

get
https://submarine.discolabs.com
/api/v1/customers/{{ customer_id }}/payment_methods.json
List payment methods
post
https://submarine.discolabs.com
/api/v1/customers/{{ customer_id }}/payment_methods.json
Create new payment method
delete
https://submarine.discolabs.com
/api/v1/customers/{{ customer_id }}/payment_methods/{{ id }}.json
Remove existing payment method

Subscription endpoints

get
https://submarine.discolabs.com
/api/v1/customers/{{ customer_id }}/subscriptions.json
List subscriptions
patch
https://submarine.discolabs.com
/api/v1/customers/{{ customer_id }}/subscriptions/{{ id }}.json
Update existing subscription
delete
https://submarine.discolabs.com
/api/v1/customers/{{ customer_id }}/subscriptions/{{ id }}.json
Delete existing subscription

Subscription order endpoints

get
https://submarine.discolabs.com
/api/v1/customers/{{ customer_id }}/subscriptions/{{ subscription_id }}/subscription_orders.json
List subscription orders
patch
https://submarine.discolabs.com
/api/v1/customers/{{ customer_id }}/subscriptions/{{ subscription_id }}/subscription_orders/{{ id }}.json
Update existing subscription order
Last modified 1yr ago