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_1andzipare 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 ofprovince,province_codeandcity, but will vary from country to country. If a merchant has many addresses from a non-Shopify source, Disco recommends using a service like https://smartystreets.com/ 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
Option | Type | Description | Example |
|---|---|---|---|
taxes_included | Bool | Whether the prices given in the CSV include taxes or not. | true |
token_policy | Enum | How the importer should determine what payment method to use — one of 'customer_default', 'first_active', 'last_active' or ''merchant_defined'. | first_active |
Subscription CSV
Field | Required? | Description | Example |
|---|---|---|---|
subscription_id | First line | An 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_email | First line | The customer's 'store email', corresponding to the store email of the migrated customer record in Shopify. | |
status | First line | The status of the subscription — one of 'active', 'paused', 'pending_cancellation' or 'cancelled'. Merchants may choose to exclude paused and cancelled subscriptions from the migration. | active |
frequency | First line | The frequency at which this subscription recurs, in the format 'magnitude_period', e.g. '2_weeks' or '3_months'. | 4_weeks |
next_order_at | First line if active | The 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_at | Conditional | If the subscription is cancelled (or pending cancellation), the time it was cancelled in ISO8601 format. | 2019-04-02T13:45:12Z |
paused_at | Conditional | If the subscription is paused, the time it was paused in ISO8601 format. | 2019-04-02T13:45:12Z |
currency | First line | The currency used to charge for the subscription, in ISO4217 format. | AUD |
note | No | Any note that should be added to each order generated in this subscription. | Beware of the dog. |
sku | Yes | The SKU of the subscribed line item. | ABC123 |
quantity | Yes | The quantity of the subscribed line item. | 2 |
price | No | The unit price of the subscribed line item, if different to that set in Shopify. | 12.99 |
shipping_line_description | First line | A 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_price | No | The amount to be charged for shipping. If absent, the shipping cost will be pulled from Shopify. | 9.99 |
billing_first_name | First line | Customer's first name for billing purposes. | Joan |
billing_last_name | First line | Customer's first name for billing purposes. | Peterson |
billing_company | No | Customer's company name for billing purposes, if required. | ACME Co |
billing_address_1 | First line | First line of the customer's billing address. | 10 River Road |
billing_address_2 | No | Second line of the customer's billing address. | Apartment 21B |
billing_city | No | City of the customer's billing address. | New York |
billing_province | No | Province name of the customer's billing address. | New York |
billing_province_code | No | Province code of the customer's billing address. | NY |
billing_zip | First line | ZIP of the customer's billing address. | 10044 |
billing_country | First line | Country code of the customer's billing address, in ISO-2 format. | US |
shipping_first_name | First line | Customer's first name for shipping purposes. | Joan |
shipping_last_name | First line | Customer's last name for shipping purposes. | Peterson |
shipping_company | No | Customer's company name for shipping purposes, if required. | ACME Co |
shipping_address_1 | First line | First line of the customer's shipping address. | 10 River Road |
shipping_address_2 | No | Second line of the customer's shipping address. | Apartment 12B |
shipping_city | No | City of the customer's shipping address. | New York |
shipping_province | No | Province name of the customer's shipping address. | New York |
shipping_province_code | No | Province code of the customer's shipping address. | NY |
shipping_zip | First line | ZIP of the customer's shipping address. | 10044 |
shipping_country | First line | Country code of the customer's shipping address, in ISO-2 format. | US |
discount_code | No | The discount code that was applied to the subscription. | FREEBIES |
discount_value | No | The value of the discount code. | 10 |
discount_amount | No | The dollar amount that's deducted from the subscription total as a result of the discount code. | 3.12 |
discount_type | No | The 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.
Field | Required? | Description | Example |
|---|---|---|---|
old_sku | Yes | The SKU of the item as it appears in the subscription export. | ABC123 |
new_sku | Yes | The SKU of the item as it exists in Shopify. | K1-P2345 |
quantity | No | The 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 |
Updated 9 days ago