Getting started

Getting things rolling with Submarine on your Shopify Plus store.

1. Theme quick-start

Submarine has a comprehensive API that allows theme developers to integrate it seamlessly into any Shopify theme. Some use cases include:
  • supporting regular and campaign purchases on the product page;
  • exposing detailed campaign options on cart pages; and
  • building out beautiful portals for customers to manage their purchases.
However, if you just want to get up and running quickly, with the minimal effort, Submarine provides a simple theme extension so that customers can opt in to delayed payment for presale and crowdfund campaigns.

💡
Dawn theme The Submarine theme extension has been tested with recent versions of the Dawn theme.

1.1. Configuring the Submarine theme extension

  1. Navigate to your published theme and click the “Customise” button.
  1. Using the drop-down box at the top of the screen, pick the product page that you want to add the theme extension to.
  1. In the “Product information” section, click “Add block” and select the Submarine “Selling plan selector” — it’s at the bottom, in the “Apps” collection.
    1. Adding the Submarine selling-plan selector to your product page.
      Adding the Submarine selling-plan selector to your product page.
  1. Since this extension also provides a variant selector, it makes sense to remove the default one that comes with Dawn.
  1. Move the selector to somewhere that makes sense for your customer flow (under the price is decent start).
    1. Replacing the default variant selector with Submarine’s selling-plan selector.
      Replacing the default variant selector with Submarine’s selling-plan selector.
  1. Click “Save”.
  1. Confirm that the changes are working in your store, by previewing the theme. Note that, if this is a fresh Submarine install, then the only purchase option available will be “One-time purchase”.
    1. Everything looking good in the theme.
      Everything looking good in the theme.

2. Creating your first presale campaign

🥅
Goal Create a presale campaign in the Submarine UI.

With the theme ready, you are now in a position to create your first presale campaign.
  1. Navigate to the Submarine homepage and click the green “Add presale” button in the top right-hand corner.
  1. You’ll be presented with a screen similar to this one:
    1. The starting place for presale creation.
      The starting place for presale creation.
      We have a detailed breakdown of how Submarine works in
      🗂️
      Key concepts
      , so for now we’ll just go over the basics.
      • Presale campaigns can be defined on one or more products or one or more variants, but not a mix of both. If you choose the wrong target when you create the campaign, the only option you have available is to delete it and start again.
      • Presale campaigns defined on products are exposed to every single variant of that product, throughout the lifetime of the campaign. This means that if you create a product campaign and then add a new variant to that product, customers will be able to purchase the new variant as a presale.
      • Presale campaigns defined on variants are only ever exposed on the selected variants.
      • Presale campaigns have four important milestones in their lifecycle, all of which can be configured on creation.
        • The date that the campaign will be launched. Before then, customers will not be able to purchase the presale.
        • The date that the campaign ends. After then, customers will be unable to purchase the presale.
        • The date that the campaign should be fulfilled. This field is optional. If left blank, fulfilment will commence as soon as inventory is applied. If it’s defined, fulfilment will be delayed until the provided date, even if inventory has been made available.
        • The grace period provided to customers, so that they can rectify their payment details should any payment fail. If this is set to “None”, then customers have one chance to pay for their presale before Submarine cancels their campaign order.
        • Note that all times for these milestones are defined in the shop’s timezone.
      • Presale campaigns should be given a reference. This is only ever used internally, and aids identification for you, the merchant, while navigating the Submarine UI. This field will automatically be populated with the name of the first selected product/variant, but can be overwritten.
      • Each presale campaign needs a limit. This is the maximum combined units of the items that can be sold as part of the campaign. It should be stressed that this is the total across all campaign items, and is not a per-item limit.
      • As mentioned elsewhere, Submarine integrates very closely with Shopify’s purchase options, and relies heavily on their concept of selling plans (to the extent that each Submarine campaign creates and maintains a Shopify selling plan under the hood). The name and description of the selling plan is automatically exposed to the customer in the theme, and this screen allows the merchant to configure what values these fields should take.
        • The default values follow Shopify’s recommended best practice, but they can obviously be overridden with anything.
        • Both fields support placeholder text — these placeholders are surrounded by double curly braces (e.g. {{due_at}}), and will be replaced with the appropriate underlying data when the selling plan is created (or updated) on Shopify.
        • The supported placeholders are launch_at, end_at, fulfil_at and due_at. The first three align exactly with the milestone fields discussed above. The due_at placeholder is a combination of end_at and fulfil_at, and will take whatever value is set.
    2. When all is said and done, you should have a form similar to this:
      1. An example of a completed presale-campaign form.
        An example of a completed presale-campaign form.
    3. Clicking “Save” creates the campaign in Submarine and bumps you back to the presale list.
      1. Your first presale campaign!
        Your first presale campaign!
    4. As well as the changes in the Submarine UI, there are also a few noticeable updates in the Shopify UI.
      1. The Shopify product page exposes the newly created purchase option. From here, you can manage the presale campaign without navigating to the Submarine UI.
        1. Note that the selling-plan name, configured in the Submarine UI when the campaign was created, has been properly parsed.
          The purchase option created by Submarine for the newly created presale campaign.
          The purchase option created by Submarine for the newly created presale campaign.
          Showing details of which variants are part of the purchase option.
          Showing details of which variants are part of the purchase option.
          More details about Submarine’s integration with Shopify’s Admin UI can be found at
          Submarine and the Shopify UI
          Submarine and the Shopify UI
          .
      2. The variant page exposes the same purchase option (with the same management features).
        1. The purchase option created by Submarine for the newly created presale campaign.
          The purchase option created by Submarine for the newly created presale campaign.
      3. Submarine created some metafields on the product and the variants. These are maintained throughout the lifetime of the campaign, and support sophisticated theme customisations.
        1. The Submarine product metafields.
          The Submarine product metafields.
          The Submarine variant metafields.
          The Submarine variant metafields.
          More details on these metafields can be found in the
          🎨
          Front-end integration
          documentation.

3. Launching your presale campaign

🥅
Goal Manually launch a presale campaign, so that customers can purchase it.

Submarine will automatically launch the campaign according to the configuration that you provided when the presale was created. If you’re impatient though, you can force an immediate launch.
  1. First off, let’s navigate to the detail view of the campaign in the Submarine UI. Go to the Submarine homepage and click on the one-and-only presale shown in the list.
  1. You’ll be presented with a page that looks similar to this:
    1. The detail view of a Submarine presale campaign.
      The detail view of a Submarine presale campaign.
      There’s a fair bit going on here, most of which we’ll touch on below, but for the time being we can see that the campaign has been given an ID of #1000, is in a pending state and inventory has not yet been allocated.
  1. Note that, since there have been no purchases made against the campaign, we’re able to cancel and delete it.
    1. If we wanted to, we could cancel or delete the campaign.
      If we wanted to, we could cancel or delete the campaign.
  1. However, we don’t want to do that right now. Instead, we want to force the launch of the campaign, so that our impatient customers can start purchasing it. We do that by clicking the green “Launch” button in the top-right corner.
    1. Manually launching our campaign prematurely.
      Manually launching our campaign prematurely.
  1. There are two immediate effects as a result of this action.
    1. First, the new status of the presale is reflected in the Submarine UI.
      1. The presale campaign has been launched!
        The presale campaign has been launched!
        Note also that the “Launch” button has disappeared and has been replaced with a (disabled) “End” button. The button in this location will always indicate what is the next step in the campaign’s lifecycle, and will usually provide the option to manually override it. Here, we are unable to end the campaign because we haven’t received any orders for it.
    2. More importantly though, the selling plan is now exposed to customers in the theme, which means that they can purchase our new presale campaign.
      1. Exposing the freshly launched presale campaign to customers.
        Exposing the freshly launched presale campaign to customers.
        Note that both the name and description of the selling plan (as configured when we created the presale campaign) is displayed in the selling plan selector.

4. Purchasing your presale campaign

🥅
Goal Purchase a presale campaign via the Shopify checkout, as if you were a customer.

As a merchant, it makes sense to familiarise yourself with the subtle differences that a customer experiences at checkout when purchasing a presale campaign.
  1. From the product page, in the selling-plan selector, make sure you select the “Presale” radio button. If you’ve only created one campaign for this variant, then the drop-down box should only have one option, and should be displaying the selling-plan name that you configured when you created the presale.
  1. Add the item to your cart and review your cart contents. Submarine fully supports mixed carts, but we’ll be keeping it simple here and will stick to just one presale item.
    1. The Shopify cart page, with a single presale item.
      The Shopify cart page, with a single presale item.
      Note the additional checkbox just above the “Pay now” button. The customer cannot complete checkout until they acknowledge the deferred payment for the presale item.
      Also note the cart summary on the right-hand side — it indicates that nothing is due to be paid now, and informs the customer when the balance will be captured. Submarine will soon allow you to configure deposits on presale campaigns, both as a percentage and a fixed value.
  1. Complete the checkout as usual. The experience should be identical to that of a regular order.
  1. If we navigate to the newly created order in the Shopify Admin UI, we can see some obvious differences.
    1. A Shopify order for a presale campaign.
      A Shopify order for a presale campaign.
      • The fulfilment for the campaign item is “On hold”, with the hold reason given as “Unknown delivery date”.
      • The fulfilment for the campaign item displays the selling-plan name, as configured in the Submarine UI when you created the presale campaign.
      • Payment is flagged as pending, with a due date of 13 March 2023. This aligns with the end date of the presale campaign.
      • In the timeline, you can see that Submarine updated the payment terms for the order soon after it was created. This is to handle the case when an order contains multiple campaign items. Since Shopify does not yet support partial payments against a purchase option, and instead only permits a single payment for the entire balance owing, we push the expected due date for that payment from the date at which the first presale is due (the default) to the date at which the last presale is due. This behaviour better meets the requirements of most of our merchants, but Submarine can be configured to revert to Shopify’s default behaviour. See
        ⚙️
        Configuring Submarine
        .
  1. If we navigate to the presale campaign in the Submarine UI, we can see some differences there too.
    1. The new campaign order in the presale campaign page.
      The new campaign order in the presale campaign page.
      • The most obvious change is that we now have a campaign order in the list at the bottom of the page. It details the campaign item, the customer and the Shopify order, and we can easily see the three statuses: the campaign order is in a pending state, the payment is pending and the fulfilment is on hold.
      • We can also see how that single order has affected the campaign’s progress. In the top-right corner, in the campaign summary card, the progress bar has been updated to reflect the fact that 1 out of our 50 limit has been reserved (representing 2%).
  1. Clicking the new campaign order, we get a more-detailed view.
    1. The detail view of the new campaign order.
      The detail view of the new campaign order.
      • We can see the fulfilment status from Shopify mirrored here, with the fulfilment flagged as being placed on hold on 6th February.
      • We can also see a breakdown of the payments — both the split between campaign order and Shopify order, an analysis of any deposits captured at checkout, and a list of any charges, refunds and adjustments that have been processed against the campaign order.
      • From here, the merchant is also able to cancel the campaign order.
        • Cancelling a campaign order from the Submarine UI.
          Cancelling a campaign order from the Submarine UI.

5. Ending your presale campaign

🥅
Goal Manually end a presale campaign, to enable inventory application.

We’re nearing the end of a campaign’s lifecycle now. As with launch, we could wait until the campaign end date rolls around and have Submarine transition the presale to the ended state automatically. Alternatively, we can accelerate that process and end the campaign manually.
  1. Navigate to the presale campaign page in the Submarine UI.
    1. The same presale campaign, but with a few more orders.
      The same presale campaign, but with a few more orders.
      A few more campaign orders have been placed since last time we saw it, but all we need is a single active one in order to end it prematurely.
  1. Click the “End” button in the top-right corder, and confirm the request.
  1. Confirm that the presale is no longer available in the theme.
    1. An ended campaign is not exposed to customers.
      An ended campaign is not exposed to customers.

6. Applying inventory to your presale campaign

🥅
Goal Apply inventory to your presale campaign, to begin payment capture and fulfilment.

Picking up from 5. Ending your presale campaign above, we can progress to the last stage of the presale lifecycle.
  1. With the presale campaign in an ended state, we are now able to apply inventory to the campaign items. Hover over each one, and you’ll be presented with an “Apply inventory” button.
    1. Opening the “Apply inventory” modal.
      Opening the “Apply inventory” modal.
  1. Clicking it opens up the “Apply inventory” modal.
    1. Configuring how much inventory to apply.
      Configuring how much inventory to apply.
      We can apply any amount of inventory to the items, but clicking “Meet reserved counts” applies just enough to cover the reserved count.
  1. Clicking “Apply” kicks off the allocation process.
    1. Submarine allocating inventory in the background.
      Submarine allocating inventory in the background.
      It runs in the background, so the presale moves into short-lived “Fulfilling” and “Allocation queued” states.
  1. After a few minutes, the process has completed.
    1. A completed presale campaign in the Submarine UI.
      A completed presale campaign in the Submarine UI.
      • The presale statuses have transitioned to “Completed” and “Allocated”.
      • The active campaign orders have all transitioned to “Completed”, “Payment received” and “Fulfilment open” states.
      • The presale campaign is ready to be archived.
  1. Lastly, picking one of the Shopify orders as an example, we can see the effect the presale completion has had.
    1. An order for a completed presale campaign in the Shopify UI.
      An order for a completed presale campaign in the Shopify UI.
      • The hold on the fulfilment has been released.
      • The order has been paid in full.