Migrate my data to Ordergroove
Ordergroove uses newline delimited JSON file where each customer's data is its own JSON object on its own line. Use one line per customer. Addresses and payments and subscriptions are connected using their IDs in the origin object.
Example: Single Customer JSON Object
You need to create the below object for each customer and put each object on a new line in a file:
{
"customer": {
"merchant" : "n83hg5fm7d82345f727dk203",
"merchant_user_id": "2398573030",
"first_name": "Sam",
"last_name": "Smith",
"email": "[email protected]",
"live": true,
"phone_number": null,
"extra_data": null,
"price_code": null,
"created": "2021-02-26 18:15:07",
"origin": {
"id": 3452345784
}
},
"addresses": [
{
"customer": "2398573030",
"address_type": "billing_address",
"first_name": "Sam",
"last_name": "Smith",
"address": "1 Fifth Ave",
"city": "New York",
"state_province_code": "NY",
"zip_postal_code": "10003",
"country_code": "US",
"live": true,
"phone": "555-123-4567",
"origin": {
"id": 3452277044
}
},
{
"customer": "2398573030",
"address_type": "shipping_address",
"first_name": "Sam",
"last_name": "Smith",
"address": "1 Fifth Ave",
"city": "New York",
"state_province_code": "NY",
"zip_postal_code": "10003",
"country_code": "US",
"live": true,
"phone": "555-123-4567",
"origin": {
"id": 61377044
}
}
],
"payments": [
{
"customer": "2398573030",
"live": true,
"token_id": "274573947",
"cc_holder": "Sam Smith",
"cc_type": 2,
"cc_exp_date": "09/2022",
"created": "2021-02-26 18:15:07",
"origin": {
"id": 567563456,
"billing_address": 3452277044
}
}
],
"subscriptions": [
{
"customer": "2398573030",
"product": "3g2375g385",
"offer": "b6b8cf7c52346234652342b6aba89ec1ea9",
"merchant_order_id": "18076256",
"live": true,
"every": 4,
"every_period": "week",
"quantity": 1,
"price": "18.99",
"start_date": "2020-07-21",
"cancelled": null,
"next_order_date": "2021-03-21",
"components": null,
"currency_code": "USD",
"origin": {
"id": 56723446,
"payment": 567563456,
"shipping_address": 61377044
}
},
{
"customer": "2398573030",
"product": "09832ng9739",
"offer": "b6b8cf7c52346234652342b6aba89ec1ea9",
"merchant_order_id": "18076256",
"live": false,
"every": 3,
"every_period": "month",
"quantity": 1,
"price": "48.99",
"start_date": "2020-07-21",
"cancelled": "2020-09-21 10:21:56",
"next_order_date": null,
"components": [
"323453434",
"j45235432",
"867g30481"
],
"currency_code": "USD",
"origin": {
"id": 2435764567,
"payment": 567563456,
"shipping_address": 61377044
}
}
]
}
Migration file fields
Below you'll find information about the data you'll need to populate the migration file.
Optional Fields
Fields marked with a * may be required during your migration. Please reach out to Ordergroove to confirm which fields are required for your subscription program.
Fields For Each Customer
Field |
Required |
Format |
Notes |
merchant |
Y |
string |
String. Your program's unique ID within Ordergroove |
merchant_user_id |
Y |
string |
String. The customer ID in the e-commerce platform you've installed Ordergroove on. We use this to identify your subscriber in that system |
|
* |
string
|
Used to send transactional emails. Check your settings to see if this is required |
first_name |
* |
string |
|
last_name |
* |
string |
|
live |
Y |
boolean |
Indicates if a customer has been manually deactivated |
phone_number |
N |
string Format: E.164 |
|
created |
N |
string Format: YYYY-MM-DD HH:MM:SS |
|
extra_data |
N |
JSON as string |
Used in rare cases, can be ignored |
origin |
Y |
object |
Identifiers from the platform(s) you're migrating from |
Fields For The Customer Origin Component
Field |
Required |
Format |
Notes |
ID |
Y |
string |
The ID of the customer you will use in other origin objects to refer to this customer |
Fields For Each Subscription
Field |
Required |
Format |
Notes |
customer |
Y |
string |
The customer ID in the e-commerce platform you've installed Ordergroove on. We use this to identify your subscriber in that system. [merchant_user_id] |
start_date |
N |
string |
The date when the subscription was created or the date it was most recently reactivated after having been cancelled. Format: YYYY-MM-DD HH:MM:SS |
cancelled |
N |
string |
The date when the subscription was most recently cancelled |
next_order_date |
N |
string |
When we import this subscription this will be the date on which we create its next order. Format: YYYY-MM-DD HH:MM:SS Note: If the migrated date is in the past, Ordergroove will update it to the next date orders can be placed. This is usually tomorrow. |
live |
Y |
boolean |
Whether or not the subscription is active. |
merchant_order_id |
Y |
string |
The ID of the e-commerce order with which the subscription was originally created (when they enrolled). This will be used to ensure accuracy and avoid duplicate subscriptions. |
product |
Y |
string |
The ID of the product in your e-commerce system. Before you start the migration, this product's information must be included in the recurring product feed sent to Ordergroove. This is how we will identify the subscription product when placing orders. |
every |
Y |
integer |
How often, in frequency periods, to send the subscription item. For example, if a subscription comes every four weeks this field would be "4" |
every_period |
Y |
string |
The frequency period to use when calculating the next order. Options: Days, Weeks, Months For example, if a subscription comes every four weeks this field would be "Weeks" |
price |
Y |
string |
Can be set to null, or you may provide a price. Keep in mind however that the key is required. |
quantity |
Y |
integer |
How many pieces of the product the subscriber has subscribed to for each order |
offer |
Y |
string |
This will be provided to you when your account is created. It identifies the incentive profile for this subscription. |
shipping_address |
Y |
string |
The address to which the subscription will be shipped |
extra_data |
N |
JSON as string |
Used in rare cases, can be ignored. |
components |
N |
object |
If the subscription is a bundle, include the data for each component product to migrate to the Legacy Bundle integration. See below for more information on the old integration. To migrate to the New Bundles Integration check this section |
currency_code |
N |
string |
The three letter ISO 4217 currency code of the subscription. |
rotation_ordinal |
N |
integer |
An integer value greater than or equal to 0 used to determine the current progress of the rotating ordinal subscription. |
origin |
Y |
object |
Identifiers from the platform(s) you're migrating from |
Fields For Each Subscription Component of a Legacy Bundle
Field |
Required |
Format |
Notes |
product |
Y |
string |
The ID of the product in your e-commerce system. Before you start the migration this product's information must be included in the recurring product feed sent to Ordergroove. This is how we will identify the subscription's component products when placing orders. |
Fields For Each Subscription Origin Component
Field |
Required |
Format |
Notes |
ID |
Y |
string |
The ID you'll use to identify this address in the rest of this customer's JSON object. It can be the ID of the address in your e-commerce system, subscription platform, or something you generate for migration. |
payment |
Y |
string |
The ID of the payment method for this subscription. This should be the same as the origin ID provided for this payment method in this JSON object. |
shipping_address |
Y |
string |
The ID of the shipping address for this subscription. This should be the same as the origin ID provided for this shipping address in this JSON object. |
Fields For Each Payment Method
Field |
Required |
Format |
Notes |
customer |
Y |
string |
The customer ID in the e-commerce platform you've installed Ordergroove on. We use this to identify your subscriber in that system. [merchant_user_id] |
cc_holder |
* |
string |
Name of the credit cardholder. If you're unable to access this data you can turn it off as required for the migration and back on if desired.
Check your settings
to see if required by your Ordergroove program. |
cc_type |
* |
string |
Options: If you're unable to access this data you can turn it off as required for the migration and back on if desired however please note subscribers will not see this with their subscription payment information.
Check your settings
to see if required by your Ordergroove program. |
cc_exp_date |
* |
string |
If you're unable to access this data you can turn it off as required for the migration and back on if desired however please note subscribers will not see this with their subscription payment information. In addition, we will not be able to. Format: MM/YYYY
Check your settings
to see if required by your Ordergroove program. |
token_id |
Y |
string |
Either: 1. The credit card token used when placing orders for this subscription 2. A unique identifier used by your e-commerce system to charge the subscriber (such as a customer ID). For BigCommerce send the customer ID as the token To migrate to Shopify payments leave this blank and continue to the origin components below |
live | Y | boolean |
If the payment method is still active and usable by the customer |
origin | Y | object |
Identifiers from the platform(s) you're migrating from |
Fields For Each Payment Method > Origin Component
Field |
Required |
Format |
Notes |
ID |
Y |
string |
The ID you'll use to identify this payment method in the rest of this customer's JSON object. It can be the ID of the payment method in your e-commerce system, a subscription platform, or something you generate for migration. |
billing_address |
Y |
string |
The ID of the billing address for this subscription. This should be the same as the origin ID provided for this billing address in this JSON object. |
payment_processor |
N |
string |
Information on payment processor being migrated |
Fields For Each Payment Method > Origin > Payment Processor Component
Field |
Required |
Format |
Notes |
type |
N |
string |
Options: PayPal, Stripe Required when migrating to Shopify Payment |
data |
N |
string |
Data specific to the type of payment process |
Fields For Each Payment Method > Origin > Payment Processor > Data (Stripe Type)
Field |
Required |
Format |
Notes |
token_id |
N |
string |
The Stripe token to be migrated. Please provide the Customer Profile ID only. For example: cus_abc123 |
Fields For Each Payment Method > Origin > Payment Processor > Data
(PayPal Type)
Field |
Required |
Format |
Notes |
token_id |
N |
string |
The PayPal billing agreement ID to be migrated |
Fields For Each Shipping or Billing Addresses
Field |
Required |
Format |
Notes |
customer |
Y |
string |
The customer ID in the e-commerce platform you've installed Ordergroove on. We use this to identify your subscriber in that system. [merchant_user_id] |
address_type |
Y |
string Options: billing_address, shipping_address |
|
first_name |
* |
string |
Check with Ordergroove to see if these fields are required by your subscription program.
Please also check the requirements of your e-commerce store. If any of these fields are required outside of Ordergroove but not present in the data you migrate it could cause errors during the import or orders not to place down the line. |
last_name |
* |
string |
|
company |
* |
string |
|
address |
* |
string |
|
address2 |
* | string | |
city |
* |
string |
|
state |
* |
string |
|
zip_code |
* |
string |
|
country |
* |
||
phone |
* |
string Format: E.164 |
|
live |
Y |
boolean |
Whether or not this address is still active and usable by the customer |
origin |
Y |
object |
Identifiers from the platform(s) you're migrating from |
Fields For Each Address Origin Component
Field |
Required |
Format |
Notes |
ID |
Y |
string |
The ID you'll use to identify this address in the rest of this customer's JSON object. It can be the ID of the address in your e-commerce system, subscription platform, or something you generate for migration. |
Updated about 1 month ago