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",
            "multi_item_bundle_components": [
                {
                    "product": "44284019474619",
                    "quantity": 2
                },
                {
                    "product": "44284019343547",
                    "quantity": 1
                }
            ],
            "currency_code": "USD",
            "rotation_ordinal": 0,
            "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,
            "currency_code": "USD",
            "rotation_ordinal": 1,
        "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

FieldRequiredFormatNotes
merchantYstringString. Your program's unique ID within Ordergroove
merchant_user_idYstringString. The customer ID in the e-commerce platform you've installed Ordergroove on. We use this to identify your subscriber in that system
email-stringUsed to send transactional emails. Check your settings to see if this is required
first_name-string
last_name-string
liveYbooleanIndicates if a customer has been manually deactivated
phone_numberNstring

Format: E.164
createdNstring

Format: YYYY-MM-DD HH:MM:SS
extra_dataNJSON as stringUsed in rare cases, can be ignored
originYobjectIdentifiers from the platform(s) you're migrating from

Fields For the Customer Origin Component

FieldRequiredFormatNotes
IDYstringThe ID of the customer you will use in other origin objects to refer to this customer

Fields For Each Subscription

FieldRequiredFormatNotes
customerYstringThe 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_dateNstringThe 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
cancelledNstringThe date when the subscription was most recently cancelled
next_order_dateNstringWhen 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.
liveYbooleanWhether or not the subscription is active.
For 'Paused' subscriptions please use false.
merchant_order_idYstringThe 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.
productYstringThe 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.
everyYintegerHow often, in frequency periods, to send the subscription item. For example, if a subscription comes every four weeks this field would be "4"
every_periodYstringThe frequency period to use when calculating the next order. Options: day, week, month

For example, if a subscription comes every four weeks this field would be "week"
priceYstringCan be set to null, or you may provide a price. Keep in mind however that the key is required.
quantityYintegerHow many pieces of the product the subscriber has subscribed to for each order
offerYstringThis will be provided to you when your account is created. It identifies the incentive profile for this subscription.
shipping_addressYstringThe address to which the subscription will be shipped.
extra_dataNJSON as stringUsed in rare cases, can be ignored.
componentsNobjectIf 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_codeNstringThe three letter ISO 4217 currency code of the subscription.
rotation_ordinalNintegerAn integer value greater than or equal to 0 used to determine the current progress of the rotating ordinal subscription.
originYobjectIdentifiers from the platform(s) you're migrating from.

Prepaid subscription fields

Prepaid subscriptions have an additional field:

  • prepaid_subscription_context - A JSON object that contains information about prepaid subscriptions. Required if the subscription is prepaid.

This is an object containing information about prepaid subscriptions, and is only required if the subscription is prepaid. To use this field, you must have the prepaid feature flag enabled by Ordergroove. Otherwise, you will get errors during the migration process.

Example:

{
 // other migration fields
 "subscriptions": [
   {
    // other subscription fields
    "prepaid_subscription_context": {
     "prepaid_orders_remaining": 3,
     "prepaid_orders_per_billing": 6,
     "renewal_behavior": "autorenew"
    }
  }
 ]
}

There are three properties, all three are required. If errors are present, they will be returned in the error property of the subscription.

PropertyTypeNotes
prepaid_orders_per_billingintegerThe number of orders the customer prepays for at once. Must be an integer greater than 1.
prepaid_orders_remainingintegerHow many prepaid orders are left in the current billing cycle. Must be a positive integer or 0.
renewal_behaviorstringWhat should happen at the end of a prepaid billing cycle. A strong with values:

- 'autorenew' - after all prepaid orders have been placed, the next order will charge the customer for another prepaid_orders_per_billing orders
- 'cancel' - the subscription will be canceled
- 'downgrade' - the subscription will be downgraded to a pay-as-you-go subscription

Fields For Each Subscription Component of a Legacy Bundle

FieldRequiredFormatNotes
productYstringThe 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

FieldRequiredFormatNotes
IDYstringThe 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.
paymentYstringThe 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_addressYstringThe 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

FieldRequiredFormatNotes
customerYstringThe 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-stringName 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-stringOptions:
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-stringIf 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_idYstringEither:

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
liveYbooleanIf the payment method is still active and usable by the customer
originYobjectIdentifiers from the platform(s) you're migrating from

Fields For Each Payment Method > Origin Component

FieldRequiredFormatNotes
IDYstringThe 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_addressYstringThe 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_processorNstringInformation on payment processor being migrated

Fields For Each Payment Method > Origin > Payment Processor Component

FieldRequiredFormatNotes
typeNstringOptions: PayPal, Stripe

Required when migrating to Shopify Payment
dataNstringData specific to the type of payment process

Fields For Each Payment Method > Origin > Payment Processor > Data (Stripe Type)

FieldRequiredFormatNotes
token_idNstringThe 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)

FieldRequiredFormatNotes
token_idNstringThe 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

FieldRequiredFormatNotes
IDYstringThe 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.

Migrating to Shopify & Shopify Payments

If needed, the Ordergroove migration system can import certain types of payment methods into Shopify Payments. Please reach out to Ordergroove for your specific payment migration needs. The following example is a record for migrating a Stripe payment to Shopify Payments when using the Stripe Legacy Gateway feature on Shopify:

{
  ...
  "payments": [
     {
        "customer": "11112222334455",
        "live": true,
        "token_id": "cus_ABCDEFG1234567",
        "billing_address": null,
        "public_id": null,
        "cc_number": "1111",
        "label": null,
        "cc_holder": null,
        "cc_type": 2,
        "cc_exp_date": "12/2030",
        "payment_method": "credit card",
        "created": null,
        "last_updated": null,
        "origin": {
          "id": "payment-0",
          "billing_address": "billing-0",
          "payment_processor": {
            "type": "stripe",
            "data": {
              "token": "cus_ABCDEFG1234567",              "stripe_payment_method_id": "..."
            }
          }
        }
     },
     ...
  ]
}

The origin object provides a “payment_processor” field which is where you can populate the data necessary to migrate your customer’s payment Shopify Payments. Here are the different payment types supported and their accompanying field requirements:

Stripe

{   ...  "payment_processor": {
    "type": "stripe",
    "data": {
        "token": "STRIPE_CUSTOMER_TOKEN",
        "stripe_payment_method_id": "..." // Optional, but recommended to specify
    }  }
}

Paypal

{
  ...
  "token_id": "PAYPAL_BILLING_AGREEMENT_ID", 
  "payment_method": "paypal",
  ...
  "origin": {
    ...
    "payment_processor": {
      "type": "paypal",
      "data": {
        "token": "PAYPAL_BILLING_AGREEMENT_ID"
      }
    }
  }
}

Auth.net

Note: Auth.net as a legacy subscription payment gateway is currently supported as a beta feature by Shopify. To use this feature, enable the legacy_subscriptions_authnet beta flag in your store. Please see this article for additional detail: https://shopify.dev/apps/subscriptions/migrate/customers#migrating-from-authorize-net

{   ...  "payment_processor": {
    "type": "authorize",
    "data": {
        "token": "AUTH_NET_CUSTOMER_TOKEN",
        "customer_payment_profile_id": "..." // Optional, but recommended to specify
    	}   
	} 
}

Braintree

Note: Braintree as a legacy subscription payment gateway is currently supported as a beta feature by Shopify. To use this feature, enable the legacy_subscriptions_braintree beta flag in your store. Please see this article for additional detail: https://shopify.dev/apps/subscriptions/migrate/customers#migrating-from-braintree

{
  ...
  "payment_processor": {
    "type": "braintree",
    "data": {
      "token": "BT_CUSTOMER_TOKEN",
      "payment_method_token": "BT_PAYMENT_METHOD_TOKEN"
    }
  }
}

Updated about 1 month ago