Importing/exporting subscription data

Use the Subscriptions app's import/export system to manage subscription plans and their product assignments in bulk through a spreadsheet.

The import/export system supports the following actions:

Create new subscription plans
Add products or variations to new or existing plans
Remove product assignments from existing plans
Export plans and their product assignments
Export subscription contracts, their products, renewal history and renewal schedules

An assignment links a product or variation to a subscription plan. Removing an assignment removes that link; it does not delete the product from your ShopWired account.

Imports do not update existing plan settings, create products, import subscription contracts or take payments. To edit an existing plan's settings, open the plan in Plans.

Each import row contains one action. The column headings are fixed and must match the downloaded template. Open and edit CSV files in spreadsheet software such as Excel or Google Sheets.

Exporting subscription plans

To export plans and find the IDs needed for an import:

Navigate to Apps > Subscriptions in your ShopWired account
Open Import and export
Select the Export plans tab
Select a Plan status, or leave it as All
Select Include each plan’s products to include product assignments and their IDs
Select Create export
Open History and select Refresh history until the export shows Ready to download
Select Download to save the file

The file is named subscription-plans.csv. Each plan has a row with plan in the record_type column. When product assignments are included, each assignment has a separate plan_item row beneath its plan.

Use plan_id to identify an existing plan. To remove an assignment, copy plan_id, assignment_id, product_id and sku from that assignment's plan_item row.

Export files have a different format from import files. Copy the required IDs into the downloaded import template. Do not upload the export file as an import or treat it as a complete backup of the subscription system.

Exporting subscription contracts

To export subscription contracts:

Navigate to Apps > Subscriptions > Import and export
Select the Export contracts tab
Choose the filters needed in Which contracts
Choose the information needed in What to include
Select Create export
Open History and select Refresh history until the export shows Ready to download
Select Download to save the file

The file is named subscription-contracts.csv.

Contract filters

Setting	Guidance
ShopWired status	Filter by the contract's status in ShopWired, or select `All`
Renewal status	Filter by this app's renewal status, or select `All`
Next renewal from	Include contracts with a next renewal on or after this date
Next renewal to	Include contracts with a next renewal on or before this date
Customer ID	Enter the customer's numeric ShopWired ID to export their contracts
Plan name contains	Enter text from the plan name recorded when the contract was purchased; matching ignores letter case

Both next-renewal dates are included in the date range. These dates use GMT all year (UTC), rather than UK summer time. The first date must be on or before the second.

A renewal status filter excludes contracts without an app renewal schedule. A date filter excludes contracts without a matching next renewal date. A contract's recorded plan name may differ from the plan's current name.

Information to include

Setting	Information added to the export
Include each contract’s products	A separate `contract_item` row for each product, including its SKU and quantity
Include renewal history	Separate `intent`, `attempt` and `charge` rows for available renewals, payment attempts and one-off payments
Include this app’s renewal schedule	Seven additional columns describing the app's renewal status and schedule

Exports do not contain card details, ShopWired credentials or payment-provider responses. Contract exports cannot be used to import contracts.

Creating new subscription plans

To prepare a file containing new plans:

Navigate to Apps > Subscriptions > Import and export
Select the Import plans and products tab
Select Download template
Open subscription-import-template.csv in your spreadsheet software
Replace the example rows with your own information, following the import column definitions below
Add a row with create_plan in the action column for each new plan
Enter a different plan_key for each plan and complete its plan settings
Leave product_id, sku, plan_id and assignment_id empty on each plan row
To add a product to the new plan, insert an add_assignment row below its plan row and enter the matching plan_key, product_id and exact sku
Leave the plan settings, plan_id and assignment_id empty on each product row
Save the file as a UTF-8 CSV file and follow the uploading instructions below

Use a separate add_assignment row for each product or variation. The product must already exist in your ShopWired account.

The plan_key is a code you choose to link a new plan to its product rows, such as monthly-box. It is different from the numeric plan_id assigned by ShopWired. A product row must refer to a valid plan row above it. Leaving its plan_key empty uses the most recent valid plan row above it.

To create plans without products, include only the create_plan rows. Add products later through another import or from Plans.

Adding products to existing plans

To add products or variations to plans that already exist:

Export the required plans to obtain their plan_id values
On the Import plans and products tab, select Download template
Open the template and remove its example data rows, keeping every column heading
Add an add_assignment row for each product or variation to add
Enter the existing plan's plan_id, the product's product_id and its exact sku
Leave plan_key, assignment_id and all plan setting columns empty
Save the file as a UTF-8 CSV file and follow the uploading instructions below

An existing plan does not need a create_plan row. Several rows can use the same plan_id to add different products or variations to that plan.

The product ID and SKU are separate values. Enter the numeric ShopWired product ID in product_id and the exact product or variation SKU in sku. For a variation, use its parent product's ID and the variation's SKU. Preserve the SKU's letter case and any leading zeros.

Removing product assignments in bulk

To remove products or variations from existing plans:

Export plans with Include each plan’s products selected
Find the plan_item row for each assignment to remove
Download the import template and remove its example data rows, keeping every column heading
Add a remove_assignment row for each assignment to remove
Copy plan_id, assignment_id, product_id and sku from the matching export row
Leave plan_key and all plan setting columns empty
Save the file as a UTF-8 CSV file
Upload and check the file using the instructions below
Review each ShopWired target, including its assignment ID, product ID and SKU
Select I have checked each assignment and confirm its removal. before starting the import

Use assignment_id to identify the particular product assignment being removed. It is different from product_id and plan_id.

The app checks the current assignment before removing it. If its product or SKU no longer matches the file, correct the row using current information and check the file again.

Do not include an addition and a removal for the same product and SKU on the same existing plan in one file. Check the result of the first import before preparing a separate change.

Uploading a file and checking the results

To check and import a completed file:

Navigate to Apps > Subscriptions > Import and export
Select the Import plans and products tab
Drag the CSV file into CSV file, or select browse to choose it
Select Check file
Review Check the file, including the Valid and Errors counts
For existing plans, check the plan and product shown in ShopWired target against the change you intend to make
Correct any rows with errors in your spreadsheet, save the CSV and check it again
If the file removes assignments, select I have checked each assignment and confirm its removal.
When every row passes, select Import plans and products
Select Check progress, or open History and select Refresh history
Select View results for the import and check every row
Select Download results to save the row results

Checking a file does not make changes. Every row must pass the file check before the import can start. Use All rows, Valid and Errors to filter the check results. Select Download errors to save the messages for rows that need correction.

Imports and exports continue in the background after they start. Return to History to check progress; you do not need to keep the page open. The list shows the 20 most recent imports and exports for your shop.

Import result labels

Result	Meaning
Plan created	The new plan was created
Assignment added	The product or variation was added to the plan
Assignment removed	The product or variation was removed from the plan
Failed	The row could not be completed; read its details
Skipped	The row was not applied, for example because its new plan was not created
Not confirmed	ShopWired did not confirm whether the change was saved; check the affected plan before making another change
Not sent	The import stopped before this row was submitted

Finished means the import has finished processing, not that every row succeeded. Earlier successful rows are not undone when another row fails. Review the results before submitting another file.

Successful imports are followed by an automatic update of the app's plan information. This can take several minutes. Check Last updated before creating an export to confirm the changes appear in the exported data.

Import column definitions

Keep these 14 headings in this exact order. Leave unused cells empty and keep all columns in the file.

Field name	Description	Guidance	Example values
`action`	The change to make	Enter `create_plan`, `add_assignment` or `remove_assignment` in lower case	`add_assignment`
`plan_key`	A code linking a new plan to its product rows	Required on a new plan row; use the matching key on its product rows, or leave it empty to use the most recent valid plan row above. Leave empty when using an existing plan's `plan_id`. Use up to 100 letters, numbers, dots, hyphens or underscores	`monthly-box`
`plan_name`	The new plan's name	Required for `create_plan`, up to 100 characters. Leave empty for additions and removals	Monthly box
`enabled`	Whether the new plan is enabled	Enter `true` or `false` for `create_plan`; capitals are also accepted. Leave empty for additions and removals	`false`
`interval`	The billing interval unit	Enter `day`, `month` or `year` for `create_plan`. Leave empty for additions and removals	`month`
`interval_count`	The number of units between renewals	Enter a whole number from 1 to 9,999 for `create_plan`. Leave empty for additions and removals	`1`
`cycle_limit`	The number of orders before the subscription ends, including the first order	Enter `0` for unlimited orders, or a whole number from 1 to 9,999 for `create_plan`. Leave empty for additions and removals	`0`
`trial_days`	The free trial length in days	Enter `0` for no trial, or a whole number from 1 to 999 for `create_plan`. Leave empty for additions and removals	`0`
`price_modifier_type`	The new plan's pricing rule	Enter `none` for the product's normal price, `fixed_price` for a set price or `percent_discount` for a percentage discount. Leave empty for additions and removals	`none`
`price_value`	The fixed price or percentage discount	Leave empty for `none`. For `fixed_price`, enter the amount including VAT without a currency symbol. For `percent_discount`, enter a number above 0 and up to 100. Leave empty for additions and removals	`39.00` or `15`
`product_id`	The existing product's numeric ShopWired ID	Required for additions and removals. For a variation, use its parent product's ID. Leave empty for `create_plan`	`12345`
`sku`	The exact product or variation SKU	Required for additions and removals. Preserve letter case; use up to 128 characters without spaces at the start or end. Leave empty for `create_plan`	`BOX-001`
`plan_id`	An existing plan's numeric ShopWired ID	Required for additions to existing plans and all removals. Leave empty for `create_plan` and additions to a plan created earlier in the same file	`15`
`assignment_id`	The numeric ShopWired ID of the product assignment to remove	Required only for `remove_assignment`. Copy it from a plan export with products included	`27`

For example, interval set to month and interval_count set to 2 creates a plan that renews every two months.

Fixed prices are checked against your shop's VAT and currency settings. Enter no more decimal places than your currency supports. Percentage discounts accept up to four decimal places.

The original 12-column template is still accepted for creating plans and adding products to plans created in the same file. Use the current 14-column template for existing-plan additions and removals.

Import examples

The examples below use illustrative IDs and SKUs. Replace them with values from your own shop. Empty CSV cells are intentional.

Create a monthly plan and add a product

The first row creates a disabled plan. The next row adds a product to that new plan using its plan_key.

action,plan_key,plan_name,enabled,interval,interval_count,cycle_limit,trial_days,price_modifier_type,price_value,product_id,sku,plan_id,assignment_id
create_plan,monthly-box,Monthly box,false,month,1,0,0,none,,,,,
add_assignment,monthly-box,,,,,,,,,12345,BOX-001,,

Add a product to an existing plan

This file adds product 12345, SKU BOX-002, to existing plan 15. No plan row is needed.

action,plan_key,plan_name,enabled,interval,interval_count,cycle_limit,trial_days,price_modifier_type,price_value,product_id,sku,plan_id,assignment_id

add_assignment,,,,,,,,,,12345,BOX-002,15,

Remove two assignments from an existing plan

This file removes assignments 27 and 28 from plan 15. Each assignment must still match the product ID and SKU supplied on its row.

action,plan_key,plan_name,enabled,interval,interval_count,cycle_limit,trial_days,price_modifier_type,price_value,product_id,sku,plan_id,assignment_id
remove_assignment,,,,,,,,,,12345,BOX-001,15,27
remove_assignment,,,,,,,,,,12345,BOX-002,15,28

Export column definitions

Blank cells mean the information does not apply to that row or was not available when the app read the record. Dates and times in export files use GMT all year (UTC).

Plan export columns

Field name	Description
`record_type`	`plan` for a plan or `plan_item` for a product assignment
`plan_id`	The plan's ShopWired ID, repeated on its product rows
`assignment_id`	The assignment's ShopWired ID on a `plan_item` row
`plan_name`	The plan name where reported
`status`	The record's ShopWired status; a plan is `enabled` or `disabled`
`interval`	The plan's billing interval unit
`interval_count`	The number of interval units between renewals
`cycle_limit`	The order limit, including the first order; `0` means unlimited
`trial_days`	The trial length; `0` means no trial
`price_modifier_type`	The pricing rule: `none`, `fixed_price` or `percent_discount`
`product_id`	The product's ShopWired ID on a `plan_item` row
`sku`	The product or variation SKU on a `plan_item` row
`version`	ShopWired's version number for the record
`observed_at`	When the app last read the record from ShopWired

The plan export does not include price_value. Use Plans to view or edit the plan's price settings.

Contract export columns

Field name	Description
`record_type`	`contract`, `contract_item`, `intent`, `attempt` or `charge`
`contract_id`	The contract's ShopWired ID, repeated on its related rows
`resource_id`	The ShopWired ID of the record represented by this row
`parent_id`	The ID of the record this row belongs to; empty on a contract row
`status`	The record's status in ShopWired
`customer_id`	The customer's ShopWired ID where reported
`initial_order_id`	The order that started the contract
`plan_name`	The plan name recorded when the contract was purchased
`currency`	The currency where reported
`payment_method_type`	The payment method type where reported
`product_id`	The product's ShopWired ID on a `contract_item` row
`sku`	The product or variation SKU on a `contract_item` row
`quantity`	The product quantity on a `contract_item` row
`renewal_order_id`	The order ID reported for a renewal
`completed_at`	When the renewal or payment attempt completed, where reported
`version`	ShopWired's version number for the record
`observed_at`	When the app last read the record from ShopWired

Optional renewal schedule columns

Selecting Include this app’s renewal schedule adds the following columns. They are populated on contract rows with an app renewal schedule.

Field name	Description
`app_state`	The app's renewal status, such as `scheduled`, `paused` or `intervention_required`
`next_due_at`	The next renewal date and time
`schedule_timezone`	The time zone used by the renewal schedule
`schedule_interval`	The schedule's renewal interval unit
`schedule_interval_count`	The number of units between scheduled renewals
`completed_cycles`	The number of orders recorded as completed by the app, including the first order
`schedule_version`	The app's version number for the schedule

Import and export limits

Import files must use UTF-8 CSV format and contain no more than 1,000 data rows
Import files must be no larger than 1 MB
Exports can contain up to 50,000 rows and must be no larger than 32 MB
Product, renewal and payment rows count towards the export row limit

If an export is too large, narrow its filters or select fewer options in What to include and prepare another export.

Exports use the app's most recently synchronised information. The app updates this information automatically, but a recently completed import or a change in ShopWired may not appear immediately. Check Last updated and the export's observed_at values. Create a new export after the information has updated.

Resolving import and export problems

A product row asks for its plan above it

For a new plan, place a valid create_plan row above the product row and use its plan_key. For an existing plan, leave plan_key empty and enter the plan's numeric ID in plan_id. Do not enter an existing plan's ID as its plan_key.

A product or SKU cannot be found

Check product_id against the product in ShopWired and enter its exact SKU. For a variation, use the parent product's ID and the variation's SKU.

Before creating a plan, the app checks all product rows linked to it. If a product check fails, the plan is not created and its product rows are skipped. The plan's result identifies the product row to correct. The downloaded results include this row number in error_row where available.

A plan was already imported

Check History and Plans before submitting another file. Uploading an identical file returns its existing import rather than creating another one, including when earlier rows succeeded but the import did not finish successfully.

An earlier import can also prevent reuse of a plan key or name while its plan still exists or its result remains unresolved. If the plan already exists, add missing products using plan_id. Do not change the key to create another copy of the same plan.

An assignment cannot be added or removed

An addition can fail if that product and SKU are already assigned to the plan. A removal can fail if the assignment no longer exists or its product or SKU has changed. Check Plans, take a new export with products included and correct the row before checking the file again.

An import needs review

Open History, select View results and find the row marked Not confirmed. Check the affected plan and product assignment in Plans before making another change. The change may have been saved even though the app did not receive confirmation. Rows after it may show Not sent.

The import button is unavailable

Resolve every row error and select the removal confirmation if required. If the button remains unavailable, read the reason shown beneath it and check Connection. Your app connection needs permission to create plans or change product assignments for the actions in your file.

An export is unavailable or contains older information

Check Connection and allow the app to finish its full check with ShopWired. After a recent import, wait for Last updated to advance and create a new export. Use History to check whether the export finished or shows an error.

A download does not appear

Check your browser's downloads and allow downloads for the app if prompted. Return to History and select Download again, or open the job and select Download results.