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 remove the product from your ShopWired account or change existing contracts.
Imports do not edit existing plan settings, create products, import subscription contracts or take payments. To edit an existing plan's settings, navigate to Plans. Read more about creating and managing 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
Exporting subscription plans
To export plans and find the IDs needed for an import:
- Navigate to Apps > Subscriptions in your ShopWired account
- Navigate to 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 - Select the History tab and select
Refresh historyuntil the export shows Ready to download - Select
Downloadto 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.
Exporting subscription contracts
Exporting subscription contracts
To export subscription contracts:
- Navigate to Apps > Subscriptions > Import and export
- Select the Export contracts tab
- Select the filters needed in Which contracts
- Select the information needed in What to include
- Select
Create export - Select the History tab and select
Refresh historyuntil the export shows Ready to download - Select
Downloadto save the file
The file is named subscription-contracts.csv. Read more about the records included in the export in the managing contracts guide.
Contract filters
| Setting | Guidance |
|---|---|
| ShopWired status | Filter by the contract's status in ShopWired, or select All |
| Renewal status | Filter by the 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.
The contract's ShopWired status and the app's renewal status describe different information. Read more about renewals and failed payments.
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 or move earlier subscriptions into the new app.
Creating new subscription plans
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.csvin your spreadsheet software - Replace the example rows with your own information, following the import column definitions below
- Add a row with
create_planin theactioncolumn for each new plan - Enter a different
plan_keyfor each plan and complete its plan settings - Leave
product_id,sku,plan_idandassignment_idblank on each plan row - To add a product to the new plan, insert an
add_assignmentrow below its plan row and enter the matchingplan_key,product_idand exactsku - Leave the plan settings,
plan_idandassignment_idblank 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 select to link a new plan to its product rows, such as monthly-box. It is different from the numeric plan_id assigned by ShopWired and is not shown to customers.
A product row for a new plan must refer to a valid plan row above it. Enter the matching plan_key explicitly to make this relationship clear. If both plan_key and plan_id are blank, the app uses the most recent valid plan row available above it. A removal row clears this automatic link.
Importing plans and assignments does not activate the new subscription system. Before activation, review the plans, product assignments and required theme changes. Follow the migration guide if you use the earlier Subscriptions app.
Adding products to existing plans
Adding products to existing plans
To add products or variations to plans that already exist:
- Export the required plans to obtain their
plan_idvalues - 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_assignmentrow for each product or variation to add - Enter the existing plan's
plan_id, the product'sproduct_idand its exactsku - Leave
plan_key,assignment_idand all plan setting columns blank - 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 code are separate values. Enter the numeric ShopWired product ID in product_id and the exact product or variation SKU code in sku. For a variation, use its parent product's ID and the variation's SKU code. Preserve the SKU code's letter case and any leading zeros.
Adding an assignment makes that product or variation available to purchase using the plan, subject to the plan and product settings. It does not add the product to existing customer subscriptions.
Removing product assignments in bulk
Removing product assignments in bulk
To remove products or variations from existing plans:
- Export plans with Include each plan’s products selected
- Locate the
plan_itemrow for each assignment to remove - Download the import template and remove its example data rows, keeping every column heading
- Add a
remove_assignmentrow for each assignment to remove - Copy
plan_id,assignment_id,product_idandskufrom the matching export row - Leave
plan_keyand all plan setting columns blank - 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 code
- 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 code no longer matches the file, correct the row using current information and check the file again.
Removing an assignment does not remove the product from ShopWired or change orders and contracts already created.
Uploading a file and checking the results
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 and drop the CSV file into CSV file, or select
browseto select 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 select the History tab and selectRefresh history - Select
View resultsfor the import and check every row - Select
Download resultsto 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.
A successful file check does not mean the import has completed. The app checks the relevant ShopWired records again when processing the import, because they may have changed since the file was checked.
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 account.
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 |
The downloaded results file contains the result codes and any recorded errors for each row. Use the app's results page to review the corresponding descriptions.
Successful imports are followed by an automatic update of the app's plan information. This can take several minutes. Check the affected plans and Last updated before creating an export.
Import column definitions
Import column definitions
Keep these 14 headings in this exact order. Leave unused cells blank and keep all columns in the file.
| Column 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. Leave blank 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 blank 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 blank for additions and removals |
false |
interval |
The subscription interval unit | Enter day, month or year for create_plan. Leave blank 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 blank for additions and removals |
1 |
cycle_limit |
The total 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 blank 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 blank 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 fixed unit price or percent_discount for a percentage discount. Leave blank for additions and removals |
none |
price_value |
The fixed price or percentage discount | Leave blank for none. For fixed_price, enter the unit price including VAT without a currency symbol. For percent_discount, enter a number greater than 0 and up to 100. Leave blank 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 blank for create_plan |
12345 |
sku |
The exact product or variation SKU code | Required for additions and removals. Preserve letter case and leading zeros; use up to 128 characters without spaces at the start or end. Leave blank for create_plan |
BOX-001 |
plan_id |
An existing plan's numeric ShopWired ID | Required for additions to existing plans and all removals. Leave blank 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. Leave blank for other actions |
27 |
For example, interval set to month and interval_count set to 2 creates a plan that renews every two months. It does not limit the subscription to two orders.
A cycle_limit of 6 allows the first order and five renewal orders. Read more about plan settings.
Fixed prices are checked against your account's VAT and currency settings. Enter no more decimal places than your currency supports. The app converts the VAT-inclusive amount to the amount stored in ShopWired. 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
Import examples
The examples below use illustrative IDs and SKU codes. Replace them with values from your own account. Blank 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,,
To create the plan without adding a product, include only the heading row and the create_plan row.
Add a product to an existing plan
This file adds product 12345, SKU code 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 code 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
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
| Column 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 subscription interval unit |
interval_count |
The number of interval units between renewals |
cycle_limit |
The total order limit, including the first order; 0 means unlimited |
trial_days |
The trial length in days; 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 code 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
| Column 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; blank 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 code 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.
| Column 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 subscription 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 |
Read more about how these schedules are used in the renewals and failed payments guide.
Import and export limits
Import and export limits
- Import files must use UTF-8 CSV format and contain no more than 1,000 data rows, excluding the heading row
- Import files must be no larger than 1 MB
- Exports can contain up to 50,000 data 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 updated information from ShopWired. 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
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 enter its matching plan_key.
For an existing plan, leave plan_key blank 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 code. For a variation, use the parent product's ID and the variation's SKU code.
Check that your spreadsheet software has not removed leading zeros, changed letter case or converted the SKU code into a date or number.
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 code are already assigned to the plan. A removal can fail if the assignment no longer exists or its product or SKU code has changed.
Check Plans, create a new export with products included and correct the row before checking the file again. Follow the creating and managing plans guide to review individual assignments.
An import needs review
Select the History tab, select View results and locate 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. The app needs permission to create plans or change product assignments for the actions in your file. Follow the connection checks in the Subscriptions v2 setup guide.
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 view the import and select Download results.