Importing subscriptions to Submarine

Submarine offers a plug-and-play import framework for subscriptions. Out of the box, it will import subscriptions so long as we are provided with a CSV export that conforms to our agreed format. An optional SKU-mapping import is also supported, for cases when SKUs on the legacy platform do not align with SKUs on Shopify.


CSV validation

In addition to the format of the CSV, we also expect the import files to be well-formed and UTF-8 encoded. Tools such as csvlint can be used to determine if the CSV is malformed.

Subscription import

Subscription CSV that conforms to the following specification can be imported with no additional work. We assume the following:

  • Customers have been migrated to Shopify. Their email aligns with that provided in the CSV.
  • Products have been migrated to Shopify, with SKUs uniquely defining a variant.
  • For addresses, note that only address_1 and zip are required fields (as well as country). However, it is expected that all addresses supplied will be complete and valid (the importer will fail to import subscriptions when Shopify cannot validate the shipping address). This will usually involve populating some or all of province, province_code and city, but will vary from country to country. If a merchant has many addresses from a non-Shopify source, Disco recommends using a service like to 'clean' or 'verify' the shipping and billing address data.
  • Multicurrency is supported for Braintree only. If currency is supplied and is not the shop currency, then an exchange rate (shop currency to the second currency) should also be supplied along with the csv.

Import options

taxes_includedBoolWhether the prices given in the CSV include taxes or not.true
token_policyEnumHow the importer should determine what payment method to use β€” one of 'customer_default', 'first_active', 'last_active' or ''merchant_defined'.first_active

Subscription CSV

subscription_idFirst lineAn identifier for a unique subscription. Multiple rows may have the same subscription ID β€” if that's the case, each line with identical subscription ID will be grouped into the same subscription in Submarine.6847
store_emailFirst lineThe customer's 'store email', corresponding to the store email of the migrated customer record in Shopify.[email protected]
statusFirst lineThe status of the subscription β€” one of 'active', 'paused', 'pending_cancellation' or 'cancelled'. Merchants may choose to exclude paused and cancelled subscriptions from the
frequencyFirst lineThe frequency at which this subscription recurs, in the format 'magnitude_period', e.g. '2_weeks' or '3_months'.4_weeks
next_order_atFirst line if activeThe time the next order is due to be placed, in ISO8601 format. Only required if the subscription is currently active.2020-04-12T12:00:00Z
cancelled_atConditionalIf the subscription is cancelled (or pending cancellation), the time it was cancelled in ISO8601 format.2019-04-02T13:45:12Z
paused_atConditionalIf the subscription is paused, the time it was paused in ISO8601 format.2019-04-02T13:45:12Z
currencyFirst lineThe currency used to charge for the subscription, in ISO4217 format.AUD
noteNoAny note that should be added to each order generated in this subscription.Beware of the dog.
skuYesThe SKU of the subscribed line item.ABC123
quantityYesThe quantity of the subscribed line item.2
priceNoThe unit price of the subscribed line item, if different to that set in Shopify.12.99
shipping_line_descriptionFirst lineA description of the shipping method being used by the customer. If Shopify is being used as the source of truth for shipping costs, this should align with a Shopify shipping rate.Standard
shipping_line_priceNoThe amount to be charged for shipping. If absent, the shipping cost will be pulled from Shopify.9.99
billing_first_nameFirst lineCustomer's first name for billing purposes.Joan
billing_last_nameFirst lineCustomer's first name for billing purposes.Peterson
billing_companyNoCustomer's company name for billing purposes, if required.ACME Co
billing_address_1First lineFirst line of the customer's billing address.10 River Road
billing_address_2NoSecond line of the customer's billing address.Apartment 21B
billing_cityNoCity of the customer's billing address.New York
billing_provinceNoProvince name of the customer's billing address.New York
billing_province_codeNoProvince code of the customer's billing address.NY
billing_zipFirst lineZIP of the customer's billing address.10044
billing_countryFirst lineCountry code of the customer's billing address, in ISO-2 format.US
shipping_first_nameFirst lineCustomer's first name for shipping purposes.Joan
shipping_last_nameFirst lineCustomer's last name for shipping purposes.Peterson
shipping_companyNoCustomer's company name for shipping purposes, if required.ACME Co
shipping_address_1First lineFirst line of the customer's shipping address.10 River Road
shipping_address_2NoSecond line of the customer's shipping address.Apartment 12B
shipping_cityNoCity of the customer's shipping address.New York
shipping_provinceNoProvince name of the customer's shipping address.New York
shipping_province_codeNoProvince code of the customer's shipping address.NY
shipping_zipFirst lineZIP of the customer's shipping address.10044
shipping_countryFirst lineCountry code of the customer's shipping address, in ISO-2 format.US
discount_codeNoThe discount code that was applied to the subscription.FREEBIES
discount_valueNoThe value of the discount code.10
discount_amountNoThe dollar amount that's deducted from the subscription total as a result of the discount code.3.12
discount_typeNoThe type of discount that was applied to the subscription β€” one of 'first_amount', '' or 'percentage' or 'shipping'.percentage

SKU-mapping import

If the SKUs in the legacy store do not align with SKUs in the Shopify store, a SKU-mapping CSV that conforms to the following specification can be imported with no additional work.

SKU-mapping CSV


Atypical mappings

The importer is not limited to just 1:1 mappings of SKUs. A single legacy SKU can be mapped to multiple Shopify SKUs, with potentially differing quantities of each one.

old_skuYesThe SKU of the item as it appears in the subscription export.ABC123
new_skuYesThe SKU of the item as it exists in Shopify.K1-P2345
quantityNoThe number of items of the new SKU that should be substituted for one item of the old SKU. Defaults to 1 if not set.2