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:

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	Print	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.quantity	subscription.shipments_remaining	subscription.quantity	subscription.collection_method	subscription.common_metadata.temporary_plan_id	subscription.common_metadata.old_id	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	active	12233	4500
16/02/2022	1	16/01/2022		1	1		send_invoice	56	1734	unpaid	4572	6000
07/08/2022	1	07/04/2022	1	2			send_invoice	133	12345	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'.

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 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

The Pelcro Blog

How to Migrate from Piano Go

Switching From Legacy Systems to a Modern Subscription Platform