1. Ordergroove Knowledge Center
  2. Migrations
  3. Managed Migrations

Migration File Example

Updated

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": "sam.smith@ordergroove.com",
        "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

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.
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
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: day, week, month

For example, if a subscription comes every four weeks this field would be "week"
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 Integrationcheck 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.

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.

Property Type Notes
prepaid_orders_per_billing integer The number of orders the customer prepays for at once. Must be an integer greater than 1.
prepaid_orders_remaining integer How many prepaid orders are left in the current billing cycle. Must be a positive integer or 0.
renewal_behavior string

What 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

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.
created N string Format: YYYY-MM-DD HH:MM:SS
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 tokenTo 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.

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": "..."
    }  }
}

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"
    }
  }
}