Guide: Migrate Existing Subscriptions
Migrating existing Subscriptions and Customers into Limio
After transitioning your commerce and self-serve journeys to Limio, you'll want your existing customers to fully use Limio's self-serve features and capabilities.
Limio requires a migration as a Zuora Subscription will not usually hold sufficient information to enable self-service. For example, Limio requires:
a Limio Identity that maps to your Identity Provider ID and other applications such as Salesforce to recognise an online user.
a Limio Offer to define an Offer Label to route the subscriber to the correct switch (upgrade/downgrade) or cancel Page.
a Limio Product to define whether delivery fields are required in the checkout.
This guide provides an overview on how to migrate in bulk your existing customers from your previous billing stack or loading them from Zuora into Limio. At a high-level, you will need to populate a CSV file that will be imported into Limio and automatically create all the Limio objects for you.
Please note that these steps are general, and your specific implementation may require additional considerations. There are also other ways to import data into Limio such as Configure Zuora to Limio Hot Sync.
If you have any questions, reach out to your project team for support.
Pre-Requisite
Before you start a migration, you should make sure you have the following:
You have defined Limio Offer that maps to what is commercially available on your Zuora Subscription. For example, if you have a Zuora Subscription with a Digital Product and a Monthly Rate Plan that is Auto-Renew with a USD currency, you will want to define a matching Limio Offer for this.
You have defined the primary identifier from your Identity Provider. Read more .
Process Overview
1. Accessing File Upload Permissions
To start the migration process:
Ensure you have access to the CSV ingestion bucket in Limio.
Request access from Limio support to upload your CSV files for migration.
2. Preparing Your Files
Prepare your migration files as follows:
Structure and Headers: Create a CSV file with the structure outlined below, ensuring headers match exactly (case sensitive). While not all fields are mandatory, required fields must be included to avoid record failures.
File Size: Limit each file to under 5000 records for optimal reliability and to avoid database throttling or data loss during upload.
File Naming: Name your files with the prefix "Limio_". For example:
Limio_Acme_Run_1.csv.
3. Uploading and Processing Files
Upload your file to the appropriate CSV bucket (e.g.,
ACME.csv-ingestion.limio.com).Limio provides access to different environments and their corresponding buckets.
Files are processed in batches of 1000 records, with each batch taking up to 15 minutes. Files exceeding 1000 records will be split automatically (but must not exceed 5000 records per file).
Monitor the progress of your migration on the Subscriptions page in the Limio App. Subscriptions are loaded automatically once processing is complete.
Processed files are moved to the "processed" folder in the bucket.
4. Checking the Outcome
Upon completion, a Limio event called "migration.uploaded" will appear in the Events Section.
For any errors, look for "migration.record.error" in the same section to identify issues with specific subscriptions.
5. Additional Migration Processes
a. Offer Migration to a Subscription
This process associates a Limio offer with a specific subscription, ideal when catalog offers were not prepared for migrated subscriptions.
Use the prefix "Limio_offers_" for the file name, following the same preparation and upload guidelines.
b. Gift Code Migration
Use this process to upload gift codes into Limio, often required for specific commercial agreements.
Gift codes can either link to existing Limio customers (via a Zuora account ID) or generate dummy customers during processing.
Use the prefix "Limio_gift_code_" for the file name, adhering to the same guidelines.
If you encounter any issues during migration or need further clarification, contact your Limio project team for assistance.
Import File
CSV Subscription File Definition:
string
Email related to the subscription (If not included, we set it to [email protected]) for the Limio Customer
string
Phone number related for the Limio Customer
string
yes
Zuora account number. Required to create the relevant Limio Identity on the Limio Customer and map Zuora Subscriptions to Limio Subscriptions. Example: A00104608
string
Salesforce account ID. Optional to create the relevant Limio Identity on the Limio Customer and map Salesforce Accounts to Limio Customers. Example: 0013w00002h2eviAAA
string
Salesforce contact ID. Optional to create the relevant Limio Identity on the Limio Customer and map Salesforce Contact to Limio Customers. Example: 0033w00002h2eviAAA
string
yes
The User id or sub from your Identity Provider. Required to create the relevant Limio Identity on the Limio Customer and allow the User to access authenticated Pages. Example: 1234567890
string
yes
The Subscription unique identifier, usually the Zuora Subscription Number from Zuora. It will also be used as Order Number to prevent duplicates if importing again the same record. Example: A00104608
string (isodate)
yes
The term start date of the subscription, format: YYYYMMDD
string (isodate)
yes
The term end date of the subscription, format: YYYYMMDD
string
A customer friendly reference to the subscription offer, eg. “Digital 1-year subscription”
string
yes
Defines the path of the Limio offer to be mapped into the subscription. Example: “/offers/digital/annual”
string
yes
The 3 character currency code. ie GBP, EUR, USD…
string (money)
yes
The price of the current subscription, ie: 295.00
string (money)
The price of the subscription next term. If empty uses current
string
[“Year”, “Week”, “Month”] - From Zuora InitialTermPeriodType field. If omitted will default to Month
string (int)
The quantity of units composing the period ie 1, 2, 3 (Years, Months, Weeks) - From Zuora InitialTerm field. If omitted will default to 1
string
Type of Rate Plan - From Zuora ratePlans.ratePlanCharges.type field
string
‘active’ (Expecting only active subscriptions)
string
First name for billing. Just to display to the customer if creates MMA account
string
Last name for billing. Just to display to the customer if creates MMA account
string
First line of address. To display to the customer if creates MMA account
string
Second line of address. To display to the customer if creates MMA account
string
To display to the customer if creates MMA account
string
To display to the customer if creates MMA account
string
To display to the customer if creates MMA account
string
sometimes
iso2 code. - Only required if payment method is detected
string
eg ***********4242 (if not known can be ***************)
string
["zuora_dd", "zuora_paypal", "zuora_card", "other"]
string
["Visa", "MasterCard", "Discover", "AmericanExpress", "Other"]
string (int)
Credit Card Expiration Month
string (int)
Credit Card Expiration Year
string
sometimes
Zuora Payment Method Id - Only required if payment method is migrated
string
It’s the Zuora payment type, we currently support: CreditCard (which is the default if not provided) and BankTransfer
string
Complete with BankTransferAccountName from Zuora Payment Method
string
Complete with BankTransferAccountNumberMask from Zuora Payment Method
string
Complete with BankCode from Zuora Payment Method
Last updated
Was this helpful?