--- updatedAt: 2026-02-26T18:40:09.000Z agentTools: projectIndex: https://docs.pelcro.com/v2.4/llms.txt --- # Migrating Your Data ![](https://files.readme.io/aaecc0a-getting-startedd-03.jpg "getting-startedd-03.jpg") 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 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 possesses extensive expertise in database systems, including proficient data mapping techniques, and has harnessed this knowledge to successfully transfer over 1,000,000 subscriptions across multiple businesses. We have migrated businesses from several other systems including but not limited to CDS, Piano, PayPal, Braintree, TownNews, Pigeon, Pico, Salesforce, and Clickshare. The analysis and preparation phase for data migration generally spans between one to three weeks, provided that the data supplied conforms 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](https://docs.pelcro.com/reference/api-core-intro). When Pelcro's migration team is assigned to migrate your data, it's essential for both parties to collaborate in following the procedure outlined in this section. This collaborative effort encompasses all the crucial measures required to ensure a successful migration. 1. Review and understand the [scope of the data migration](https://docs.pelcro.com/docs/migrating-your-data#understanding-your-data-scope). 2. Request a data export from your current provider. 3. Populate Pelcro's migration templates found [here](https://docs.pelcro.com/docs/migrating-your-data#migration-file-templates), by using the data conversion tables. 4. Request Pelcro's migration scope sheet and SFTP server credentials from your account manager and upload your converted files and the approved migration scope sheet to Pelcro's SFTP server. 5. Pelcro's migration team will perform the necessary validations on the data files provided by your team and offer feedback if necessary. 6. Once the files are approved by Pelcro's migration team, we will perform a migration test run on our staging environment. 7. Our migration team will analyze the test data, provide the stats sheet, and furnish feedback regarding the results of the migrated data. More details about this step can be found [here](https://docs.pelcro.com/docs/migrating-your-data#performing-a-data-migration-into-a-staging-environment). 8. To ensure a seamless migration, Pelcro's QA team will conduct various tests related to the migrated data based on the scope of the migration and will provide the required feedback: a. Password migration b. User interface flows, such as customer login and subscription view c. Essential aspects related to the Pelcro platform like list and fulfillment generation, subscription view, etc. 9. Your account manager will provide you with test account credentials so that you can conduct your own tests and validate data accuracy. The suggested approach can be found [here](https://docs.pelcro.com/docs/migrating-your-data#reviewing-and-analyzing-the-data-migration). 10. Once both teams approve the data accuracy, we will plan the production migration and agree on the GoLive date. The following steps will be required for production migration: a. Initiate the credit card migration process (if included in the scope of the data migration). More details can be found [here](https://docs.pelcro.com/docs/migrating-your-data#migrating-credit-cards-to-production). 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 and we're happy to assist with any questions or concerns. # Understanding your data scope Before performing any data migration, it is indispensable 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 canceled 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 subscriptions with an outstanding open invoice that must be charged upon import? 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 with a data dump as-is from the current provider. # Building your migration files First, download Pelcro's migration file templates that are linked below. Each file represents an object resource in Pelcro, and it is important to only download and build the migration files for the resource you will be migrating. For example, if you will not be migrating group members subscriptions, do not build the 'Memberships' file. The file templates contain field headers in a CSV format. Use the tables below to populate the file templates with the relevant data, according to the field description and mandate (required vs. optional). ## Migration file templates [Customers](https://pelcro-documentation.s3.amazonaws.com/migration/pelcro_customers_template.csv) [Subscriptions](https://pelcro-documentation.s3.amazonaws.com/migration/pelcro_subscriptions_template.csv) [Addresses](https://pelcro-documentation.s3.amazonaws.com/migration/pelcro_address_template.csv) [Plans](https://pelcro-documentation.s3.amazonaws.com/migration/pelcro_plans_template.csv) [Products](https://pelcro-documentation.s3.amazonaws.com/migration/pelcro_products_template.csv) [Memberships](https://pelcro-documentation.s3.amazonaws.com/migration/pelcro_memberships_template.csv) [Invoices](https://pelcro-documentation.s3.amazonaws.com/migration/pelcro_migration_template_invoice.csv) [Charges](https://pelcro-documentation.s3.amazonaws.com/migration/pelcro_migration_template_Offline_charges.csv) [Newsletters](https://pelcro-documentation.s3.amazonaws.com/migration/pelcro_migration_template_newsletter.csv) ## Customers Customers are registered users to which we associate addresses, subscriptions, payments, invoices, etc. You can migrate all of your users' profile information into Pelcro by either filling in the preset fields on the template (email address, phone number, etc.) or by adding your own custom fields which will get stored in the customer record's metadata table. The table below contains the list of attributes that make up the Customers resource migration file template: {`
Attribute Description Required/Optional

old_provider_id

The old provider id corresponds to the customer's ID as seen on your old provider's database.

In the Addresses and Subscriptions file, this field is known as 'customer_id'.

This value must be a unique ID, and can be any of the following values:
1. Numeric value.
2. Alphabetic value.
3. Alphanumeric value.

Required.

email

The email field corresponds to the customer's email address. A customer can only have one email address.

This value must be unique, meaning the email address cannot be shared across different customer records.

Optional.

first_name

The customer's first name.

Optional.

last_name

The customer's last name.

Optional.

phone

The customer's phone number.

This field has a 20-character limit , and alphabetic characters are not supported.

Here are some examples of accepted values:
0015141234567
+15141234567
+1.514.123.4567
+1-514-123-4567
(514)1234567
'empty'

Optional.

organization

The customer's company or organization name.

This field can be used to group customers of a same company/organization together by entering the same Organization value. Watch out, it's case sensitive!

Optional.

password_type

This field indicates the type of encryption used to hash the provided passwords.

The 'password_type' field can take the following values:
'plain_text'
'password_bcrypt'
'MD5'
'bcrypt_wordpress'
'argon2id'
'drupal_v8.2.x'

Optional.

password

This field corresponds to the customer's hashed password.

Optional.

import_payment_methods

A boolean on whether to import payment methods associated with the provided 'payment_gateway_id' from the current payment gateway provider. This is used to import the payment methods during a migration in order to re-create the subscriptions using those payment methods.

Optional. Required only when importing payment methods alongside customer records.

payment_gateway_id

The unique identifier for customer on your current payment gateway provider (e.g. Stripe). You can pass this identifier during a migration in-order to import the customer's payment methods from the payment gateway so that you can re-create the subscriptions using the payment methods. Once imported from the gateway, you can find the default source in the customer list API endpoint which can be used to re-create the subscriptions.

Optional. Required only when importing payment methods alongside customer records.

metadata[field_name]

The metadata is a custom data field that allows you, as a business, to store customer data that does not fit in Pelcro's preset fields.

You can customize the field name by replacing the text in brackets.
Some examples of metadata field names can be found below:
metadata[job_area]
metadata[first_login_date]
metadata[age]
metadata[job_type]

Optional.
`} Here are some examples of customer records formatted into Pelcro's Customers migration file template: | old\_provider\_id\* | email | first\_name | last\_name | phone | organization | metadata\[job\_area] | metadata\[job\_type] | | :------------------ | :---------------------- | :---------- | :--------- | :-------------- | :----------- | :--------------------------------- | :------------------- | | 143278 | | Gerard | Cassano | 0015141234567 | Rocket | Digital / eCommerce / Omnicommerce | Administrator | | abc1234 | | Jane | Doe | | Pelcro | | | | 1234abc | | D | Williams | +1-514-123-4567 | Pelcro | Analytics / Data Analysis | Analyst | | abcdef | | Accounting | | +15141234567 | | Executive / Corporate Management | | ## Addresses Addresses provide contact information related to customers and their subscriptions. That includes shipping and billing addresses. If your Pelcro account checks any of the boxes below, the shipping address will be required to migrate your subscriptions into Pelcro. If you are unsure of whether there is an address requirement to create subscriptions, please contact or your account manager. 1. Sales tax collection is enabled on your account. 2. The address is required on the subscription product. This is typically the case when a product needs to be shipped to the subscriber. In this case, the shipping address will only be required to migrate subscriptions on the given Product. 3. The payment gateway connected to your account requires an address to process charges. The table below contains the list of attributes that make up the Address resource migration file template: {`
Attribute Description Required/Optional

old_provider_id

This field corresponds to the user's address record ID as seen on your old provider's database.

In the Subscriptions and Memberships file, this field is known as 'address_id'.

This value must be a unique ID, and can be any of the following values:
1. Numeric value.
2. Alphabetic value.
3. Alphanumeric value.

Required.

customer_old_provider_id

The customer ID corresponds to the old.provider_id of the customer record tied to this address.

A customer can have multiple addresses, of different types. Add an address record for each address a customer has, tying them to the same customer_id.

Required.

type

The type indicates whether this address is of type 'shipping' or 'billing'.

Required.

first_name

The first name on the address record.

Optional.

last_name

The last name on the address record.

Optional.

title

The customer's job title on the address record.

Optional.

salutation

The customer's salutation or courtesy title on the address record.

Optional.

company

The customer's company name on the address record.

Optional.

department

The customer's job department name on the address record.

Optional.

phone

The customer's phone number on the address record.

This field has a 20-character limit , and alphabetic characters are not supported.

Here are some examples of accepted values:
'0015141234567'
'+15141234567'
'+1.514.123.4567'
'+1-514-123-4567'
'(514)1234567'
'empty'

Optional

line1

The line1 indicates the first address line, typically used for the street address.

Required.

line2

The line2 indicates the secondary address information, such as the apartment/suite/post office box number.

Optional.

city

The city on the address record.

Optional.

state

The state on the address record.

For all US and Canadian addresses, the state value must adhere to the 2-letter ISO standard format found here.

Optional.

country

The country on the address record.

Country values must adhere to the 2-letter ISO standard format found here.

Required.

postal_code

The zip/postal code on the address record.

Optional.

is_default

The is_default flag is a boolean value that takes the values: '1' or '0', indicating whether the address record is the customer's default address or not, respectively.

This flag is optional, and is typically used for customers who have multiple addresses on record.

Optional.
`} Here are some examples of addresses formatted into Pelcro's Addresses migration file template: | old\_provider\_id\* | customer\_old\_provider\_id\* | type\* | first\_name | last\_name | title | phone | Company | line1\* | line2 | city | state | country | postal\_code | is\_default | | ------------------- | ----------------------------- | -------- | ----------- | ---------- | ----- | ------------- | ------- | -------------------------- | -------- | -------- | ----- | ------- | ------------ | ----------- | | 11223 | 143278 | shipping | Gerard | Cassano | Admin | 0015141234567 | Rocket | 3555 Ch. Cote-des-Neiges | Apt. 412 | Montreal | QC | CA | H32 1N5 | | | a5e01f | abc1234 | billing | Jane | Doe | | | Pelcro | 469 Homewood Ave.Levittown | | New York | NY | US | 05510 | | | a5e01g | abc1234 | shipping | Jane | Doe | | | Pelcro | 469 Homewood Ave.Levittown | | New York | NY | US | 05510 | 1 | ## Products Subscription Products describe the goods or services that your business offers to your customers. Each product can contain one or multiple pricing plans, which are often grouped together based on the nature of the component being offered. For example, a newspaper offers a digital access subscription, as well as a print copy subscription to their customers. One product would be created for each type, and pricing plans would be added to each product. The pricing plan carries the price and the duration/term of the good or service you are offering. More on this [here](https://docs.pelcro.com/docs/migrating-your-data#plans). The table below contains the list of attributes that make up the Products resource migration file template: {`
Attribute Description Required/Optional

old_provider_id

This field corresponds to the identifier of the Product your are migrating into Pelcro.

This value will be used to tie your pricing plans (or rates) to the corresponding Products you will be migrating. In the Plans file, this field is known as 'product_id'.

This value must be a unique ID, and can only contain alphanumeric characters.

Required.

name

The product name that will be displayed on the offer page.

Required.

name_internal

The product's internal name, that can only be seen from the CRM.

Optional.

address_required

This boolean flag indicates whether a shipping address is required to purchase this product.

Indicate '0' if the address is not required, and '1' if it is.

Required.

description

The description of the product you are offering, that can be made visible on offer pages.

Optional.

statement_descriptor

The label that will appear on your customer's bank statement when they purchase a subscription to this product.

This field has a limit of 22 characters.

Optional.
`} Here are some examples of products formatted into Pelcro's Product migration file template: | old\_provider\_id\* | name\* | name\_internal | address\_required\* | description | statement\_descriptor | | :------------------ | :----------------------- | :------------- | :------------------ | :-------------------------------------------------------------------------------- | :-------------------- | | DIGITAL-E01 | Digital Access | | 0 | Get digital access to premium content. | Digital Subscription | | 1196 | Home Delivery | Print0001 | 1 | Enjoy a fresh copy of the latest news delivered to your doorstep. | Home Delivery | | printanddigital | Print and Digital Bundle | | 1 | Subscribe to our print & digital bundle for all-access to our exclusive magazine. | | ## Plans The pricing plan, also known as the rate, will dictate the price, the currency, the terms and the duration of the good or the service you are offering. You cannot create a subscription without a pricing plan, and you cannot create a pricing plan without a Product. This relationship has been surfaced on the migration templates, by allowing you to tie files together using common fields, namely 'plan\_id' and 'product\_id'. Learn more about the [Plans](https://docs.pelcro.com/docs/subscription-plans) resource and its associated properties. The table below contains the list of attributes that make up the Plans resource migration file template: {`
Attribute Description Required/Optional

old_provider_id

This field corresponds to the identifier tied to the Plan your are migrating into Pelcro.

This value will be used to tie your customer's subscriptions to the plans that carry the price, currency and duration of the subscription service.

In the Subscriptions file, this field is known as 'plan_id'.

This value must be a unique ID, and can only contain alphanumeric characters.

Required.

product_old_provider_id

This field corresponds to the old.provider_id of the product that this plan will be tied with.

A product can have multiple plans. Add a plan for each rate you are offering, tying them to the same product_id.

Required.

type

This boolean flag indicates the type of the plan. Indicate 'regular' for individual subscription plans, and 'membership' for group subscription plans.

Gift subscriptions can only be created on 'regular' plans.

Required.

nickname

The plan name that will be displayed on offer pages.

Required.

name_internal

The plan's internal name, that can only be seen from the CRM.

Optional.

auto_renew

This is a boolean value describing the auto-renewal status of the plan. Indicate '1' if a subscription to this plan will automatically renew, and '0' if it will not.

Required.

amount

The plan's unit price.

For example: A plan for $8.99 must be entered as '899' in the amount field.

Required.

currency

The plan's currency. A plan can be offered in one currency.

Required.

recognized_revenue_type

This is a boolean value describing the recognition method for revenue earned for this subscription plan.
Indicate 'time' or 'shipments'. For more information on recognized revenue and its impact on the accounting module, see Recognized revenue.

Required.

interval

This value describes the plan's billing interval.

This field can take the following values:
'day'
'week'
'month'
'year'

*_Required. _

interval_count

This value indicates the plan's billing cycle and must be used in coordination with the 'interval' value, according to the instructions below.

For a yearly plan, set:
1. interval = year.
2. interval_count = 1.

This indicates that the subscription will be billed on a yearly basis.

For a bi-monthly plan, set:
1. plan.interval = month.
2. plan.interval_count = 2.

This indicates that the subscription will be billed every 2 months.

Required.

available_online

This is a boolean value indicating whether the plan will be displayed on offer pages or not.
Indicate '1' if the plan will be displayed online as a subscription offer, and '0' otherwise.

Required.

refundable

This is a boolean value indicating whether a subscription to this plan can be refundable, or not.
Indicate '1' if the subscription can be refundable, and '0' otherwise.

Required.

description

The description of the plan you are offering, that can be made visible on offer pages.

Optional.

entitlements

The entitlement field takes an array of comma-separated tags that can be used to control access to a product or service when a user subscribes to this plan.
Example: 'entitlements' = 'premium,digital'.

More of entitlements and how they work here.

Optional.

trial_period_days

This field takes the number of days that will be offered as a trial period when a user subscribes to this plan. Indicate '0' if it is a non-trial plan.

Required.

shipments_per_interval

This value represents the number of shipments/issues associated with this plan, taking into account the plan's interval term.

1. For a 1-year plan with a monthly shipment schedule, indicate '12' for 12 shipments a year.

2. For a monthly plan with a weekly shipment schedule, indicate '4' for 4 shipments a month.

Optional.

member_seat_capacity

This field indicates the maximum seat capacity on this group subscription plan.

Required only when plan type is 'membership'.
`} Here are some examples of plans formatted into Pelcro's Plans migration file template: | old\_provider\_id\* | product\_old\_provider\_id\* | nickname\* | type\* | auto\_renew\* | amount\* | currency\* | recognized\_revenue\_type\* | interval\* | interval\_count\* | available\_online\* | refundable\* | description | shipments\_per\_interval | member\_seat\_capacity | | :------------------ | :--------------------------- | :-------------------------------------- | :--------- | :------------ | :------- | :--------- | :-------------------------- | :--------- | :---------------- | :------------------ | :----------- | :------------------------------------------ | :----------------------- | :--------------------- | | MONTH-D-I | DIGITAL-E01 | Silver Subscription: Monthly auto-renew | regular | 1 | 4 | CAD | time | month | 1 | 1 | 1 | Monthly subscription to all-digital access. | | | | 010193 | 1196 | 1-year home delivery subscription | regular | 0 | 59.99 | USD | shipments | year | 1 | 1 | 0 | Yearly auto-renewing print subscription. | 12 | | | YEAR-D-M | DIGITAL-E01 | 1-year Corporate Group Subscription | membership | 0 | 999.99 | CAD | time | year | 1 | 0 | 0 | Yearly site license membership plan. | | 1000 | ## Subscriptions The subscription is the piece that connects the registered user, *Customer*, to the good or service you are offering, the pricing *Plan*. The subscription carries relevant information such as its end date, its auto-renewal status, the payment method used to purchase the subscription, as well as the number of shipments/issues remaining on a user's subscription. Subscriptions can be tied to individual customers, as well as multiple. Pelcro supports migrating group/corporate subscriptions, and gift subscriptions (from one user to another). If you will be migrating group subscriptions into Pelcro, the group admin and user subscriptions must be split into two files. The group admin subscription must be added to the Subscriptions file template and carry the type 'admin'. The group member subscription must be added to the [Memberships](https://docs.pelcro.com/docs/migrating-your-data#memberships) file template. Learn more about the [Subscriptions](https://docs.pelcro.com/docs/subscriptions) resource and its associated properties. The table below contains the list of attributes that make up the Subscriptions resource migration file template: {`
Attribute Description Required/Optional

old_provider_id

The subscription ID is the unique identifier tied to the Subscription your are migrating into Pelcro.
You can use your old provider's subscription/order ID here.

In the Memberships file, this field is known as 'subscription_id'.

This value must be a unique ID, and can be any of the following values:
1. Numeric value.
2. Alphabetic value.
3. Alphanumeric value.

Required.

customer_old_provider_id

The customer ID corresponds to the old.provider_id of the customer record tied to this subscription.

This ID will be used to tie your customer to this subscription.
A customer can have multiple subscriptions, of different types. Add a new record for each subscription a customer has, tying them to the same customer_id.

Required.

address_old_provider_id

This value corresponds to the old.provider_id of the address record tied to this subscription.

Required only when the address is required to purchase a subscription. More on this here.

source

This field indicates the source by which this subscription was acquired.

The 'source' field can take the following values:
'phone'
'email'
'website'
'renewal'
'agency'

Required.

plan_old_provider_id

This field corresponds to the plan_id value in the Plans file. It is used to tie the subscription to the corresponding plan that carries the price, currency and duration of the subscription service.

The subscription will inherit all of the billing information from the plan, in addition to the plan type (whether it is a regular or group subscription plan).

Required.

collection_method

This field indicates the billing method used to acquire this subscription.

The 'collection_method' field takes one of the two possible values:
'charge_automatically'
'send_invoice'

Charge automatically indicates that a credit card was charged to create this subscription, whereas send invoice indicates that the subscription is paid via an offline payment (check, cash, wire payment, etc..).

The collection method can only be of type 'charge automatically' if the user's credit card has been migrated/exists in Pelcro; Pelcro will automatically convert this value to 'send invoice' otherwise.

Required.

auto_renew

This is a boolean value describing the auto-renewal status of the subscription. Indicate '1' if the subscription will automatically renew on them same plan at the end of the current subscription period, and 0 if the subscription will terminate at the end of the current period.

Note: If 'auto-renew = 1', the subscription must be tied to an auto-renewal plan.

Required.

quantity

This value indicates the quantity of subscriptions purchased, often used when there is a print component tied to the subscription.

This value must be an integer, and in most cases should be set to 1.

Required.

import_dynamic_end_date

This value indicates the subscription's current period end date.

In the case of auto-renewing subscription, the subscription will renew on this date.

The 'import_dynamic_end_date' value must adhere to the format below:
MM/DD/YYYY

Required.

next_invoice_date

This value indicates whether the subscription is awaiting payment or has been paid for.
Leave this field blank if the subscription is awaiting payment and must be migrated as an 'Open invoice' subscription, or populate this field with the 'import_dynamic_end_date' value if the subscription must be migrated with a closed/paid invoice.

Required.

shipments_remaining

This value corresponds to the number of shipments remaining/issues to go for the current subscription's period (based on the import_dynamic_end_date value).

This value must be an integer.

Optional.

is_gift_donor

This field indicates whether this is a gift donor subscription. Indicate '1' if this is the case, otherwise leave the field blank.

For more information on migrating your gift subscriptions to Pelcro, see Gifts.

Optional, required for gift donor subscription records.

gift_donor_old_provider_id

This field indicates whether this is a gift recipient subscription. Populate this field with the old.provider_id of the gift donor subscription if this is the case, otherwise leave the field blank.

For more information on migrating your gift subscriptions to Pelcro, see Gifts.

Optional, required for gift recipient subscription records.

campaign_key

The promotional or campaign key tied to this subscription.

This value can be any of the following values:
1. Numeric value.
2. Alphabetic value.
3. Alphanumeric value.

This field can be used to group and track subscriptions acquired through the same campaign/channel. Watch out, it's case sensitive!

Optional.

domains

This field corresponds to the email domains that will allow end-users to become group members of this subscription upon registration/login.

This field can only be populated when the subscription is tied to a Plan with 'type = membership'.

This field supports an array of comma-separated values.

Below is an example:
'domains = pelcro.com,pelcro.ca'

If jane.doe@pelcro.com or john.doe@pelcro.ca register/login to your website, they will automatically become a member of this group subscription.

Optional.

ip_addresses

This field corresponds to the IP addresses that will allow end-users to become group members of this subscription upon registration/login.

This field can only be populated when the subscription is tied to a Plan with 'type = membership'.

Multiple IP addresses can be added as an array of comma-separated values. This field also supports CIDR notation.

Below is an example:
'ip_addresses = 10.193.28.01,12.160.1.01/26'

Any user registering or logging in via one of the listed IP addresses will automatically become a member of this group subscription.

Optional.

shipments_undeliverable

This is a boolean value indicating whether a shipment is deliverable or not.

Indicate '1' if the subscription's shipment status is 'undeliverable', leave the field blank otherwise.

This field can be used to filter out subscriptions when building shipping/fulfillment lists. To learn more, see Lists.

Optional.

shipments_suspended_until

This field indicates the date by which the shipments of a subscription will be suspended.

The 'shipments_suspended_until' value must adhere to the following date format:
MM/DD/YYYY

This field can be used to filter out subscriptions when building shipping/fulfillment lists. To learn more, see Lists.

Optional.

metadata[field_name]

The metadata is a custom data field that allows you, as a business, to store subscription data that does not fit in Pelcro's preset fields.

You can customize the field name by replacing the text in brackets.
Some examples of metadata field names can be found below:
metadata[first_issue_date]
metadata[old_subscription_id]

Optional.
`} Here are some examples of gift donor (1), open invoice (2), group owner (3) and gift recipient (4) subscription records, formatted into Pelcro's Subscription migration file template: | old\_provider\_id\* | customer\_old\_provider\_id\* | address\_old\_provider\_id | source\* | plan\_old\_provider\_id\* | collection\_method\* | auto\_renew\* | quantity\* | import\_dynamic\_end\_date | next\_invoice\_date | shipments\_remaining | is\_gift\_donor | gift\_donor\_subscription\_id | domains | ip\_addresses | | :------------------ | :---------------------------- | :------------------------- | :------- | :------------------------ | :-------------------- | :------------ | :--------- | :------------------------- | :------------------ | :------------------- | :-------------- | :---------------------------- | :------------------- | :-------------------------- | | 11223344 | 143278 | 11223 | website | MONTH-D-I | charge\_automatically | 1 | 1 | 08/25/2023 | 08/25/2023 | | 1 | | | | | def1234 | abcdef | AeCGgEv | agency | 010193 | send\_invoice | 1 | 1 | 01/01/2024 | | 11 | | | | | | 1234def | abc1234 | a5e01f | email | YEAR-D-M | send\_invoice | 0 | 1 | 02/28/2025 | 02/28/2025 | | | | pelcro.com,pelcro.ca | 10.193.28.01,12.160.1.01/26 | | aabbccdd | 1234abc | | website | MONTH-D-I | send\_invoice | 1 | 1 | 08/25/2023 | 08/25/2023 | | | 11223344 | | | ## Memberships The membership represents the group member subscription to the good or service you are offering. This template must only be filled out if you are intending on migrating group/school/corporate subscriptions into Pelcro. The membership (group member) record will be tied to the group owner subscription record (any subscription tied to a plan with 'type = membership'). Learn more about the [Memberships](https://docs.pelcro.com/docs/memberships) resource and its associated properties. The table below contains the list of attributes that make up the Memberships resource migration file template: {`
Attribute Description Required/Optional

old_provider_id

This field corresponds to the user's membership ID as seen on your old provider's database.

This value must be a unique ID, and can be any of the following values:
1. Numeric value.
2. Alphabetic value.
3. Alphanumeric value.

Optional

subscription_old_provider_id

The subscription ID corresponds to the old.provider_id of the group admin subscription record this membership is tied with.

Required

customer_old_provider_id

The customer ID corresponds to the old.provider_id of the customer record tied to this group member record.

This ID will be used to tie your customer to this group member record.

Required

address_old_provider_id

This value corresponds to the old.provider_id of the address record tied to this membership.

Required only when the address is required to subscribe to a product. More on this here.
`} Here are some examples of group member subscriptions formatted into Pelcro's Memberships migration file template: | old\_provider\_id | subscription\_old\_provider\_id\* | customer\_old\_provider\_id\* | address\_old\_provider\_id | | :---------------- | :-------------------------------- | :---------------------------- | :------------------------- | | 67abc | 1234def | abc1234 | | | | aabbccdd | 143278 | AeCGgEv | ## Invoices Invoices outline the amounts a customer owes for purchasing your products or services. Depending on how they are generated, they can be either one-time or recurring. This guide will help you navigate through your invoices. For further details, refer [here](https://docs.pelcro.com/docs/invoices). The table below contains the list of attributes that make up the invoices resource migration file template: | Attribute | Description | Required/Optional | | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- | | currency | The currency code. Must be valid for the account and customer. | **Required.** | | old\_provider\_id | The unique identifier of this invoice from the previous provider. If provided, must be unique under the same account. | **Required.** | | line\_items | Details about the invoiced goods/services, including description, price, quantity, and optional tax info. Required if total is not provided. | **Required.** | | total | The total invoice amount in minor units (e.g., cents). Required if line\_itemsis not provided. | **Required if line\_items are not provided.** | | customer\_id | The unique ID of the customer. Required if customer\_old\_provider\_id is not provided. | **Required.** | | customer\_old\_provider\_id | The old provider ID assigned to the customer who owns this invoice. If provided, customer\_id can be omitted. | Optional. | | period\_start | Start of the line item's billing period formate (MM-DD-YYYY). Must be before or equal to period\_end. | Optional. | | period\_end | End of the line item's billing period formate (MM-DD-YYYY). Must be after or equal to period\_start. | Optional. | | due\_date | The date when the invoice will be due. Must be after or equal to period\_start. | Optional. | | status | The invoice status: draft, open, paid, uncollectible, or void. | **Required.** | | billing\_reason | Indicates why the invoice was created: manual, subscription\_create, subscription\_cycle, subscription\_update, or order\_create. | **Required.** | | subscription\_id | The unique ID of the subscription assigned to this invoice. Can be omitted if subscription\_old\_provider\_id is provided. | Optional. | | subscription\_old\_provider\_id | The old provider ID of a previously created subscription. Can be omitted if subscription\_id is provided. | Optional. | | customer\_address | An address object representing the customer's billing address. If omitted, the default is the customer’s saved billing address. | Optional. | | billing\_address\_id | The ID of the billing address linked to the customer or invoice. Can be omitted if customer\_address is provided. | Optional. | | customer\_shipping | An address object representing the customer's shipping address. If omitted, the default is the customer’s saved shipping address. | Optional. | | shipping\_address\_id | The ID of the shipping address linked to the customer or invoice. Can be omitted if customer\_shipping is provided. | Optional. | | is\_imported | Defaults to false. A flag determining whether this invoice was imported. | Optional. | Here are some examples of invoices formatted into Pelcro's invoices migration file template: | old\_provider\_id | customer\_old\_provider\_id | customer\_id | total | currency | subscription\_id | subscription\_old\_provider\_id | status | line\_items | period\_start | period\_end | due\_date | billing\_reason | customer\_address | billing\_address\_id | customer\_shipping | shipping\_address\_id | is\_imported | | ----------------- | --------------------------- | ------------ | ----- | -------- | ---------------- | ------------------------------- | ------ | ----------- | ------------- | ----------- | ---------- | -------------------- | ----------------- | -------------------- | ------------------ | --------------------- | ------------ | | old\_inv\_12345 | 143278 | | 5000 | usd | | 11223344 | paid | | 08/25/2022 | 08/25/2023 | 08/25/2022 | subscription\_create | | | | | | | old\_inv\_12346 | abcdef | | 12000 | cad | | def1234 | open | | 01/01/2023 | 01/01/2024 | 01/01/2023 | subscription\_create | | | | | | | old\_inv\_12347 | abc1234 | | 7500 | eur | | 1234def | paid | | 02/28/2023 | 02/28/2025 | 02/28/2023 | subscription\_create | | | | | | ## Offline charges Offline charges in Pelcro refer to payments that are processed outside the normal subscription flows. These charges can include payments made via methods such as checks, wire transfers, cash, external payment systems, or older systems. By using offline charges, businesses can track and manage payments received from customers through non-digital channels while ensuring that all financial transactions are accurately recorded in the Pelcro system. This feature is crucial for maintaining up-to-date records of customer payments, regardless of the payment method used, and helps streamline the accounting and reconciliation processes. The table below contains the list of attributes that make up the offline charges resource migration file template: | Attribute | Description | Required/Optional | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------- | | customer\_id | A unique identifier of the customer that will be charged. | **Required.** | | amount | The amount in cents that will be deducted from the customer. If the related invoice is paid, it must match the invoice total. | **Required.** | | reference | The reference of this charge. | **Required.** | | currency | The currency of the charge (e.g., CAD, USD). | **Required.** | | payment\_category | Indicates the payment method: 2 for check, 3 for wire, 4 for transfer, 5 for external, 6 for cash. | **Required.** | | invoice\_id | The unique identifier of the invoice associated with this charge. | Optional. | | invoice\_old\_provider\_id | The old provider ID that was assigned to the invoice related to this charge. | Optional. | | customer\_old\_provider\_id | The unique identifier which was added to the customer who owns this invoice. If provided, customer\_id can be omitted. | **Required.** | Here are some examples of offline charges formatted into Pelcro's offline charges migration file template: | customer\_old\_provider\_id | amount | reference | currency | payment\_category | invoice\_id | invoice\_old\_provider\_id | customer\_id | | --------------------------- | ------ | ------------ | -------- | ----------------- | ----------- | -------------------------- | ------------ | | 143278 | 5000 | INV-20250101 | usd | Cash | 98765 | old\_inv\_12345 | | | abcdef | 12000 | INV-20250102 | cad | External | 98766 | old\_inv\_12346 | | | abc1234 | 7500 | INV-20250103 | eur | Cash | 98767 | old\_inv\_12347 | | ## Newsletters Newsletters are automated emails that businesses can enable to reach their subscribers and members. You might wonder, 'Why are they important?' When executed effectively, newsletters serve as a powerful tool to boost sales, promote new features, and maintain audience engagement with minimal effort. For more details, visit [here](https://docs.pelcro.com/docs/newsletters). The table below contains the list of attributes that make up the newsletters resource migration file template: | Attribute | Description | Required/Optional | | ------------- | ---------------------------------------------------------------------------------------------- | ----------------- | | email | The unique email of the newsletter. | **Required.** | | source | The source for the newsletter. Accepts one of the following values: (Web, Phone, Mail, Other). | **Required.** | | first\_name | The first name for the newsletter. | Optional. | | last\_name | The last name for the newsletter. | Optional. | | postal\_code | The postal code for the newsletter. | Optional. | | lists | The lists of the newsletter in comma-separated format. | Optional. | | consent\_url | The consent URL for the newsletter. | Optional. | | consent\_ip | The consent IP address for the newsletter. | Optional. | | consent\_text | The consent text for the newsletter. | Optional. | | consent\_type | The consent type for the newsletter. | Optional. | Here are some examples of newsletters formatted into Pelcro's newsletters migration file template: | email | lists | source | first\_name | last\_name | postal\_code | | ---------------- | ----------------- | :----- | ----------- | ---------- | ------------ | | | Weekly Newsletter | Web | John | Smith | 10001 | | | Promotions,Events | Other | Lisa | Brown | 90001 | # 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. There are also limitations with migrating open active subscriptions ('next\_invoice\_date = NULL'). 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 different scenarios and expected behaviors have been outlined below: 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)](https://docs.pelcro.com/docs/invoices#automatic-uncollectible) 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. # Gifts You can migrate your gift subscriptions into Pelcro. It is important to note how gift subscriptions are structured in Pelcro prior to the migration, as it may be different than the way your gift subscriptions are built on your old provider's database. In Pelcro, a gift subscription is split into two subscriptions: the gift donor subscription and the gift recipient subscription records. In order to migrate your gifts into Pelcro, you must have two subscription records per gift subscription. Both subscription records must contain the same subscription data, with the exception of: a. old.provider\_id (must be unique) b. customer\_id (since the gift donor and gift recipient are often not the same user). c. address\_id d. is\_gift\_donor e. gift\_donor\_subscription\_id The 'is\_gift\_donor' field is a flag that will indicate whether the subscription record in question is a gift donor subscription record. The 'gift\_donor\_subscription\_id' field indicates that the subscription record in question is a gift recipient subscription, and will be tied to its donor record via the 'old\_provider\_id' value. This format must be adhered to in order to successfully import gift subscriptions into Pelcro. # 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 of importing the user passwords upon GoLive. # Deferred Revenue ## What is Deferred Revenue? Reference: [Pelcro Docs – Deferred Revenue](https://docs.pelcro.com/docs/accounting#deferred-revenue) ## How to Migrate Deferred Revenue To migrate deferred revenue into Pelcro, follow these steps: * Export a snapshot of deferred revenue balances from your current system. * Import invoices and the related payments into Pelcro. When dates and amounts are accurate, Pelcro’s accounting reports will reflect correct balances as long as the invoices and related payments are correctly tied to their respective subscription. * Ensure proper mapping between objects. Customer IDs, invoice numbers, dates, payment IDs, and amounts must match. ## Deferred Revenue Migration Steps 1. Gather the deferred revenue from the old provider. Example format: [invoice](https://docs.pelcro.com/docs/migrating-your-data#invoices) | old\_provider\_id | customer\_old\_provider\_id | total | currency | subscription\_old\_provider\_id | status | | ----------------- | --------------------------- | ----- | -------- | ------------------------------- | ------ | | Invoice\_ID | customer\_old\_provider\_id | 22981 | usd | Subscription\_old\_provider\_id | paid | 2. Create invoices for each customer tied to a subscription with the remaining amount. * The invoice should be imported as **paid**. * It must be linked to the correct `customer_old_provider_id` and `subscription_old_provider_id`. 3. For each paid invoice, import a related **[charge](https://docs.pelcro.com/docs/migrating-your-data#offline-charges)**. Example format: | customer\_old\_provider\_id | amount | currency | reference | invoice\_old\_provider\_id | | --------------------------- | ------ | -------- | ---------------------------- | -------------------------- | | customer\_old\_provider\_id | 22981 | usd | Invoice\_\_old\_provider\_id | |
4. To import invoices for a specific period and amount, add two extra columns to the invoice template: * `period_start` * `period_end` *** # Invoice Period Rules Use these rules to set `Period Start` and `Period End` when creating invoices tied to subscriptions. > **Quick Do/Don’t Checklist** > > * ✔ Do align`Period End` with the subscription. > * ✘ Don’t set `Period End` past the subscription expiry. 1. **Choose `Period Start` and `Period End` carefully.** These dates define the invoice time window. 2. **Keep `Period End` within the subscription expiry date.** If `Period End` goes beyond the subscription's expiry date, this will cause accounting mismatches. 3. **Understand the role of `Period Start`.** `Period Start` determines when the system begins recognizing the invoice. 4. **If `Period Start` is not specified.** The system will default it to the invoice migration date. 5. **When explicitly setting the period start and end dates** The amount should reflect the expected amount for that period. *** # Customer Balance ## What is Customer Balance? For the definition of **Customer Balance**, please refer to our [documentation](https://docs.pelcro.com/docs/customer-balance#/). Pelcro manages customer balances (credits and debits). These can come from prepayments, unapplied payments, or refunds. ## How to Migrate Customer Balance To migrate customer balances: * Decide what the balance represents: prepayments, unapplied payments, or refunds/chargebacks. * Import payments and credit notes as standalone transactions (charges) tied to each customer. By not attaching them to invoices, the full amount will be treated as a **Customer Balance**. ## Customer Balance Migration Steps 1. Prepare a [charges](https://docs.pelcro.com/docs/migrating-your-data#offline-charges) file linked only to a customer (no invoice). Example format: | customer\_old\_provider\_id | amount | currency | reference | | --------------------------- | ------ | -------- | -------------------------- | | customer\_old\_provider\_id | 22981 | usd | customer\_old\_id\_balance | 2. Import this file. * The charge will be added as a **Customer Balance** for the specified customer.
# 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 that 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. Screen Shot 2022-06-09 at 3.06.04 PM.png 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 critical to ensure your end users do not have to re-enter their payment details when switching from your legacy payment processor to your new one. Unlike migrating other types of data, credit card migrations require the intervention of a third-party vendor, which can impact the overall timeframe. ## General Migration Steps 1. Understand Requirements 1. Review all prerequisites for credit card migration. 2. Ensure you have a unique ID for each customer in the old processor files to map to new customer IDs. 2. Coordinate Processors 1. Your new payment processor will provide a file template for credit card information. 2. Work with your old payment processor to prepare the data dump file according to this template. 3. Transitionary Period (Freeze Window) 1. During the migration window, payments may be temporarily frozen. Options include: 1. Redirecting new subscriptions to customer service operators, who will manually process subscriptions and issue bill-to invoices. 2. For smaller businesses without operators, completely freeze new subscriptions during this period. 4. Import & Mapping 1. The new payment processor will confirm the import by providing a mapping file (JSON) containing: 1. Newly generated IDs (customers, payment methods, etc.) 2. Corresponding old payment processor IDs. 5. Update Pelcro Records 1. Use the mapping file to overwrite Pelcro data (customer records, subscriptions, etc.). 6. Validation & Approval 1. Validate the data across both providers. 2. Provide a final approval stamp before resuming normal operations. ## Stripe-Specific Migration When migrating between Stripe accounts, Stripe offers a self-serve data copy tool directly in the Dashboard. ### What Can Be Copied 1. Customer Data 1. Includes names, billing information, and metadata. 2. Customer IDs remain unchanged. 2. Payment Methods 1. Cards, bank accounts, ACH, etc. 2. These receive new Stripe object IDs, but Stripe provides a CSV mapping between old and new IDs. Follow the resources here for more information: 1. [Stripe Docs: Data Migration ](https://docs.stripe.com/get-started/data-migrations/pan-copy-self-serve) 2. [Stripe Support Article](https://support.stripe.com/questions/data-that-can-be-copied-between-stripe-accounts) > 📘 Check out these helpful articles for more information on our blog > > * [The Pelcro Blog](https://blog.pelcro.com/) > * [How to Migrate from Piano Go](https://blog.pelcro.com/how-to-migrate-from-piano-go/) > * [Switching From Legacy Systems to a Modern Subscription Platform](https://blog.pelcro.com/switching-legacy-systems-modern-subscription-platform/) # Sibling pages * [Overview](https://docs.pelcro.com/v2.4/docs/overview.md) * [Setting Up ](https://docs.pelcro.com/v2.4/docs/setting-up.md) * [Preparing Your Team](https://docs.pelcro.com/v2.4/docs/preparing-your-team.md) * [Going Live](https://docs.pelcro.com/v2.4/docs/going-live.md)