[Staging] Migrating Your Data

Data migration is the process of transferring your data from your old system to Pelcro. Challenges arise when the data format does not match between the two systems.
This requires the data to be normalized and transformed to fit the Pelcro structure. Our team has put together all of the necessary tools to help you migrate your data successfully into Pelcro.
Process
The migration team has a deep understanding of relational databases that they have used to successfully migrate 100 000+ subscriptions across several businesses.
We have migrated businesses from several other systems including but not limited to: CDS, Piano, PayPal, Braintree, TownNews, Pigeon, Pico, and ClickShare.
It typically takes two weeks to analyze the data and prepare for its migration, assuming that all data provided adheres to the Pelcro templates.
Any technical team would be able to successfully migrate data into Pelcro using the core APIs. You can learn more about the Pelcro core API here.
In this section, we outline all the important steps necessary to guarantee a successful migration.
- Understand the scope of work and the data to be migrated.
- Request a data export from your current provider using Pelcro migrations templates to analyze the data.
- Data conversion.
a. Customer conversion.
b. Product conversion.
c. Plan conversion. - Analyze the provided data, generate the data analysis report and share the list of questions to be clarified.
- Perform a data migration into the designated Pelcro staging environment.
- Generate a migration statistics report and share the migration analysis report for review.
- Review and analyze the data migration.
- Plan the production migration.
a. Initiate credit card migration process.
b. Request and prepare the production data files.
c. Initiate production data migration.
d. Validate production data.
Limitations
There are some important limitations to be aware of when migrating your data in Pelcro’s system. You cannot migrate the following data:
- Expired subscriptions.
- Canceled subscriptions.
- Historical billing information.
There are also limitations with migrating unpaid active subscriptions.
If you want Pelcro to charge existing users for the active unpaid subscriptions, you need to set the subscription.common_metadata.service_status attribute to 'unpaid'.
On the day of migration, a charge equal to the plan price associated with the subscription will be attempted on the user account during the migration process. The following cases will define the behaviour considering the different possible scenarios:
-
Auto-renew unpaid subscriptions:
a. Invoice generated with amount_due matching amount fetched from the plan.
b. If collection_method is set to send_invoice, the due date is set to 1 day.
c. If collection_method is set to charge_automatically and a valid source exists, the charge will be attempted.
d. Otherwise, collection_method will be changed to send_invoice and the due date will be set to 1 day. -
For non-auto-renew unpaid subscriptions:
a. Due_date is set to 1 day.
b. Collection_method is forced to send_invoice.
c. An invoice is generated with the amount_due matching the amount fetched from the plan. -
For expired auto-renew unpaid subscriptions:
a. These are always created as a scheduled subscription with one phase.
b. Contains as many iterations as required to make current_period_end within current billing cycle bounds.
c. An invoice is generated with the amount_due matching the amount fetched from the plan.
d. If the collection method is set to send_invoice.due, the date will be set to 1 day.
e. If the set method is set to charge_automatically and a valid source exists, the charge will be attempted.
f. Otherwise, collection_method will be changed to send_invoice, and the due date will be set to 1 day. -
For expired non-auto-renew unpaid subscriptions:
a. The due_date would be set to 1 day and the collection_method forced to send_invoice.
b. The subscription is cancelled immediately after creation and the invoice generated with amount_due matching the amount fetched from the plan.
Our support team is right there for you!
Contact us at [email protected] and we're happy to assist with any questions or concerns.
Understanding Your Data Scope
Before performing any migration, it is necessary to understand and clean your data. During the migration kickoff meeting, your Account Manager will be asking you a set of questions that will be critical to understanding the data structure:
- Number of authenticated users to be migrated.
- Number of active subscriptions to be migrated.
- How are the active subscriptions broken down?
- How many of the active subscriptions are on auto-renew?
- How many of the active subscriptions are set to be cancelled at period end?
- How many of these subscriptions are gift subscriptions?
- How many of these subscriptions are membership subscriptions?
- Does your business collect taxes?
- Are there any unpaid subscriptions that requires charging the user during the migration process?
Requesting a Data Export From Your Current Provider
When requesting a data export from your current provider, the format likely will not match the data structure required by Pelcro.
By providing the data in our predefined CSV files, our team will be able to process the migration much faster than if you provide us a data dump as-is from the current provider.
Pelcro offers two different templates of CSV files. This gives you more flexibility with how you choose to export your data points. The options are outlined below:
- 3 predefined CSV files.
a. File 1: Merge customers, subscriptions and addresses into 1 file.
b. File 2: Products.
c. File 3: Plans. - 5 predefined CSV files.
a. File 1: Customers.
b. File 2: Subscriptions.
c. File 3: Addresses.
d. File 4: Products.
e. File 5: Plans.
Links to the templates:
- Pelcro migration template for customer data
- Pelcro migration template for plans
- Pelcro migration template for products
Data Conversion
During the data conversion process, you will need to populate the Pelcro Provided templates with your current data set.
Customers
Customers are the underlying object to which we associate subscriptions, payments, invoices, etc.
When migrating customers, we migrate authenticated users. These would include:
- 'Active Authenticated Users', also referred to as 'Active Registered Users'.
- 'Inactive Authenticated Users', also referred to as 'Inactive Registered Users'. These would be the users that haven't logged in within the last 3, 6, 9, 12 or more, months ago.
- 'Active Subscribers' are a subcategory of the 'Active Authenticated Users' that have one or more active subscription
All the following attributes related to each customer with unique old_provider_id must be unique. Normally these attributes are represented on one line item. If the same user has multiple subscriptions, all the repeated rows must have exactly the same values for the following customer related attributes with the same old_provider_id.
You can learn more about the customer resource and its associated properties here.
Attribute | Description | Required/Optional |
---|---|---|
customer.old_provider_id | The old provider id corresponds to the unique identifier currently used on the old data provider. This value must be a unique id tied to the customer record. This value could be any of the following: 1. Numeric value. 2. Alphabetic value. 3. Alphanumeric value. Note: If an old provider id is not available, you must assign a randomly generated unique id for each individual customer record. Note: If there's a credit card migration involved, the "customer.old_provider_id" must be included in the dump sent to Stripe or other payment processors. | Required. |
customer.email | If the email is provided, it must be a unique email tied to each old provider id. Two separate old provider IDs cannot share the same email address. Note: If an email address is not available, the user will not be able to login to online services. | Optional (strongly recommended to be included). |
customer.first_name | The first name of the subscriber. Note: If you do not have the customer's first name, you can always keep the value empty. | Optional (recommended to be included). |
customer.last_name | The last name of the subscriber. Note: If you do not have the customer's last name, you can always keep the value empty. | Optional (recommended to be included). |
customer.phone | The default customer phone number. No letters are allowed. Maximum 20 digits. Here are some example of accepted values: 1. 0015141234567 2. +15141234567 3. +1.514.123.4567 4. +1-514-123-4567 5. (514)1234567 6. 'empty' | Optional. |
customer.title | The title value on the customer record allows you to track the customer's job title. Here are some example of accepted values: 1. CEO. 2. Manager. 3. Doctor. 4. Publisher. 5. 'empty'. | Optional. |
customer.salutation | The salutation value on the customer record allows you to how to address your customer. Here are some example of accepted values: 1. Mr. 2. Mrs. 3. Miss. 4. Ms. 5. Dr. 6. Me. 7. 'empty'. | Optional. |
customer.display_name | The display name that can be used by the customer and must be unique in the database. Note: Two customers cannot share the same username. | Optional. |
customer.password | In the case of password migrations, encrypted passwords should be provided for all customers. Note: For completing password migrations, a subset/sample of encrypted passwords should be provided with their corresponding plain text passwords. | Dependent (in case of passwords migrations it is required, otherwise it is optional). |
customer.common_metadata.import_only_the_customer | This is a binary value that determines if this migration will only import customer data and metadata. 0: Import all data. 1: Import customer data only. | Required. |
customer.common_metadata.password_encryption | The type of encryption used to encrypt the provided passwords. Here are some examples: 1. MD5. 2. Plain text. 3. Drupal. 4. Bcrypt. | Required for password migration. |
customer.common_metadata.original_old_provider_id | Information corresponds to the old provider customer ID that is used during the migration process. | Required. |
Here are some examples of customer records populated in our migration template:
- Customers having all the necessary information.
customer.old_provider_id* | customer.email* | customer.first_name | customer.last_name | customer.phone | customer.title | customer.salutation | customer.display_name | customer.password | customer.common_metadata.import_only_the_customer | ||
---|---|---|---|---|---|---|---|---|---|---|---|
143278 | [email protected] | Gerard | Cassano | 0015141234567 | CEO | Mr. | Gcassano1 | $S$E787NL98gqdILAPnprFDzXuXzJjSMttvx8l.YNcEqtM7rvMJZpsJ | 1 | ||
abc1234 | [email protected] | Jane | Doe | Manager | Miss | $#$%sfsfhsjkbvsjkdhf234235235fsdgs | 1 | ||||
1234abc | [email protected] | J | Williams | *+1-514-123-4567 | Doctor | Dr. | Jwilliams1 | 0 | |||
abcdef | [email protected] | Sabrina | +15141234567 | sabrina1989 | 1 |
Addresses
Addresses will provide all the required contact information related to customers and their subscriptions. That includes both billing and shipping addresses.
- Each customer being imported without a subscription, can be imported with or without an address.
- Each customer being imported with a subscription can ideally have a billing address.
- Each customer being imported with a subscription can have a shipping address.
- If the subscription is tied to a physical product that needs to be shipped, the shipping address will be required.
Billing Address
Attribute | Description | Required/Optional |
---|---|---|
address.billing_first_name | The first name on the billing address corresponds to the first name of the person being billed when an invoice is generated. | Required. |
address.billing_last_name | The last name on the billing address corresponds to the last name of the person being billed when an invoice is generated. | Required. |
address.billing_salutation | The salutation value on the billing address record allows you to how to address your customer. Here are some example of accepted values: 1. Mr. 2. Mrs. 3. Miss. 4. Ms. 5. Dr. 6. Me. 7. 'empty'. | Optional. |
address.billing_title | The title value on the billing address record allows you to track the customer's job title. Here are some example of accepted values: 1. CEO. 2. Manager. 3. Doctor. 4. Publisher. 5. 'empty'. | Optional. |
address.billing_company | The company value on the billing address record allows you to track the company tied to the billing address. | Optional. |
address.billing_department | The department value on the billing address record allows you to track the department tied to the billing address. | Optional. |
address.billing_line1 | This value provides the first billing address line of the customer's billing address. | Required. |
address.billing_line2 | This value provides the second billing address line of the customer's billing address. This value can contain the suite or apartment number. It can also be left empty. | Optional. |
address.billing_city | This value provides the city of the customer's billing address. | Required. |
address.billing_state | This value provides the state of the customer's billing address. Note: For all US and Canadian addresses, the state value must be populated in the 2-letter ISO standard format found here. | Required. |
address.billing_country | This value provides the country of the customer's billing address. Note: Countries should be in the 2-letter ISO standard format found here. | Required. |
address.billing_zip | This value provides the zip/postal code of the customer's billing address. | Required. |
address.billing_phone | This value provides the phone number of the customer's billing address. It cannot contain any non-numeric characters (eg +,x). Number length should not exceed 20 digits. | Optional. |
Here are some examples of the customer billing address records populated in our migration template:
address.billing_first_name | address.billing_last_name | address.billing_line1 | address.billing_line2 | address.billing_city | address.billing_state | address.billing_country | address.billing_salutation | address.billing_title | address.billing_zip | address.billing_phone | address.billing_company | address.billing_department |
---|---|---|---|---|---|---|---|---|---|---|---|---|
Genaro | Cassano | 1010 Sainte Catherine ouest | #02-111 | Montreal | QC | CA | Mr. | H3H1H1 | 514112-2233 | ABC Inc. | Accounting | |
Jennifer | White | 469 Homewood Ave. Levittown | New York | NY | US | 11756 | 5051122233 | EFG inc. | HR |
Shipping Address
Attribute | Description | Required/Optional |
---|---|---|
address.shipping_first_name | The first name on the shipping address corresponds to the first name of the person to whom the physical shipment will be sent to. | Required. |
address.shipping_last_name | The last name on the shipping address corresponds to the last name of the person to whom the physical shipment will be sent to. | Required. |
address.shipping_salutation | The salutation value on the shipping address record allows you to how to address your customer. Here are some example of accepted values: 1. Mr. 2. Mrs. 3. Miss. 4. Ms. 5. Dr. 6. Me. 7. 'empty'. | Required. |
address.shipping_title | The title value on the shipping address record allows you to track the customer's job title. Here are some example of accepted values: 1. CEO. 2. Manager. 3. Doctor. 4. Publisher. 5. 'empty'. | Required. |
address.shipping_company | The company value on the shipping address record allows you to track the company tied to the shipping address. | Optional. |
address.shipping_department | The department value on the shipping address record allows you to track the department tied to the shipping address. | Optional. |
address.shipping_line1 | This value provides the first shipping address line of the customer's shipping address. | Required. |
address.shipping_line2 | This value provides the second shipping address line of the customer's shipping address. This value can contain the suite or apartment number. It can also be left empty. | Optional. |
address.shipping_city | This value provides the city of the customer's shipping address. | Required. |
address.shipping_state | This value provides the state of the customer's shipping address. Note: For all US and Canadian addresses, the state value must be populated in the 2-letter ISO found here. | Required. |
address.shipping_country | This value provides the country of the customer's shipping address. Note: Countries should be in the 2-letter ISO standard format, found here. | Required. |
address.shipping_zip | This value provides the zip/postal code of the customer's shipping address. | Required. |
address.shipping_phone | This value provides the phone number of the customer's shipping address. It cannot contain any non-numeric characters (eg +,x). Number length should not exceed 20 digits. | Optional. |
Here are some examples of the customer shipping address records populated in our migration template:
address.shipping_first_name | address.shipping_last_name | address.shipping_salutation | address.shipping_title | address.shipping_company | address.shipping_department | address.shipping_line1 | address.shipping_line2 | address.shipping_city | address.shipping_state | address.shipping_country | address.shipping_zip | address.shipping_phone |
---|---|---|---|---|---|---|---|---|---|---|---|---|
Genaro | Cassano | 1010 Sainte Catherine ouest | #02-111 | Montreal | QC | CA | H3H1H1 | (514)-112-2233 | ||||
Jennifer | White | 469 Homewood Ave. Levittown | New York | NY | US | 11756 | (613)1233322 |
You can learn more about the addresses resource and its associated properties.
Note: How do you handle a customer that has multiple shipping and/or billing addresses?
It is not expected that the same customer could have multiple addresses. However, if the customer has more than one address, you need to add two additional columns (shipping_address_id,billing_address_id) and ensure a unique ID for each unique address. Keep in mind that this would be adding an additional layer of complexity. Avoiding that is strongly recommended.
Products
Product objects describe items that your customers can subscribe to via a subscription.
Each product can contain one or multiple pricing plans. For example, a newspaper offers two products:
- Digital Product [PRODUCT1]
a. Weekly Subscription [PLAN1]
b. Monthly subscription [PLAN2]
c. Yearly Subscription [PLAN3] - Print Product [PRODUCT2]
a. Monthly Subscription [PLAN1]
b. Yearly subscription [PLAN2]
You can learn more about the product resource and its associated properties.
Here's a list of the required information for all product migrations:
Attribute | Description | Required/Optional |
---|---|---|
product.id | This value is a unique identifier tied to every product and which is used to relate each plans to its corresponding product. | Required. |
product.address_required | This value is a boolean value that indicates if the customer address is required for this product or not. The boolean values are as follows: 1: Address required. 0: Address is not required. In case of taxes inclusion in payments, addresses are required for all eligible customers regardless of product nature. | Required. |
product.name | The product name for this product.id which will be used on the Pelcro platform to represent the product. | Required. |
product.description | This value provides a product description that can be used on the platform. | Optional. |
Product.statement_descriptor | Name that will appear on your customer's bank statement. | Optional. |
Here are some examples of product records populated in our migration template:
product.id | product.address_required | product.active | product.name | product.description | product.image |
---|---|---|---|---|---|
PR1234 | 0 | 1 | Digital membership | Digital membership | https://abcd.com/images/1.jpg |
PR1235 | 1 | 1 | Print Membership | Print Membership offering 12 print magazines a year. 1 per month | |
PR1236 | 1 | 1 | Combo Membership (Print + Digital) | Print and Digital Membership | |
PR1230 | 1 | 0 | OLD Print Product | Archived plan - Old print product |
Plans
A product object describes items that your customers can subscribe to via a subscription.
Each product can contain one or multiple pricing plans, where a plan can be a variation of the product offered. Let's take the example: a newspaper offers two products:
- Digital Product [PRODUCT1]
a. Weekly Subscription [PLAN1]
b. Monthly subscription [PLAN2]
c. Yearly Subscription [PLAN3] - Print Product [PRODUCT2]
a. Monthly Subscription [PLAN1]
b. Yearly subscription [PLAN2]
You can learn more about the plan resource and its associated properties.
Here's a list of the required information for all plan migrations:
Attribute | Description | Required/Optional |
---|---|---|
plan.amount | This value represents the unit amount in cents to be assigned as the plan price. Note: amounts should be represented as a whole integer if possible. | Required. |
plan.auto_renew | This boolean value determines whether the plan is on an auto-renewal cycle or not. The boolean is defined as follows: 1: The plan is auto-renew. 0: The plan is not auto-renew. It is a one time plan. | Required. |
plan.currency | This value determines the plan currency that will be used to charge the client. | Required. |
plan.available_online | Boolean value to specify whether the plan is available on your site. The boolean is defined as follows: 1: Yes. 0: No. | Required. |
plan.interval | This value determines the interval value of the plan, which is tied to the billing cycle. The input is an integer which depends on the cycle: Day: 1 Week: 2 Month: 3 Year: 4 | Required. |
plan.interval_count | This value is tied to the 'plan.interval' value and determines the billing cycle. Example 1: If a plan has the following parameters: 1. plan.interval = 4. 2. plan.interval_count = 1. This means that the billing cycle is once every 1 year. Example 2: If a plan has the following parameters: 1. plan.interval = 3. 2. plan.interval_count = 2. This means that the billing cycle is once every 2 months. | Required. |
plan.nickname | The respective plan name. | Required. |
plan.shipments_per_interval | This value represents the number of shipments associated with this plan. A digital plan that does not have any shipments associated with it, will typically be 0, whereas a print product, that has shipments associated with it, will have a value greater than 0. Example 1: If a plan is a yearly print subscription with 12 shipments per year: plan.shipments_per_interval = 12 Example 2: If a plan is a monthly print subscription with 1 shipment per month: plan.shipments_per_interval = 1 | Required. |
plan.description | A brief description providing more details about the plan(This also will appear on Pelcro platform along side the nickname). | Optional |
plan.temporary_product_id | The associated product id with this plan. This value will be used to link the Plans file with the Products file, and to specifically reference the Product under which the Plan will be created. | Required. |
plan.old_id | The unique identifier previously used to refer to the plan (also known as rate code, promo code). | Required. |
plan.type | This value will indicate the plan type, whether it is a membership plan, a standard (individual) subscription plan or a donation plan. Standard subscription plans must take the value regular. Membership/group plan must take the value membership. For more information on membership plans, kindly refer to our documentation found here: https://docs.pelcro.com/docs/memberships Donation plans must take the value donation. For more information can be found here: https://docs.pelcro.com/changelog/whats-new-in-version-145-derrida | Required. |
plan.revenue_recognition_type | The revenue recognition field will be used to specify whether the subscription-related revenue is being recognized on a time basis (seconds elapsed since subscription start) or a shipment basis (shipments delivered from subscription start). More information can be found here. | Required. |
plan.entitlements | The entitlements that are available to the user upon subscribing to this plan. The entitlements will enable you to control the features that a user has access to. In the case of a single plan having multiple entitlements, this field should be added and filled with the multiple entitlements separated by a comma (e.g. ent_a,ent_b,ent_c). | Optional. |
plan.amount | plan.currency | plan.autorenew | plan.interval | plan.interval_count | plan.nickname | plan.shipments_per_interval | plan.description | plan.common_metadata.account_name | plan.product_id | plan.old_id | plan.is_donated | plan.type | plan.revenue_recognition_type |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
19900 | eur | 1 | 4 | 1 | Europe Yearly Membership - Gold | 12 | Print+Digital | abcd | 14371 | 1234 | 1 | donation | shipment_based |
1900 | cad | 0 | 3 | 1 | Canada Monthly Membership - Silver | 1 | abdc | 15634 | 5789 | 0 | regular | shipment_based |
Subscriptions
During the customer conversion process you might encounter the following scenarios:
- One customer, referred to as a registered user, without any subscription.
- One customer, referred to as a subscribed user, with one active subscription.
- One customer, referred to as a subscribed user, with two or more active subscriptions.
You can learn more about the subscription resource and its associated properties.
Here's a list of the typical information which is vitally needed for a given subscriptions migration, as well as an example of a sample dataset.
Attribute | Description | Required/Optional |
---|---|---|
subscription.current_period_end | End date of the current period that the subscription has been invoiced for. At the end of this period, a new invoice will be created. | Required. |
subscription.cancel_at_period_end | This boolean value determines whether an active subscription will be cancelled at the end of the current period. The boolean value is defined as follows: 1: Plan will terminate at the end of the current period. 0: Plan will not be cancelled at the end of the current period. The plan will auto-renew. | Required. |
subscription.shipments_undeliverable | Boolean value that determines whether a shipment is deliverable. This is helpful if this customer is not receiving the shipment for any reason, and you want to make sure future shipments are not lost. | Optional. |
subscription.shipments_suspended_until | Date which sets the subscription on a suspension mode. This can then be filtered out when creating a list. This is helpful if customers are travelling and request a suspension till they are back for example. | Optional. |
subscription.n.common_metadata.is_expired | Boolean value which determines if a subscription status will automatically be set to expired once the data migration is complete. 1: The subscription will be set to expired once it has been migrated, regardless of provided current_period_end and cancel_at_period_end values. 2. Subscription will not be set to expired. | Optional. |
subscription.n.common_metadata.start_now | Boolean value which determines when a migrated subscription starts: 1: The subscription will start immediately after the migration and will fetch its period_end from the related plan interval. 0: The subscription will not start immediately after migration. | Optional. |
subscription.shipments_remaining | The number of shipments remaining on a given subscription as of the migration date. Normally when creating the new interval invoice shipments_per_interval from the plan is added to the shipments_remaining amount, this occurs on the first invoice of the plan but also on all subsequent invoices that are created automatically by the subscription. Must be an integer. | Required (could be skipped in case of digital products subscriptions). |
subscription.quantity | Depending on the associated product/plan, some subscriptions may require a quantity for the product/service provided (e.g. in the case of print subscriptions where the subscriber has required to include a specific number of copies per shipment). In most cases, this value should be set to 1. Must be an integer. | Required. |
subscription.collection_method | This attribute only takes 2 possible values: 1. "charge_automatically". 2. "send_invoice". This is referring to the subscription payment method. It is either charged automatically by credit card or by sending the invoice (e.g. via cheque, cash or wire payments). | Required. |
subscription.common_metadata.temporary_plan_id | The associated plan id with this subscription. This value will be used to link the customers file with the plans file. It also is used to reference the Plan under which this subscription record will be created. | Required. |
subscription.common_metadata.old_id | Unique subscription identifier. | This field is optional but in case of having gift subscriptions, it must be filled. |
subscription.common_metadata.service_status | Status of a given subscription. This field only takes the following values: 1. Active. 2. Unpaid. Active is for an actively running subscription that has been paid. Unpaid is for a subscription with an open invoice that must be imported into Pelcro. For records where the latter value has been marked, an open invoice will be generated upon import and tied to the subscription record. | Required. |
subscription.common_metadata.order_number | The number of this subscription order (one of the order metadata). | Optional. |
subscription.common_metadata.order_price | The price of this subscription order (one of the order metadata). | Optional. |
subscription.common_metadata.order_term | The term (length) of this subscription order. | Optional. |
subscription.type | This field indicates the subscription type: 1. A standard subscription plan, if so indicate regular. 2. A membership group admin, if so indicate admin. 3. A membership group member, if so indicate member. | Required. |
subscription.common_metadata.membership | The unique membership identifier, as Pelcro would define each membership via this field. Note: Every unique membership group must have a single admin user. | Required when importing membership subscriptions. |
subscription.common_metadata.is_gift_donor | This boolean attribute indicates whether the gift subscription record is gift donor record: 1. Yes. 2. No. | Required only when importing gift subscription records. |
subscription.common_metadata.is_gift_recipient | This boolean attribute indicates whether this subscription is related to a gift recipient: 1: Yes. 2: No. | Required only when importing gift subscription records. |
subscription.common_metadata.gift_donor_subscription_id | The donor subscription ID that will be used to tie a gift recipient subscription to a gift donor subscription. This value is only expected to be filled for gift recipient subscription records. | Required only when importing gift subscription records. |
subscription.current_period_end | subscription.cancel_at_period_end | subscription.start_date | subscription.shipments_undeliverable | subscription.shipments_suspended_until | subscription.quantity | subscription.shipments_remaining | subscription.quantity | subscription.collection_method | subscription.common_metadata.temporary_plan_id | subscription.common_metadata.old_id | subscription.common_metadata.is_expired | subscription.common_metadata.service_status | subscription.common_metadata.order_number | subscription.common_metadata.order_price |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
31/01/2021 | 0 | 31/01/2020 | 1 | 1 | 1 | charge_automatically | 1234 | 1012131 | 0 | active | 12233 | 4500 | ||
16/02/2022 | 1 | 16/01/2022 | 1 | 1 | send_invoice | 56 | 1734 | 0 | unpaid | 4572 | 6000 | |||
07/08/2022 | 1 | 07/04/2022 | 1 | 2 | send_invoice | 133 | 12345 | 0 | active | 12 | 2350 |
Limitations
There are some important limitations to be aware of when migrating your data in Pelcro’s system. You cannot migrate the following data:
- Expired subscriptions.
- Canceled subscriptions.
- Historical billing information.
There are also limitations with migrating unpaid active subscriptions.
If you want Pelcro to charge existing users for the active unpaid subscriptions, you need to set the subscription.common_metadata.service_status attribute to 'unpaid'.
On the day of migration, a charge equal to the plan price associated with the subscription will be attempted on the user account during the migration process. The following cases will define the behaviour considering the different possible scenarios:
-
Auto-renewing unpaid subscriptions:
a. An open invoice is generated, with the amount fetched from the plan.amount field value.
b. If the collection_method is set to send_invoice, the invoice will remain open until the automatic uncollectible (or write-off) period is reached.
c. If the collection_method is set to charge_automatically and a valid payment method exists, a charge will be attempted on the invoice.
d. If the collection_method is set to charge_automatically but there is no valid payment method on file, the collection_method will be changed to send_invoice (see point b.) -
For non-auto-renewing, unpaid subscriptions:
a. The collection_method will be forced to send_invoice.
b. An open invoice is generated, with the amount fetched from the plan.amount field value.
c. The invoice will remain open until the automatic uncollectible (or write-off) period is reached. -
For expired, auto-renewing unpaid subscriptions:
a. These subscriptions are always created as a scheduled subscription with one phase.
b. Contains as many phases as required to make current_period_end within current billing cycle bounds.
c. An open invoice is generated, with the amount fetched from the plan.amount field value.
d. If the collection_method is set to send_invoice, the invoice will remain open until the automatic uncollectible (or write-off) period is reached.
e. If the collection_method is set to charge_automatically and a valid payment method exists, a charge will be attempted.
f. If the collection_method is set to charge_automatically but there is no valid payment method on file, the collection_method will be changed to send_invoice (see point d.) -
For expired non-auto-renew unpaid subscriptions:
a. The collection_method will be forced to send_invoice.
b. The subscription is cancelled immediately upon import, along with the invoice generated.
In the case where multiple rows per customer exist (e.g. same customer having multiple subscriptions to different plans/rates), all the customer-related fields (even if they are optional) must be unique per customer. For these cases, only one row would be used to migrate customer related attributes and others would be discarded. All subscription related attributes will be honoured and migrated as such.
Canceled/Expired Subscriptions
It is not possible to migrate any canceled or expired subscriptions. It is also not possible to migrate any historical billing information. All this data can be sent to us for storage in our backups that can be queried in the future upon request.
Migrating gift subscriptions
Pelcro can migrate gift subscriptions; there is, however, an additional cost incurred to migrate the relationship between donors and recipients. This relationship is handled using the following attributes:
- subscription.common_metadata.is_gift_donor
- subscription.common_metadata.is_gift_recipient
- subscription.common_metadata.gift_donor_subscription_id
Notes: Donor and recipient subscriptions should share the same plan. This is a one-to-one relation which means that every gift donor subscription should be related to one (and only one) gift recipient subscription using the gift_donor_subscription_id value.
Migrating passwords
The password migration component deals specifically with transferring the end-user passwords. The main consideration here is the customer’s previous encryption mechanism. Pelcro only supports the following:
- Drupal_v8.2.x
- Bcrypt (WordPress)
- Bcrypt
- MD5
- Plain text
Note: Pelcro uses Bcrypt and its implementation on PHP.
Once you've reviewed the prerequisites, the next step is to provide Pelcro with a small sample of hashes with their respective passwords in plain text, against the hashing algorithm. This will allow Pelcro's migration engineers to analyze the sample and evaluate the feasibility of migrating user passwords into the database.
Items the customer must provide to migrate passwords into Pelcro:
- A minimum of 5 password examples (hashes and their equivalent plain text).
- Hash types:
a. Built-in: provide the name of the hashing mechanism (e.g. sha1, MD5, bcrypt).
b. Custom implementation: provide the code used to generate and validate passwords. - If the hashing requires a salt/pepper, that must be provided as well.
If Pelcro's migration engineers successfully reproduce the hashing output that matches the customers’, we deem that we are capable of moving forward with the password migration.
The final step is to provide the password hash in the customers file template, as part of the data dump; this must be provided under the customer.password field. Pelcro will then undertake the work to import the user passwords upon GoLive.
Performing a data migration into a Staging environment
Once all the statistics have been reviewed and validated by the client, the migration team will begin the migration dry-run process:
- The migration team will prepare the data files to perform the migration to staging.
- The migration team will run the script to migrate the data into the staging environment.
- The migration team will validate that all the data provided in the dry-run data dump has been successfully imported.
Generating a migration statistics report
Once the dry-run process has been completed, it will be critical for the migration team to review the data and generate a migration report which will illustrate the migration success rate of each Pelcro record object.
The sample statistics report below reflects the percentage of records with valid data that Pelcro was able to migrate from the legacy system into the Pelcro system.
Field definitions:
- Attribute: Property of a given object type.
- Pelcro Pre-Processed: number of records fed into Pelcro’s migration script.
- Excel dump: number of records included in the customer data dump.
- Accuracy: Measure of how many records were kept between the excel dump and Pelcro's migration script.
- Inaccuracy: Compliment of accuracy.
- Dry-run (staging): number of valid records migrated into the staging server.
- Production: number of valid records migrated into the production server.

Sample statistics report.
Sample statistics reports will vary in size depending on the data points included. It is important to sanity check the numbers in this report against the data in your system. For example, verify that you have 1848 customers subscribed to the 'Print & Digital 1-Year USA' plan.
Reviewing and analyzing the data migration
The report generated in the previous section will be critical to getting the client's approval to move forward with the production migration.
As part of this process the client will be required to:
- Review the report generated by the Pelcro migration team
- Validate the numbers
- Validate sample data in the Pelcro Dry-run environment.
- Sign off on the report and Data validation
In order to assist you in validating the imported data, you can review Pelcro's best practices below:
- Once logged into the Pelcro platform, use the Products tab in the left sidebar to validate the product and plan relations and plan amounts.
a. Tip: Looking at shipments_per_interval and plan_intervals is a great way to begin your validations. - Navigate to Billing > Subscriptions and perform a data export to validate the subscription-related objects, such as:
a. Auto_renew status
b. Subscription expiry dates
c. Shipments_remaining
d. Validate the customer-subscription relations using the same CSV data export.
Going the extra mile: Navigate to Customers > Customers and perform a customer_object data export, where you can validate:
- Billing and Shipping Addresses
- Customer metadata.
Migrating Credit Cards to Production
Migrating credit card information is important to ensure your end users do not have to re-enter their payment details when you switch from your legacy payment processor to your new payment processor.
The key difference between migrating credit cards and your other data, is the intervention of a third-party vendor. This may impact the timeframe of the data migration.
The steps required to migrate your end users' credit card information into the new payment processor are outlined below:
- Get familiar with the requirements for credit card migration.
- You need an ID for each customer in the old payment processor files, which will be mapped to new customer IDs.
- Coordinate between your new payment processor and the previous one to request the data migration.
a. Your new payment processor will provide you with a file template for dumping the credit card information. Work with your old payment processor to prepare the data dump file. - The transitionary period: online payment freeze period, where the customer will be requested to freeze any online payment.
a. Redirecting all new subscriptions to the customer service operators, that will manually process the subscription and issue a bill-to invoice.
b. For smaller customers without customer service operators, they can even freeze all new subscriptions during this transitionary period. - The new payment processor will confirm the import by providing a mapping file (JSON) which contains their generated IDs (customers, payment methods, etc) along with the old payment processor IDs.
- Use the mapping file to overwrite Pelcro data (customer record info, subscriptions, ..).
- Once the mapping is complete, you must validate the data across both providers and provide a stamp of approval.
Migrating the rest of your data to production
- Prepare the production data files.
- Initiate production data migration.
- Validate production data.
IMPORTANT: It is critical to provide a customer, address, and subscription data in one flat file while providing another flat file for the products and plans.
subscription.common_metadata.order_price
Check out these helpful articles for more information on our blog
Updated about 1 year ago