Prepare Data

Prior to attempting a migration the following are essential steps to ensure data are ready. Skipping these steps may result in missing or incomplete order information post-migration.

Minimal order example

The following example is intended to show the absolute minimum amount of information you can provide when creating orders in order to migrate your data smoothly, efficiently, and without undue data collisions.

{
  "external_source": "M-MIG",
  "external_order_id": "AB123456",
  "status_id": 0,
  "date_created": "Tue, 20 Nov 2012 00:00:00 +0000",
  "customer_message": "Thank you",
  "staff_notes": "Ship sunday",
  "total_ex_tax": "23.74",
  "total_inc_tax": "25.61",
  "billing_address": {
      /*... billing address info ...*/
  },
  "products": [
      /*... product data objects ...*/
  ],
}

The other fields that should be included depend on the complexity of your migration and should be added as necessary depending on your needs.

In the remaining sections, all order data mapping is covered in detail to allow a full and complete picture of the process. Your needs will vary depending on the complexity of your migration, customer data, and catalog.

Product data links

It’s assumed that you have already transferred your products following the instructions in Product Migration. During that process, you should have ensured that your products have the BigCommerce product_id attached so that order information is able to attach the correct products within BigCommerce. For products that have variations or modifications that might change the inventory tracking or other relevant data access, the appropriate variant_id, modifier_id, and sku information should be attached to relevant product data within your orders.

As covered in the fields outline from the product migration page, these fields may be labelled differently depending on the specific API endpoint used to access them during product migration. As such, it’s essential that you label the fields clearly in your data source with respect to the data they belong to.

Other product-level fields to map include product_name, variant_name, and the various *_price fields on the product. These should have a uniform name between both source and destination data, since their names are specific enough to make clear what field they reference.

For custom products — those defined by you when creating an order or those no longer in your catalog — the only necessary fields are name, quantity, price_inc_tax, and price_ex_tax. Other data may be included as necessary, but the data structure is different. See Create an Order for more information.

The following is an example of the product data structure for orders:

{
  /*... other order fields ...*/
  "products": [
    {
      /*... Custom Product ...*/
      "name": "Custom Product Name",
      "quantity": 1,
      "price_inc_tax": 10.98,
      "price_ex_tax": 10
    },
    {
      /*... Product with Variants ...*/
      "product_id": 118,
      "quantity": 1,
      "variant_id": 93
    },
    {
      /*... Product with Modifiers ...*/
      "product_id": 184,
      "product_options": [
        {
          "id": 200,
          "value": "180"
        },
        {
          "id": 230,
          "value": "192"
        }
      ]
    },
    {
      /*... Product with Variants and Modifiers ...*/
      "product_id": 184,
      "variant_id": 93
      "product_options": [
        {
          "id": 200,
          "value": "180"
        },
        {
          "id": 230,
          "value": "Custom Text"
        }
      ]
    }
  ]
  /*... other order fields ...*/
}

Customer data links

Unlike product data, customer data has much more straightforward fields to connect between your data source and BigCommerce. Specifically, customer data requires customer_id and address information. Beyond that, mapping is fairly straightforward.

Regardless of the specific structure used, the following example billing_address is the basis for all address options:

{
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "Company name",
    "street_1": "123 Main Street",
    "street_2": "Suite B",
    "city": "Austin",
    "state": "TX",
    "zip": "12345",
    "country": "United States",
    "country_iso2": "US",
    "phone": "987654321",
    "email": "example@example.com"
  }
}

There are two important callouts about the example above. First, the zip field is required within the billing address, as it is a mandatory field for most payment processors. It must be at least two characters and a valid postal code for the country. Second, shipping addresses optionally include a shipping_method field, which identifies the method by which the customer requested shipment. It can be any of your store’s enabled shipping methods.

When mapping customer data, there are five main cases to prepare for, as outlined in Complexity Considerations. Even so, they fall back on one of two main structures so far as mapping customer data.

Orders with consignments

Orders with consignments are treated as, essentially, pickup orders. All product data is paired directly with the relevant address data. In the default use-case, this address data is meant to pair with specific locations of your business and specific ‘pickup’ methods.

An example of this structure is outlined below.

{
  /*... other order fields ...*/
  "customer_id": 11,
  "billing_address": {
    /*... billing address fields ...*/
  },
  "consignments": {
    "pickups": [
      {
        "pickup_method_id":1,
        "pickup_method_display_name": "Pick Up",
        "collection_instructions": "Bring your ID",
        "collection_time_description": "9am - 6pm",
        "location": {
          /* location fields use a different structure */
          "name": "Location 1",
          "code": "LOCATION-1",
          "address_line_1": "123 Main Street",
          "address_line_2": "Suite 101",
          "city":"Austin",
          "state":"Texas",
          "postal_code":"78726",
          "country_alpha2":"US",
          "email":"location1@example.com",
          "phone":"+1 111-111-1111"
        },
		"line_items": [
          /*... product data ...*/
        ]
      }
    ]
  }
  /*... other order fields ...*/
}

The fields listed in this example may or may not align with your expected structure. Verify ahead that your fields follow the appropriate structure to use this data type.

Orders without consignments

Rather than using an order with consignments, order data may be split with product data in one array and shipping addresses in another, both of which are collections of objects of their specific data types. In this case, there is no direct mapping between products and the addresses to which they are shipped. As such, only older order data should be imported via this method.

An example of this structure is outlined below.

{
  /*... other order fields ...*/
  "customer_id": 11,
  "billing_address": {
    /*... billing address fields ...*/
  },
  "shipping_addresses": [
    {
      /*... other address fields ...*/
      "shipping_method": "UPS"
    }
  ],
  "products": [
    /*... product data ...*/
  ]
  /*... other order fields ...*/
}

All order data fields

Once product- and customer-specific data have been mapped properly, there are many other fields to manage in mapping. The table below contains all order fields (including for customer and product data) by name, including their data types, descriptions, and examples where possible.

FAQs

Resources

• Product API Field Reference
• Orders API - Create an Order
• Order Complexity Considerations
• API Best Practices