All Collections
Push items from Heartland Retail to BigCommerce
Push items from Heartland Retail to BigCommerce

How to send item catalog information from Heartland Retail to BigCommerce

Brian Curtis avatar
Written by Brian Curtis
Updated over a week ago

Please note: This is a beta feature. If you would like to complete a push sync in Heartland Retail to BigCommerce, please reach out to

Push Sync is a powerful feature that lets you send item information from Heartland Retail to BigCommerce. In this guide, you’ll find out how to set up, use, and troubleshoot BigCommerce Push Sync.

First, you’ll need to have an active BigCommerce connection in your Heartland Retail account. Follow this article if you haven’t set that up yet.

Enabling Push Sync

To enable Push Sync, navigate to the Items Information tab of the BigCommerce connection you’re using (Settings >> Integrations >> BigCommerce >> Manage). At the top, select Push item information from Heartland Retail to BigCommerce, as shown below.

Important: Push Sync is not an ongoing process. You'll need to initiate a sync each time you want to send item information from Heartland Retail to BigCommerce.

Selecting items to sync

Next, select which items you’d like to sync to BigCommerce. You can sync all your items, or use filters to sync only a subset. The filtering tool works just like it does everywhere else in Heartland Retail with one exception: Push Sync assumes you only want to send active items, so it will always ignore inactive ones.

Best Practice: The easiest way to set up this filter is by using a custom field that specifies whether an item should be sold online. For instance, name a field Sold on web? and filter for items where that value = true

Next, choose whether to sync only new items, or update existing ones on BigCommerce.
(Careful! This setting can overwrite existing information on BigCommerce.)

Next, choose whether you want to sync items with no images. You can also choose whether to sync individual items or only those that belong to a grid. Then select whether the synced items should immediately appear as visible on your customer-facing BigCommerce website. 

Mapping information from items and grids

Now you’re ready to map your item information. Before you start with the settings on the BigCommerce integration page, let’s look at some fields that always map the same way.

As seen above, the following field mappings are consistent and cannot be changed:

  • Heartland Retail Description >> BigCommerce Product Name

  • Heartland Retail Long Description >> BigCommerce Description
    (Note: Only the grid's Long Description will sync to BigCommerce.)

  • Heartland Retail Current Price >> BigCommerce Price
    (Note: Although BigCommerce allows you to create a product with a price of zero in their front-end interface, they do not allow you to import one using their API. Thus, all items push synced from Heartland Retail must have a positive value for price.)

  • Heartland Retail Default Cost >> BigCommerce Cost Price

Best Practice: Review your Heartland Retail item catalog in a spreadsheet to be sure all the information is correct before attempting Push Sync. For example, make sure your descriptions are optimized for customer-facing uses rather than inventory control!

When a push sync in Heartland Retail is completed, the following fields in Big Commerce will be updated : name, cost_price, description, price, categories, tax_class, brand, weight, width, height, depth, type, is_visible, sku, upc, images, inventory_tracking, and modifiers. The push will not update fields in BC such as Search Keywords. 

Syncing items with variants (Grids)

Best Practice: If you are an apparel or footwear retailer, it's important that you grid your items in Heartland Retail before pushing items to BigCommerce. Otherwise, the items will not appear together on BigCommerce.

If you want to display products with variants such as size and color on your BigCommerce website, you’ll need to set those up as grids in Heartland Retail. If you have a lot of items that need to be gridded, you may want to consider our auto-gridding service. When you sync a grid, the grid Description will map to BigCommerce as the Product Name, and each dimension will result in product options on BigCommerce.

Important: When you sync a grid, only the Long Description from the grid will push to BigCommerce. So if the gridded items have Long Description populated, but the grid itself does not, nothing will push to BigCommerce.

Now that you’ve prepared your item catalog’s fixed fields, it’s time to consider the options available for mapping.


All BigCommerce products require a weight. All items that do not already have a weight specified will sync with the value in this field. 

If you’d like to set weights for your items individually, you can do that in the Measurements tab of each item’s record, as shown below.


Choose which field will map to BigCommerce category. If no field is mapped here, any newly synced items will appear in the category “Uncategorized Heartland Retail Items”. 

Important: When syncing a grid, be sure to fill in your category field at the grid level. If your gridded items have category information but the grid itself does not, the items will be synced as Uncategorized Heartland Retail Items.

Assigning multiple categories
You may want to assign an item to more than one BigCommerce category or take advantage of nested sub-categories, in which case you’ll need to use a very specific syntax. First, create a custom field on Heartland Retail to hold the data. We suggest a name like BigCommerceCategories that makes the purpose of the field clear. You’ll then need to populate the field using the following syntax:


To assign an item to multiple top-level categories, separate each one with a semicolon (;):


If an item has multiple levels of sub-category, separate those with a forward slash (/):

Category;Category/Sub-category/Tertiary Category

For a realistic example, this category syntax ... Shop All;Apparel;Apparel/Dresses

… maps to this in in BigCommerce:

Important: Push Sync will not create new categories on BigCommerce. All categories and hierarchies must exist prior to the sync attempt and exactly match the information sent by Heartland Retail.

If any category information in Heartland Retail does not match what’s in your BigCommerce account, that item will fail to sync with the error “Invalid category”.

Tax Class

All BigCommerce items require a Tax Class, and you can map that to a Heartland Retail field if you want to designate this at the item level. If you don’t map this field, your synced items will be set to “Default Tax Class” on BigCommerce.

Brand Name

You can map any item field in Heartland Retail to the Brand Name attribute in BigCommerce. The obvious choice is Primary Vendor, but keep in mind that the BigCommerce Brand Name is customer-facing and will appear on your website exactly as it does in Heartland Retail. So if your vendor is listed in Heartland Retail as ACME WIDGETS N.A. INC, but your customers think of it as Acme, you may want to create a specific Brand field in Heartland Retail to hold that information.


If you have designated a field for UPC or another alternate lookup in Heartland Retail, you can map it to the UPC/EAN attribute in BigCommerce.

How Updates Work

When you sync an item that has previously synced, you can also control whether certain attributes are updated or left alone on BigCommerce. 

Item Name, Description, Cost, Price: These attributes are not optional and will always overwrite the information present on BigCommerce.

Weight: Any item with a blank weight attribute will be synced with the default value specified on your Push Sync settings page and will overwrite current info on BigCommerce. If you want to set the weights of your items individually, you should do this on Heartland Retail.

Category: If you map this field, the push sync will overwrite existing information on BigCommerce. If you do not map this field, push sync will add un-synced items to the category “Uncategorized Heartland Retail Items” and leave items with existing category information unchanged.
If you want to put items in multiple categories, but do not want to use the import syntax described above, another option is to sync the items with no category and then assign categories using the BigCommerce interface. In this case, you should not map the category field during sync to avoid overwriting existing information.


All item images uploaded to the product profile in Heartland Retail will sync to BC. Images uploaded to the grid "All Images" section in Heartland Retail will link to the "Images and Videos" section of the product profile on BC. This will be the first images that are displayed to the customer on the website. Any images uploaded to the Heartland Retail dimension level on the grid will appear in the product options on BC.

Note: Only the primary image per each SKU will be stored and shown by BigCommerce when a variance color and size is selected. For example, this means once a product color and size are selected on BC, only the primary image attached to the variance will be displayed to the customer. This is currently a restriction with the capabilities of the BC website.

Starting the Sync

Now that you’ve mapped all your attributes, you’re ready to start your Push Sync. Simply push the Push items to BigCommerce button. 

The sync process itself can take a considerable amount of time, especially the first time it runs. Plan on waiting several hours, or even a couple days, for a large item catalog.

Once the sync completes, you will see the following screen, including the number of total items attempted, the number successfully synced, and the number that did not sync because of errors. To find out what caused the errors, click Download errors to csv.

Important: Be sure you download your errors file before you press OK!

Did this answer your question?