Guides

Migrate my data to Ordergroove

Suggest Edits

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

email

* 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.
For 'Paused' subscriptions please use false.

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.

Please also check the requirements of your e-commerce store. If this field is 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.

cc_type

*

string

Options:
Visa: 1
MasterCard: 2
American Express: 3
Discover: 4
Diners: 5
JCB: 6

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.

Please also check the requirements of your e-commerce store. If this field is 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.

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.

Please also check the requirements of your e-commerce store. If this field is 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.

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

Deprecated PayPal Docs

Braintree Docs

 

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

Validation

zip_code

*

string

country

*

Validation

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 2 months ago