Migrating to Ordergroove

Migrate data to Ordergroove

File format and field reference for migrating customers, subscriptions, payments, and addresses into Ordergroove
View as Markdown

Ordergroove uses a newline-delimited JSON file where each customer’s data is its own JSON object on its own line. Use one line per customer. Addresses, payments, and subscriptions are connected using their IDs in the origin object.

Example: Single Customer JSON Object

Create the below object for each customer and put each object on a new line in the file:

1{
2  "customer": {
3    "merchant": "n83hg5fm7d82345f727dk203",
4    "merchant_user_id": "2398573030",
5    "first_name": "Sam",
6    "last_name": "Smith",
7    "email": "sam.smith@ordergroove.com",
8    "live": true,
9    "phone_number": null,
10    "extra_data": null,
11    "price_code": null,
12    "created": "2021-02-26 18:15:07",
13    "origin": {
14      "id": "3452345784"
15    }
16  },
17  "addresses": [
18    {
19      "customer": "2398573030",
20      "address_type": "billing_address",
21      "first_name": "Sam",
22      "last_name": "Smith",
23      "address": "1 Fifth Ave",
24      "city": "New York",
25      "state_province_code": "NY",
26      "zip_postal_code": "10003",
27      "country_code": "US",
28      "live": true,
29      "phone": "555-123-4567",
30      "origin": {
31        "id": "3452277044"
32      }
33    },
34    {
35      "customer": "2398573030",
36      "address_type": "shipping_address",
37      "first_name": "Sam",
38      "last_name": "Smith",
39      "address": "1 Fifth Ave",
40      "city": "New York",
41      "state_province_code": "NY",
42      "zip_postal_code": "10003",
43      "country_code": "US",
44      "live": true,
45      "phone": "555-123-4567",
46      "origin": {
47        "id": "61377044"
48      }
49    }
50  ],
51  "payments": [
52    {
53      "customer": "2398573030",
54      "live": true,
55      "token_id": "274573947",
56      "cc_holder": "Sam Smith",
57      "cc_type": 2,
58      "cc_exp_date": "09/2022",
59      "created": "2021-02-26 18:15:07",
60      "origin": {
61        "id": "567563456",
62        "billing_address": "3452277044"
63      }
64    }
65  ],
66  "subscriptions": [
67    {
68      "customer": "2398573030",
69      "product": "3g2375g385",
70      "offer": "b6b8cf7c52346234652342b6aba89ec1ea9",
71      "merchant_order_id": "18076256",
72      "live": true,
73      "every": 4,
74      "every_period": "week",
75      "quantity": 1,
76      "price": "18.99",
77      "start_date": "2020-07-21",
78      "cancelled": null,
79      "next_order_date": "2021-03-21",
80      "multi_item_bundle_components": [
81        {
82          "product": "44284019474619",
83          "quantity": 2
84        },
85        {
86          "product": "44284019343547",
87          "quantity": 1
88        }
89      ],
90      "currency_code": "USD",
91      "rotation_ordinal": 0,
92      "origin": {
93        "id": "56723446",
94        "payment": "567563456",
95        "shipping_address": "61377044"
96      }
97    },
98    {
99      "customer": "2398573030",
100      "product": "09832ng9739",
101      "offer": "b6b8cf7c52346234652342b6aba89ec1ea9",
102      "merchant_order_id": "18076256",
103      "live": false,
104      "every": 3,
105      "every_period": "month",
106      "quantity": 1,
107      "price": "48.99",
108      "start_date": "2020-07-21",
109      "cancelled": "2020-09-21 10:21:56",
110      "next_order_date": null,
111      "currency_code": "USD",
112      "rotation_ordinal": 1,
113      "origin": {
114        "id": "2435764567",
115        "payment": "567563456",
116        "shipping_address": "61377044"
117      }
118    }
119  ]
120}

Migration File Fields

Below you’ll find information about the data you’ll need to populate the migration file.

Optional Fields

Fields marked with * 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
merchantYstringYour program’s unique ID within Ordergroove
merchant_user_idYstringThe customer ID in the eCommerce platform you’ve installed Ordergroove on. Used to identify your subscriber in that system.
email*stringUsed to send transactional emails.
first_name*string
last_name*string
liveYbooleanIndicates if a customer has been manually deactivated
phone_numberNstringFormat: E.164
createdNstringFormat: 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 eCommerce platform (merchant_user_id). Used to identify your subscriber in that system.
start_dateNstringThe date when the subscription was created or most recently reactivated after being cancelled. Format: YYYY-MM-DD
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 (usually tomorrow).
liveYbooleanWhether or not the subscription is active. For paused subscriptions, use false.
merchant_order_idYstringThe ID of the eCommerce order with which the subscription was originally created. Used to ensure accuracy and avoid duplicate subscriptions.
productYstringThe ID of the product in your eCommerce system. Before you start the migration, this product’s information must be included in the recurring product feed sent to Ordergroove.
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 used 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. The key is required.
quantityYintegerHow many pieces of the product the subscriber has subscribed to for each order
offerYstringProvided when your account is created. 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. 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 ≥ 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 containing information about prepaid subscriptions. 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:

1{
2  "subscriptions": [
3    {
4      "prepaid_subscription_context": {
5        "prepaid_orders_remaining": 3,
6        "prepaid_orders_per_billing": 6,
7        "renewal_behavior": "autorenew"
8      }
9    }
10  ]
11}

All three properties 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. Options: autorenew (charge the customer for another prepaid_orders_per_billing orders), cancel (cancel the subscription), downgrade (convert to a pay-as-you-go subscription).

Fields For Each Subscription Component of a Legacy Bundle

FieldRequiredFormatNotes
productYstringThe ID of the product in your eCommerce 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 subscription in the rest of this customer’s JSON object. It can be the ID of the subscription in your eCommerce system, subscription platform, or something you generate for migration.
paymentYstringThe ID of the payment method for this subscription. This should match the origin ID provided for this payment method in this JSON object.
shipping_addressYstringThe ID of the shipping address for this subscription. This should match the origin ID provided for this shipping address in this JSON object.

Fields For Each Payment Method

FieldRequiredFormatNotes
customerYstringThe customer ID in the eCommerce platform (merchant_user_id). Used to identify your subscriber in that system.
cc_holder*stringName of the credit cardholder. Check your settings to see if required by your Ordergroove program. Please also check the requirements of your eCommerce 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 prevent orders from placing.
cc_type*stringOptions: 1 = Visa, 2 = MasterCard, 3 = American Express, 4 = Discover, 5 = Diners, 6 = JCB. Check your settings to see if required. Same caveat applies as above.
cc_exp_date*stringFormat: MM/YYYY. Check your settings to see if required. Same caveat applies as above.
createdNstringFormat: YYYY-MM-DD HH:MM:SS
token_idYstringEither: (1) the credit card token used when placing orders for this subscription, or (2) a unique identifier used by your eCommerce system to charge the subscriber (e.g. 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.
liveYbooleanWhether 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 in your eCommerce system, subscription platform, or something you generate for migration.
billing_addressYstringThe ID of the billing address for this subscription. This should match the origin ID provided for this billing address in this JSON object.
payment_processorNstringInformation on the payment processor being migrated

Fields For Each Payment Method > Origin > Payment Processor Component

FieldRequiredFormatNotes
typeNstringOptions: PayPal, Stripe. Required when migrating to Shopify Payments.
dataNstringData specific to the type of payment processor

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

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)

FieldRequiredFormatNotes
token_idNstringThe PayPal billing agreement ID to be migrated. See Deprecated PayPal Docs or Braintree Docs.

Fields For Each Shipping or Billing Address

Fields marked with * in the Required column below should be confirmed with Ordergroove. Please also check the requirements of your eCommerce 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 prevent orders from placing.

FieldRequiredFormatNotes
customerYstringThe customer ID in the eCommerce platform (merchant_user_id). Used to identify your subscriber in that system.
address_typeYstringOptions: billing_address, shipping_address
first_name*string
last_name*string
company*string
address*string
address2*string
city*string
state*stringValidation
zip_code*string
country*stringValidation
phone*stringFormat: E.164
liveYbooleanWhether or not this address is still active and usable by the customer
originYobjectIdentifiers 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 eCommerce 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:

1{
2  "payments": [
3    {
4      "customer": "11112222334455",
5      "live": true,
6      "token_id": "cus_ABCDEFG1234567",
7      "billing_address": null,
8      "public_id": null,
9      "cc_number": "1111",
10      "label": null,
11      "cc_holder": null,
12      "cc_type": 2,
13      "cc_exp_date": "12/2030",
14      "payment_method": "credit card",
15      "created": null,
16      "last_updated": null,
17      "origin": {
18        "id": "payment-0",
19        "billing_address": "billing-0",
20        "payment_processor": {
21          "type": "stripe",
22          "data": {
23            "token": "cus_ABCDEFG1234567",
24            "stripe_payment_method_id": "..."
25          }
26        }
27      }
28    }
29  ]
30}

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

Stripe

1{
2  "payment_processor": {
3    "type": "stripe",
4    "data": {
5      "token": "STRIPE_CUSTOMER_TOKEN",
6      "stripe_payment_method_id": "..."
7    }
8  }
9}

PayPal

1{
2  "token_id": "PAYPAL_BILLING_AGREEMENT_ID",
3  "payment_method": "paypal",
4  "origin": {
5    "payment_processor": {
6      "type": "paypal",
7      "data": {
8        "token": "PAYPAL_BILLING_AGREEMENT_ID"
9      }
10    }
11  }
12}

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. See Shopify’s migration docs for additional detail.

1{
2  "payment_processor": {
3    "type": "authorize",
4    "data": {
5      "token": "AUTH_NET_CUSTOMER_TOKEN",
6      "customer_payment_profile_id": "..."
7    }
8  }
9}

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. See Shopify’s migration docs for additional detail.

1{
2  "payment_processor": {
3    "type": "braintree",
4    "data": {
5      "token": "BT_CUSTOMER_TOKEN",
6      "payment_method_token": "BT_PAYMENT_METHOD_TOKEN"
7    }
8  }
9}