Importing and exporting a contract CSV

You can use a CSV (comma-separated values) file to import contracts from a third-party subscriptions app into the Shopify Subscriptions app or export contracts from the Shopify Subscriptions app.

To learn more about how to use CSV files, refer to open and edit a CSV file.

Download a sample CSV file

You can download and view a sample contract CSV file to use as a template.

Considerations for the contract CSV file

Before you use contract CSV file to import contracts, review the following considerations.

Formatting the CSV file

For your contract CSV file to import correctly, verify the that it meets the following criteria:

• The first line of your contract CSV file must be the column headers as specified in the contract CSV description table.
• Each column must be separated by a comma.
• A CSV file can be a maximum size of 10 MB.

Note

If you use Excel to edit your CSV, then check Excel's export settings when you export the CSV to ensure that your file uses commas between values.

Understanding the handle column

The handle is used to uniquely identify each contract. Handles are used to manage data in the following ways:

• Grouping contracts with multiple line items: Contracts with multiple line items are grouped by a shared handle.
• Preventing duplicate contracts: Duplicate contracts are ignored on import. If a row with the same handle was previously imported successfully, then that row is skipped in the new import process. This mechanism helps to avoid duplication of data.

Note

If you have data exported from a different subscriptions app, then the handle will likely be a set of characters representing the ID for the customer's overall subscription. You can change the handle before you import as long as the handle is unique.

Multiple line item contracts

Contracts that include multiple line items require a separate row for each line item, and are grouped together with the handle column.

For example, if a contract has three line items, then each line item must be added as a separate row. The first row contains all of the contract information, and the next two rows only contain values in the following columns:

• handle
• line_variant_id
• line_quantity
• line_current_price
• Optional: line_selling_plan_id
• Optional: line_selling_plan_name

The handle must be identical for all three columns. All other columns in rows two and three must be empty.

Description of the CSV file

The information used in the contract CSV falls into the following categories: * The name of the contract * Customer and billing information * Delivery method and information * The items included in the subscription

All columns must be added to the CSV file to import correctly, and all fields are required unless otherwise noted.

Description of the columns in the contract CSV file.

Column	Description
Handle	Handles are the unique identifiers for each contract. Handles can contain letters and numbers, and are usually a combined string of letters, numbers, or both. Each contract must have a unique handle.
upcoming_billing_date	The upcoming billing date for the contract. Time is in UTC (Coordinated Universal Time), and must be formatted as YYYY-MM-DDTHH:MM:SSZ. For example, 3:50 pm on September 7, 2019 in the time zone of UTC (Coordinated Universal Time) is represented as 2019-09-07T15:50:00Z.
customer_id	The customer ID. The ID must match the ID of an existing customer in your Shopify admin.
currency_code	The currency code of the contract. The currency code must match a currency that is active in your store.
status	The status of the contract. Contracts can have one of the following statuses: Active Paused
cadence_interval	The delivery frequency of the subscription. A contract can have one of the following candence intervals: Week Month Year
cadence_interval_count	The delivery frequency of the subscription within the overall time interval. For example, the cadence interval count for every month is 1, and the cadence interval for every two weeks is 2.
customer_payment_method_id	The ID for the payment method used by the customer for the contract.
delivery_price	The price of the delivery in the correct currency format.
delivery_method_type	The delivery method of the subscription. The delivery method must be one of the following types: Shipping Local Delivery Pickup None
delivery_address_first_name	The first name of the recipient on the delivery address. This field is required for Shipping and Local Delivery methods only.
delivery_address_last_name	The last name of the recipient on the delivery address. This field is only required for Shipping and Local Delivery methods only.
delivery_address_address1	The first line of the delivery address. This field is only required for Shipping and Local Delivery methods.
delivery_address_address2	The second line of the delivery address. This field is only required if the address has a second field, and the delivery method is Shipping or Local Delivery.
delivery_address_city	The city of the delivery address. This field is only required for Shipping and Local Delivery methods.
delivery_address_province_code	The province or state of the delivery address. This field is only required for Shipping and Local Delivery methods.
delivery_address_country_code	The country code of the delivery address. This field is only required for Shipping and Local Delivery methods.
delivery_address_company	The company name of the delivery address. This field is only required if the order is for a business, and the delivery method is Shipping or Local Delivery.
delivery_address_zip	The postal code of the delivery address. This field is only required for Shipping and Local Delivery methods.
delivery_address_phone	The phone number of the delivery address. This field is only required for Shipping and Local Delivery methods.
delivery_local_delivery_phone	The phone number of the delivery address. This field is required for subscriptions with the Local Delivery method.
delivery_local_delivery_instructions	Local delivery instructions. This field is only needs to be included when instructions are provided for subscriptions with the Local Delivery method.
delivery_pickup_method_location_id	The location ID for the pick up method. This field is only required for subscriptions with the Local Pick up method.
line_variant_id	The ID for each line item included in the subscription. If there are multiple line items included in the subscription, then each line item must added as a new line with the unique variant ID.
line_quantity	The quantity for each line item included in the subscription. If there are multiple line items included in the subscription, then the quantity added should be for that specific item, not the total quantity of all items included.
line_current_price	The price of the subscription line item in the correct currency format.
line_selling_plan_id	The ID of the subscription plan. This field is optional.
line_selling_plan_name	The name of the subscription plan. This field is optional.

Import contracts using a CSV file

You can use a CSV file to import existing contracts from a third-party subscription app from the Shopify App Store or another Shopify store to your Shopify Subscription app. A CSV file can't be used to edit or overwrite existing contracts. Duplicates of existing contracts are ignored on import.

Caution

You need to use a correctly formatted CSV with all required fields to import the data. CSV files with missing or extra columns or data won't import.

Steps:

1. From your Shopify admin, go to Subscriptions > Contracts.
2. Click Import.
3. Click Add file, and then select the CSV file that you want to import.
4. Click Upload file.

After your CSV file is uploaded, you'll receive a confirmation email from Shopify at the email account used to set up your Shopify store. Read solutions to common import errors to help resolve any import issues.

Tip

To avoid issues when you upload your product CSV file, use the Google Chrome browser.

Export contracts using a CSV file

You can export your contracts for your records or to import into another Shopify store where you have the Shopify Subscriptions app installed.

Steps:

1. From your Shopify admin, go to Subscriptions > Contracts.
2. Click Export.