Migrating Your Data

Data migration is the process of transferring your data from your old account management system to Pelcro. It is a meticulous process that requires the data to be normalized and transformed to fit the Pelcro structure. Our team has put together all the necessary tools at your disposal 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. Review and understand the scope of the data migration.
  2. Request a data export from your current provider.
  3. Populate Pelcro's migration templates found here, by using the data conversion tables
  4. If Pelcro is migrating your data, request Pelcro's SFTP server credentials from your account manager and upload your converted files to Pelcro's SFTP server.
  5. Perform a migration test run on a staging environment, which consists of importing the following objects:
    a. Customers.
    b. Subscriptions.
    c. Addresses.
    d. Products.
    e. Plans.
  6. Analyze the test data, and work with the feedback provided by Pelcro's migration engineers to improve the data quality.
  7. Plan the production migration.
    a. Initiate credit card migration process.
    b. Prepare the production data files.
    c. Initiate production data migration.
    d. Validate production data.

👍

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 and deliver the data migration significantly 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. The options are outlined below:

3 predefined CSV files.

File 1: Merge customers, subscriptions and addresses into 1 file.
File 2: Products.
File 3: Plans.

Download links to the 3 templates:

  1. Pelcro migration template for customer data
  2. Pelcro migration template for plans
  3. Pelcro migration template for products

5 predefined CSV files.

File 1: Customers.
File 2: Subscriptions.
File 3: Addresses.
File 4: Products.
File 5: Plans.

Download links to the 5 templates:

  1. Pelcro migration template for customer data
  2. Pelcro migration template for subscription data
  3. Pelcro migration template for address data
  4. Pelcro migration template for plans
  5. 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 (or registered users, we use them interchangeably throughout this document). These would include:

  1. 'Active Authenticated Users'.
  2. 'Inactive Authenticated Users', referring to the inactive users that haven't logged in within the past few months.
  3. 'Active Subscribers' are a subcategory of the 'Active Authenticated Users' that have one or more active subscriptions.

All of the attributes below are tied to the customer data, where a customer record is defined by their unique old_provider_id value. If using the 3 file templates, a 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.

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 determine 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 password 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, and discard subscription data.
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:

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

  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

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

  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:

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.

When taxes are configured for your account, addresses are required for all eligible customers regardless of the type of product.

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 and seen by end-users.

Optional.

Product.statement_descriptor

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

  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:

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:

  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.

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 by which the shipments of a subscription will be suspended. This value can be used to filter subscriptions when building lists. To learn more, see Lists.

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.

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

  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.

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.

Gifts

Pelcro can migrate gifts. However, there is 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.
Sample statistics report.Sample statistics report.

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.

📘

Check out these helpful articles for more information on our blog


Did this page help you?