> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ordergroove.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ordergroove.com/_mcp/server. # Migrate data to Ordergroove 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: ```json { "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 `*` 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 | Your program's unique ID within Ordergroove | | `merchant_user_id` | Y | string | The customer ID in the eCommerce platform you've installed Ordergroove on. Used 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](https://en.wikipedia.org/wiki/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 eCommerce platform (`merchant_user_id`). Used to identify your subscriber in that system. | | `start_date` | N | string | The date when the subscription was created or most recently reactivated after being 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 (usually tomorrow). | | `live` | Y | boolean | Whether or not the subscription is active. For paused subscriptions, use `false`. | | `merchant_order_id` | Y | string | The ID of the eCommerce order with which the subscription was originally created. Used to ensure accuracy and avoid duplicate subscriptions. | | `product` | Y | string | The 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](https://developer.ordergroove.com/docs/integrating-with-a-custom-platform) sent to Ordergroove. | | `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 used 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. The key is required. | | `quantity` | Y | integer | How many pieces of the product the subscriber has subscribed to for each order | | `offer` | Y | string | Provided when your account is created. 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. **To migrate to the New Bundles Integration, [check this section](https://help.ordergroove.com/hc/en-us/articles/6351678016403-View-migration-file-structure-information#h_01HCHXBYBFN2BGSD8KB55PRVQK).** | | `currency_code` | N | string | The three-letter ISO 4217 currency code of the subscription. | | `rotation_ordinal` | N | integer | An integer value ≥ 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 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: ```json { "subscriptions": [ { "prepaid_subscription_context": { "prepaid_orders_remaining": 3, "prepaid_orders_per_billing": 6, "renewal_behavior": "autorenew" } } ] } ``` All three properties 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. 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 | Field | Required | Format | Notes | | :-------- | :------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `product` | Y | string | The 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](https://developer.ordergroove.com/docs/integrating-with-a-custom-platform) 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 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. | | `payment` | Y | string | The ID of the payment method for this subscription. This should match 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 match 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 eCommerce platform (`merchant_user_id`). Used to identify your subscriber in that system. | | `cc_holder` | \* | string | Name of the credit cardholder. [Check your settings](https://developer.ordergroove.com/hc/en-us/articles/360041560073-Order-Placement-Subscription-Creation-Validation-Settings#h_01EGP2Z1BAW6XXNVTZ20JADBPZ) 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` | \* | string | Options: `1` = Visa, `2` = MasterCard, `3` = American Express, `4` = Discover, `5` = Diners, `6` = JCB. [Check your settings](https://developer.ordergroove.com/hc/en-us/articles/360041560073-Order-Placement-Subscription-Creation-Validation-Settings#h_01EGP2Z1BAW6XXNVTZ20JADBPZ) to see if required. *Same caveat applies as above.* | | `cc_exp_date` | \* | string | Format: `MM/YYYY`. [Check your settings](https://developer.ordergroove.com/hc/en-us/articles/360041560073-Order-Placement-Subscription-Creation-Validation-Settings#h_01EGP2Z1BAW6XXNVTZ20JADBPZ) to see if required. *Same caveat applies as above.* | | `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, 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. | | `live` | Y | boolean | Whether 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 in your eCommerce system, subscription platform, or something you generate for migration. | | `billing_address` | Y | string | The ID of the billing address for this subscription. This should match the origin ID provided for this billing address in this JSON object. | | `payment_processor` | N | string | Information on the 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 Payments. | | `data` | N | string | Data specific to the type of payment processor | ## Fields For Each Payment Method > Origin > Payment Processor > Data (Stripe) | Field | Required | Format | Notes | | :--------- | :------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | `token_id` | N | string | The Stripe token to be migrated. Please provide the [Customer Profile ID](https://docs.stripe.com/api/customers) only. For example: `cus_abc123` | ## Fields For Each Payment Method > Origin > Payment Processor > Data (PayPal) | Field | Required | Format | Notes | | :--------- | :------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token_id` | N | string | The PayPal billing agreement ID to be migrated. See [Deprecated PayPal Docs](https://developer.paypal.com/docs/api/payments.billing-agreements/v1/) or [Braintree Docs](https://developer.paypal.com/braintree/docs/reference/response/paypal-account#billing_agreement_id). | *** ## 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. | Field | Required | Format | Notes | | :------------- | :------- | :------ | :--------------------------------------------------------------------------------------------------------------- | | `customer` | Y | string | The customer ID in the eCommerce platform (`merchant_user_id`). Used to identify your subscriber in that system. | | `address_type` | Y | string | Options: `billing_address`, `shipping_address` | | `first_name` | \* | string | | | `last_name` | \* | string | | | `company` | \* | string | | | `address` | \* | string | | | `address2` | \* | string | | | `city` | \* | string | | | `state` | \* | string | [Validation](https://static.ordergroove.com/@ordergroove/i18n-data/0.1.3/i18n_country_data.json) | | `zip_code` | \* | string | | | `country` | \* | string | [Validation](https://static.ordergroove.com/@ordergroove/i18n-data/0.1.3/i18n_country_data.json) | | `phone` | \* | string | Format: [E.164](https://en.wikipedia.org/wiki/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 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: ```json { "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 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 ```json { "payment_processor": { "type": "stripe", "data": { "token": "STRIPE_CUSTOMER_TOKEN", "stripe_payment_method_id": "..." } } } ``` ### PayPal ```json { "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. See [Shopify's migration docs](https://shopify.dev/apps/subscriptions/migrate/customers#migrating-from-authorize-net) for additional detail. ```json { "payment_processor": { "type": "authorize", "data": { "token": "AUTH_NET_CUSTOMER_TOKEN", "customer_payment_profile_id": "..." } } } ``` ### 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](https://shopify.dev/apps/subscriptions/migrate/customers#migrating-from-braintree) for additional detail. ```json { "payment_processor": { "type": "braintree", "data": { "token": "BT_CUSTOMER_TOKEN", "payment_method_token": "BT_PAYMENT_METHOD_TOKEN" } } } ```