ChangelogGuidesRecipesAPI ReferenceBlogYoutube
Guides
START FREE TRIALSCHEDULE A DEMO

[Staging] Migrating Your Data

Suggest Edits
2952

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.

  1. Understand the scope of work and the data to be migrated.
  2. Request a data export from your current provider using Pelcro migrations templates to analyze the data.
  3. Data conversion.
    a. Customer conversion.
    b. Product conversion.
    c. Plan conversion.
  4. Analyze the provided data, generate the data analysis report and share the list of questions to be clarified.
  5. Perform a data migration into the designated Pelcro staging environment.
  6. Generate a migration statistics report and share the migration analysis report for review.
  7. Review and analyze the data migration.
  8. 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:

  1. Expired subscriptions.
  2. Canceled subscriptions.
  3. 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:

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

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

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

  4. 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:

  1. Number of authenticated users to be migrated.
  2. Number of active subscriptions to be migrated.
  3. How are the active subscriptions broken down?
  4. How many of the active subscriptions are on auto-renew?
  5. How many of the active subscriptions are set to be cancelled at period end?
  6. How many of these subscriptions are gift subscriptions?
  7. How many of these subscriptions are membership subscriptions?
  8. Does your business collect taxes?
  9. 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:

  1. 3 predefined CSV files.
    a. File 1: Merge customers, subscriptions and addresses into 1 file.
    b. File 2: Products.
    c. File 3: Plans.
  2. 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:

  1. Pelcro migration template for customer data
  2. Pelcro migration template for plans
  3. 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:

  1. 'Active Authenticated Users', also referred to as 'Active Registered Users'.
  2. '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.
  3. '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.

AttributeDescriptionRequired/Optional
customer.old_provider_idThe 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.emailIf 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_nameThe 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_nameThe 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.phoneThe 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.titleThe 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.salutationThe 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_nameThe 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.passwordIn 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_customerThis 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_encryptionThe 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_idInformation 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:

  1. Customers having all the necessary information.
customer.old_provider_id*customer.email*customer.first_namecustomer.last_namecustomer.phonecustomer.titlecustomer.salutationcustomer.display_namecustomer.passwordcustomer.common_metadata.import_only_the_customer
143278[email protected]GerardCassano0015141234567CEOMr.Gcassano1$S$E787NL98gqdILAPnprFDzXuXzJjSMttvx8l.YNcEqtM7rvMJZpsJ1
abc1234[email protected]JaneDoeManagerMiss$#$%sfsfhsjkbvsjkdhf234235235fsdgs1
1234abc[email protected]JWilliams*+1-514-123-4567DoctorDr.Jwilliams10
abcdef[email protected]Sabrina+15141234567sabrina19891

Addresses

Addresses will provide all the required contact information related to customers and their subscriptions. That includes both billing and shipping addresses.

  1. Each customer being imported without a subscription, can be imported with or without an address.
  2. Each customer being imported with a subscription can ideally have a billing address.
  3. Each customer being imported with a subscription can have a shipping address.
  4. If the subscription is tied to a physical product that needs to be shipped, the shipping address will be required.

Billing Address

AttributeDescriptionRequired/Optional
address.billing_first_nameThe 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_nameThe last name on the billing address corresponds to the last name of the person being billed when an invoice is generated.Required.
address.billing_salutationThe 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_titleThe 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_companyThe company value on the billing address record allows you to track the company tied to the billing address.Optional.
address.billing_departmentThe department value on the billing address record allows you to track the department tied to the billing address.Optional.
address.billing_line1This value provides the first billing address line of the customer's billing address.Required.
address.billing_line2This 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_cityThis value provides the city of the customer's billing address.Required.
address.billing_stateThis 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_countryThis 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_zipThis value provides the zip/postal code of the customer's billing address.Required.
address.billing_phoneThis 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_nameaddress.billing_last_nameaddress.billing_line1address.billing_line2address.billing_cityaddress.billing_stateaddress.billing_countryaddress.billing_salutationaddress.billing_titleaddress.billing_zipaddress.billing_phoneaddress.billing_companyaddress.billing_department
GenaroCassano1010 Sainte Catherine ouest#02-111MontrealQCCAMr.H3H1H1514112-2233ABC Inc.Accounting
JenniferWhite469 Homewood Ave.
Levittown		New YorkNYUS117565051122233EFG inc.HR

Shipping Address

AttributeDescriptionRequired/Optional
address.shipping_first_nameThe 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_nameThe 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_salutationThe 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_titleThe 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_companyThe company value on the shipping address record allows you to track the company tied to the shipping address.Optional.
address.shipping_departmentThe department value on the shipping address record allows you to track the department tied to the shipping address.Optional.
address.shipping_line1This value provides the first shipping address line of the customer's shipping address.Required.
address.shipping_line2This 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_cityThis value provides the city of the customer's shipping address.Required.
address.shipping_stateThis 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_countryThis 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_zipThis value provides the zip/postal code of the customer's shipping address.Required.
address.shipping_phoneThis 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_nameaddress.shipping_last_nameaddress.shipping_salutationaddress.shipping_titleaddress.shipping_companyaddress.shipping_departmentaddress.shipping_line1address.shipping_line2address.shipping_cityaddress.shipping_stateaddress.shipping_countryaddress.shipping_zipaddress.shipping_phone
GenaroCassano1010 Sainte Catherine ouest#02-111MontrealQCCAH3H1H1(514)-112-2233
JenniferWhite469 Homewood Ave.
Levittown		New YorkNYUS11756(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:

  1. Digital Product [PRODUCT1]
    a. Weekly Subscription [PLAN1]
    b. Monthly subscription [PLAN2]
    c. Yearly Subscription [PLAN3]
  2. 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:

AttributeDescriptionRequired/Optional
product.idThis value is a unique identifier tied to every product and which is used to relate each plans to its corresponding product.Required.
product.address_requiredThis 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.nameThe product name for this product.id which will be used on the Pelcro platform to represent the product.Required.
product.descriptionThis value provides a product description that can be used on the platform.Optional.
Product.statement_descriptorName that will appear on your customer's bank statement.Optional.

Here are some examples of product records populated in our migration template:

product.idproduct.address_requiredproduct.activeproduct.nameproduct.descriptionproduct.image
PR123401Digital membershipDigital membershiphttps://abcd.com/images/1.jpg
PR123511Print MembershipPrint Membership offering 12 print magazines a year. 1 per month
PR123611Combo Membership (Print + Digital)Print and Digital Membership
PR123010OLD Print ProductArchived 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:

  1. Digital Product [PRODUCT1]
    a. Weekly Subscription [PLAN1]
    b. Monthly subscription [PLAN2]
    c. Yearly Subscription [PLAN3]
  2. 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:

AttributeDescriptionRequired/Optional
plan.amountThis 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_renewThis 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.currencyThis value determines the plan currency that will be used to charge the client.Required.
plan.available_onlineBoolean value to specify whether the plan is available on your site. The boolean is defined as follows:
1: Yes.
0: No.		Required.
plan.intervalThis 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_countThis 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.nicknameThe respective plan name.Required.
plan.shipments_per_intervalThis 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.descriptionA brief description providing more details about the plan(This also will appear on Pelcro platform along side the nickname).Optional
plan.temporary_product_idThe 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_idThe unique identifier previously used to refer to the plan (also known as rate code, promo code).Required.
plan.typeThis 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_typeThe 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.entitlementsThe 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.amountplan.currencyplan.autorenewplan.intervalplan.interval_countplan.nicknameplan.shipments_per_intervalplan.descriptionplan.common_metadata.account_nameplan.product_idplan.old_idplan.is_donatedplan.typeplan.revenue_recognition_type
19900eur141Europe Yearly Membership - Gold12Print+Digitalabcd1437112341donationshipment_based
1900cad031Canada Monthly Membership - Silver1Printabdc1563457890regularshipment_based

Subscriptions

During the customer conversion process you might encounter the following scenarios:

  1. One customer, referred to as a registered user, without any subscription.
  2. One customer, referred to as a subscribed user, with one active subscription.
  3. 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.

AttributeDescriptionRequired/Optional
subscription.current_period_endEnd 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_endThis 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_undeliverableBoolean 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_untilDate 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_expiredBoolean 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_nowBoolean 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_remainingThe 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.quantityDepending 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_methodThis 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_idThe 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_idUnique subscription identifier.This field is optional but in case of having gift subscriptions, it must be filled.
subscription.common_metadata.service_statusStatus 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_numberThe number of this subscription order (one of the order metadata).Optional.
subscription.common_metadata.order_priceThe price of this subscription order (one of the order metadata).Optional.
subscription.common_metadata.order_termThe term (length) of this subscription order.Optional.
subscription.typeThis 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.membershipThe 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_donorThis 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_recipientThis 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_idThe 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_endsubscription.cancel_at_period_endsubscription.start_datesubscription.shipments_undeliverablesubscription.shipments_suspended_untilsubscription.quantitysubscription.shipments_remainingsubscription.quantitysubscription.collection_methodsubscription.common_metadata.temporary_plan_idsubscription.common_metadata.old_idsubscription.common_metadata.is_expiredsubscription.common_metadata.service_statussubscription.common_metadata.order_numbersubscription.common_metadata.order_price
31/01/2021031/01/2020111charge_automatically123410121310active122334500
16/02/2022116/01/202211send_invoice5617340unpaid45726000
07/08/2022107/04/202212send_invoice133123450active122350

Limitations

There are some important limitations to be aware of when migrating your data in Pelcro’s system. You cannot migrate the following data:

  1. Expired subscriptions.
  2. Canceled subscriptions.
  3. 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:

  1. 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.)

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

  3. 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.)

  4. 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:

  1. subscription.common_metadata.is_gift_donor
  2. subscription.common_metadata.is_gift_recipient
  3. 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:

  1. Drupal_v8.2.x
  2. Bcrypt (WordPress)
  3. Bcrypt
  4. MD5
  5. 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:

  1. A minimum of 5 password examples (hashes and their equivalent plain text).
  2. 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.
  3. 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:

  1. The migration team will prepare the data files to perform the migration to staging.
  2. The migration team will run the script to migrate the data into the staging environment.
  3. 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:

  1. Attribute: Property of a given object type.
  2. Pelcro Pre-Processed: number of records fed into Pelcro’s migration script.
  3. Excel dump: number of records included in the customer data dump.
  4. Accuracy: Measure of how many records were kept between the excel dump and Pelcro's migration script.
  5. Inaccuracy: Compliment of accuracy.
  6. Dry-run (staging): number of valid records migrated into the staging server.
  7. Production: number of valid records migrated into the production server.
2318

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:

  1. Review the report generated by the Pelcro migration team
  2. Validate the numbers
  3. Validate sample data in the Pelcro Dry-run environment.
  4. 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:

  1. 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.
  2. 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:

  1. Billing and Shipping Addresses
  2. 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:

  1. Get familiar with the requirements for credit card migration.
  2. You need an ID for each customer in the old payment processor files, which will be mapped to new customer IDs.
  3. 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.
  4. 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.
  5. 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.
  6. Use the mapping file to overwrite Pelcro data (customer record info, subscriptions, ..).
  7. 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

  1. Prepare the production data files.
  2. Initiate production data migration.
  3. 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 almost 3 years ago