1. Nomenclature
There are a number of resources that play together in Submarine. Some of them (such as customers, products and product variants) require no introduction, since they have identical or similar representations inside Shopify. Others, however, are perhaps less familiar, and it is these that we describe below.
Shopify purchase options
Submarine’s integration with Shopify leverages native behaviour around Subscriptions and Selling Plans. We assume that the reader is well versed in those concepts.
1.1. Channel
A channel represents an individual Shopify store. Although you should rarely need to interact directly with channels, most of the resources described here are scoped to a channel, so it makes sense to introduce the concept.
Attributes
- external ID The external ID of the channel. For Shopify, this is the ID of the store, e.g. 276250199.
- identifier A unique, human readable identifier for the channel. For a Shopify store, this is the Shopify domain, e.g. ”my-submarine-store.myshopify.com”.
- status Can be one of “active” or “inactive”. For Shopify, an example of an inactive channel is when the Submarine app is uninstalled from a store.
1. Subscription concepts
2.1. Subscription plan group
A subscription plan group defines how subscriptions can be offered to a customer, as well as how a subscription behaves once it’s been created. This includes which collections, products, or variants are available for subscription within the group, and the different behaviours attached to those products when they are part of a subscription (see Subscription behaviours).
2.2. Subscription plan
Each subscription plan group contains one or more subscription plans. Each subscription plan within a group has a unique subscription frequency, and may inherit or override the behaviours defined on the parent subscription plan group.
Subscription Frequencies define the recurrence of the subscription. The frequency is what the end customer will select in most cases. A frequency would be something like “every 2 weeks” or “every month”. At least one frequency and corresponding subscription plan must be defined for every subscription plan group.
2.3. Subscription
Once a customer placed an order containing one or more subscription items, a subscription is created. A subscription represents an single contract between the customer and the merchant, and is linked to a specific subscription plan (and corresponding subscription plan group).
It may have one or more lines, which point to the product and variant the customer is subscribed to.
2.4. Subscription order
A subscription has many subscription orders, each of which represents a single instance of a future order that will be generated as part of the subscription. Unlike many other platforms, Submarine allows each subscription order to be managed and updated independently for maximum flexibility.
The default Submarine behaviour is to generate the next ten upcoming subscription orders for a subscription, regardless of frequency.
2.5. Subscription behaviours
As noted above, subscription plan groups, subscription plans, and individual subscriptions may all have various types of behaviours defined.
Delivery behaviours define rules around when a customer will receive their order, and whether a customer’s individual subscription schedule needs to be aligned to a particular merchant-defined delivery schedule.
Billing behaviours piggyback off delivery behaviours to define when subscription orders are actually processed (ie, when they are charged and the order actually created).
They are responsible for specifying how two key attributes are calculated for each individual subscription order:
- A billing offset time, which is when an order needs to be successfully processed in order to meet the subscription order’s selected delivery window; and
- A processing time, which is when a subscription order should be processed.
The pricing behaviours specifies how much customers will pay for items in their subscription, both when they subscribe initially and over time. The pricing behaviours define both the base price and any applicable discounts.
An inventory behaviours defines the behaviour relating to stock and inventory in the subscription group when orders are being processed.
The inventory behaviour defines both an inventory decrement policy and an out of stock policy.
Payment concepts
3.1. Payment method
A payment method is a means of payment associated to a customer. It can have one or more payment instruments (e.g. card, PayPal), although only one of them can be active.
Attributes
- customer A reference to the customer that owns this payment method.
- external ID The ID that the external payment processor assigned to their corresponding payment method.
- metadata An optional set of arbitrary key/value pairs.
- status Can be one of “active” or “inactive”. Note that payments cannot be processed against an inactive payment method.
Payment instrument attributes
- active Whether or not the instrument is active. Although a payment method can have many instruments, only one of them can be active at any time.
- external ID The ID that the external payment processor assigned to their corresponding payment instrument.
- external reference A supporting reference for the external payment processor. For Shopify, this is usually set to the ID of the Shopify order, e.g. “gid://shopify/Order/5095136559344”.
- metadata An optional set of arbitrary key/value pairs.
- payment processor The external processor used to process the payment. For Shopify Payments, this is “shopify”.
- type The type of payment instrument. For Shopify, this can currently be “card” or “paypal”.
Card attributes
- brand The card brand, e.g. “mastercard”, “visa”.
- expiry month The month the card expires, as an integer, e.g. January is denoted as a 1.
- expiry year The year the card expires, as an integer, e.g. 2025.
- external ID The ID that the external payment processor assigned to their corresponding card. For Shopify, this is usually set to the ID of the payment mandate created at checkout, e.g. “gid://shopify/PaymentMandate/2470c5852eca3f416c83b54c84aaa413”.
- last 4 The last four digits of the card number, e.g. “4242”.
- metadata An optional set of arbitrary key/value pairs.
3.2. Charge
Details of unsuccessful charges and refunds are preserved and exposed by Submarine, allowing the merchant and customer to remain in the loop.
Charge attributes
- amount The amount charged.
- description An optional description for the charge.
- external ID The ID that the external payment processor assigned to their corresponding charge.
- failure code A machine-readable message describing the reason for a charge failure.
- failure message A human-readable message describing the reason for a charge failure.
- metadata An optional set of arbitrary key/value pairs.
- payment instrument A reference to the payment instrument associated to this charge.
- payment intent A reference to the payment intent associated to this charge.
- status One of “pending”, “succeeded”, “failed”.
- type One of “verify”, “authorise”, “capture”, “sale”.