Skip to main content

BigCommerce Products

Updated over 3 months ago

Background

Products in iPaaS.com, along with product categories and inventory can be transferred to and from BigCommerce based on the below mappings. It also supports Product Variants and their associated Product Options and Product Option Values. Kits are not currently supported.

Matching

Products (simple and variants) to/from BigCommerce are matched on SKU. Other product attributes are matched on external ID.

Transaction Custom Fields

BigCommerce Custom Fields

iPaaS.com supports BigCommerce custom fields in this data type.

iPaaS.com Custom Fields

Module

Name

Product Unit

Child Alternate Unit Barcode

Product Unit

Child Alternate Unit Default Price

Product Unit

Child Alternate Unit Denominator

Product Unit

Child Alternate Unit Include

Product Unit

Child Alternate Unit Name

Product Unit

Child Alternate Unit Numerator

Product Unit

Child Alternate Unit Sale Price

Product Unit

Parent Alternate Unit Barcode

Products TO iPaaS.com

Webhooks (External)

In order to enable Product data to flow TO iPaaS.com, the following external webhooks need to be enabled:

  • store/product/deleted

Data Mapping

BC Product Delete To iPaaS

Allow for product deletes to come down from BigCommerce and remove that item from iPaaS.com

Notes:

  • Please be careful about using this depending on your system of record for products.

  • If you do not want deletes in BC to delete products in iPaaS.com, remove this mapping or do not enable this webhook.

  • Delete mapping collections do not have any mappings by design.

Products FROM iPaaS.com

Webhooks (Internal)

In order to enable Product data to flow FROM iPaaS.com, the following external webhooks need to be enabled:

  • product/created

  • product/updated

  • product/category/created

  • product/category/updated

  • product/category/deleted

  • product/inventory/created

  • product/inventory/updated

  • product/inventory/deleted

  • product/variant/created

  • product/variant/updated

  • product/variant/deleted

  • product/variant/category/created

  • product/variant/category/updatedp

  • roduct/variant/category/deleted

  • product/variant/inventory/created

  • product/variant/inventory/updated

  • product/variant/inventory/deleted

Notes:

  • Product/category/updated

    • Note: It is not recommended to subscribe to this webhook, since it will create unnecessary transfers. The webhook will be processed by the Add/Update mapping above and will likely perform no actions due to the existing assignment to the same category.

  • Product/category/deleted

    • Category assignments can be removed by creating a delete mapping collection for the assignment. No mappings are necessary but the following filter is recommended to only delete assignments from categories that exist in the external system:

      var value = await GetExternalIdAsync(CategoryId, "Product Category", SpaceportSystemId); 

      if (value !=  null){return true;} else {return false;}

    • No mappings are needed in a delete mapping collection.
      ​

Data Mapping

Notes:

  • The names of the following sections are the mapping collection names in iPaaS.com.

  • Some mapping collections have mappings that need to be updated. Those are denoted by a *

  • Some mapping collections have Lookup Translations that should be reviewed. Those are denoted by a ⁺

  • Some mapping collections have mapping or error filters that need to be updated. Those are denoted by a º

BC Product Add Only From iPaaS

This is used for adding products to BC from iPaaS.com.

Notes:

  • Special consideration is needed for products if BC is setup with Multi-Store Fulfillment (MSF) to ensure the signs channel IDs are assigned. Please reach out to your MiSP for information regarding this.

  • Options in iPaaS.com are designed around color as a default, but additional ones can be added to by an MiSP.

  • Related products can be added as a Dynamic Formula with the destination field of RelatedProducts with the following formula:

    • ConvertRelatedProductsToBigCommerceIdsAsync(object relatedProducts, string typeFilter)

    • The function is needed to pass in the IDs of those products

    • The typeFilter parameter is optional and if no value is specified, all related products will be added to the list (if they have BigCommerce external IDs.) Passing one of the values below for the typeFilter allows filtering to only specific related product types as well:

      • Replacement

      • Similar Item

      • Related Product

This mapping collection has the following sub-mapping collections:

  • BC Product Variant Add Only From iPaaS

    • BC Product Variant Option Add Only From iPaaS

  • BC Product Option Add Only From iPaaS⁺

    • BC Product Option Value Add Only From iPaaS⁺

  • BC Product Unit Add Only From iPaaS

BC Product Category Add From iPaaS

These are the product categories to be used in building out the category tree in BC.

Notes:

  • The BC default mappings in iPaaS.com assume a single category tree. Please reach out to your MiSP should you want to create multiple trees.

BC Product Category Assignment Delete From IPaaS

Used to delete a category assignment from BC.

Notes:

  • Delete mapping collections do not have any mappings by design.

BC Product Category Assignment From IPaaS

Used to assign a product to a specific category in BC.

Notes:

  • Category assignments are often be performed after a product update, and, at times, the product update webhook could be processed before the category assignment had completed.

    • To alleviate this problem, category assignment webhooks can be processed first. This will ensure the subsequent assignment is processed in a timely manner before the next full product update.

    • The filter and dynamic formula in this mapping collection are designed to handle this.

BC Product Category Update From IPaaS

Update the categories assigned to a product in BC.

BC Product Inventory Add Only From IPaaSº

Add inventory for new products added to BC.

Notes:

  • iPaaS.com only supports using one Location for inventory in BC. The name of the location needs to be updated in the mapping filter. Replace the word MAIN with the name of your iPaaS.com location that has inventory assigned to BC.

  • Inventory external IDs will not be linked until a full product update is performed.

  • BigCommerce does not accept negative values for inventory. If you need to send a value you think might be negative, you can use the larger function, i.e. Larger(QtyAvailable,0).

BC Product Realtime Inventory Updates From IPaaSº

A lightweight way to update inventory as it changes without needing to update the entire product.

Notes:

  • iPaaS.com only supports using one Location for inventory in BC. The name of the location needs to be updated in the mapping filter. Replace the word MAIN with the name of your iPaaS.com location that has inventory assigned to BC.

BC Product Update Only From IPaaS*

Update products in BC with updates in iPaaS.com.

Notes:

  • Special consideration is needed for products if BC is setup with Multi-Store Fulfillment (MSF) to ensure the signs channel IDs are assigned. Please reach out to your MiSP for information regarding this.

  • Options in iPaaS.com are designed around color as a default, but additional ones can be added to by an MiSP.

  • Some of the mappings below update inventory. iPaaS.com only supports using one Location for inventory in BC. The name of the location needs to be updated in the mapping formula. Replace the word MAIN with the name of your iPaaS.com location that has inventory assigned to BC.

This mapping collection has the following sub-mapping collections:

  • BC Product Variant Update Only From IPaaS*

    • BC Product Variant Option Update Only From IPaaS

  • BC Product Option Update Only From IPaaS⁺

    • BC Product Option Value Update Only From IPaaS⁺

  • BC Product Unit Update Only From IPaaS

BC Product Variant Delete From IPaaS

Used to delete. product variant from BC.

Notes:

  • Delete mapping collections do not have any mappings by design.

BC Product Variant Inventory Add Only From IPaaS

Add inventory for new product variants added to BC.

Notes:

  • Some of the mappings below update inventory. iPaaS.com only supports using one Location for inventory in BC. The name of the location needs to be updated in the mapping filter. Replace the word MAIN with the name of your iPaaS.com location that has inventory assigned to BC.

BC Product Variant Realtime Inventory Updates From IPaaS

A lightweight way to update variant inventory as it changes without needing to update the entire product.

Notes:

  • Some of the mappings below update inventory. iPaaS.com only supports using one Location for inventory in BC. The name of the location needs to be updated in the mapping filter. Replace the word MAIN with the name of your iPaaS.com location that has inventory assigned to BC.

Custom Functions

Redirects

iPaaS.com supports the RedirectUrl and RedirectUrlSite fields, both of which are required on a product in order to set a redirect for the product. To set these you need to know the ID of the site:

  • SiteIdFromChannelId(int) – For the main site, this should work: await SiteIdFromChannelId(1)

  • SiteIdFromChannelUrl(string) – this will use the site url, e.g. await SiteIdFromChannelUrl("https://redrook.mybigcommerce.com")

Product Modifiers

Product Modifiers allow shoppers to input values tracked with a line item when sold. These options are presented in addition to Variant Options (such as Size and Color) on the product page. Stores have the ability to add many Modifiers and apply them in different groups by product.

In order to use these you need to add them in BigCommerce, add them as custom fields in iPaaS.com, create mappings using special handling and then account for the mappings coming back from BigCommerce.

Creating Custom Fields

Since these are custom fields in BigCommmerce, in order to utilize them in mappings they need to be added as custom fields in the BigCommerce Subscription (Subscription Management > Subscriptions > BigCommerce > Custom Fields).

The name given to the Custom Field will be the name assigned to the Modifier Display Name in BC and the module should be BC Product.

Add Product Mappings

In the Product Add and Product Update mapping collections, create a single mapping entry for each one on the parent collections.

The mappings should be created as a dynamic formula:

  • The destination will be the custom field you created

  • The source value should be one of the following functions passing the values that are relevant to your configuration:

Function

Type of Data

Data Attributes

ToTextModifier

bool required

Default Value is not set
Single Line Only
No Min/Max Characters

ToTextModifier

bool required, string defaultValue

Single Line Only
No Min/Max Characters Limits

ToTextModifier

bool required, string defaultValue, int? textMaxLines, int? textMinLength, int? textMaxLength

If Max Lines > 1 then entry box is set as MultiLine

ToNumberModifier

bool required

Default Value is not set

No Min/Max Limits

ToNumberModifier

bool required, int? defaultValue

integers are required for defaults and number limits, even when double type values are permitted.

No Min/Max Limits

ToNumberModifier

bool required, int? defaultValue, string numberLimitMode, bool numberIntegersOnly, int? numberLowestValue, int? numberHighestValue

numberLimitMode Allowed Values: lowest, highest, range

ToDateModifier

bool required

Default Value is not set

No Earliest/Latest Date Limits

ToDateModifier

bool required, string defaultValue

No Earliest/Latest Date Limits

Datevalues must be passed using full DateTime format: 2020-01-01T00:00:00+00:00

ToDateModifier

bool required, string defaultValue, string dateLimitMode, string dateEarliestValue, string dateLatestValue

dateLimitMode Allowed Values: earliest, range, latest

ToPickListModifier

bool required, Dictionary<string, string> optionValues

productListAdjustsPricing set to false

productListAdjustsInventory set to false

productListShippingCalc set to “none”

ToPickListModifier

bool required, string defaultValue, bool productListAdjustsPricing, bool productListAdjustsInventory, string productListShippingCalc, Dictionary<string, string> optionValues

productListShippingCalc Allowed Values: none, weight, package

ToDropDownModifier

bool required, List<string> optionValues

Default Value is not set

ToDropDownModifier

bool required, string defaultValue, List<string> optionValues

ToSwatchModifier

bool required, Dictionary<string, string> optionValues

Default Value is not set

ToSwatchModifier

bool required, string defaultValue, Dictionary<string, string> optionValues

ToRadioButtonsModifier

bool required, List<string> optionValues

Default Value is not set

ToRadioButtonsModifier

bool required, string defaultValue, List<string> optionValues

ToRectangleModifier

bool required, List<string> optionValues

Default Value is not set

ToRectangleModifier

bool required, string defaultValue, List<string> optionValues

ToCheckBoxModifier

bool required, string description

isChecked = false

ToCheckBoxModifier

bool required, string description, bool isChecked

ToFileUploadModifier

bool required

fileTypesMode is set to “all” <br>No FileType Limits

ToFileUploadModifier

bool required, string fileTypesMode, List<string> fileTypesSupported, List<string> fileTypesOther, int? fileMaxSize

fileTypesMode Allowed Values: specific, all

fileTypesSupported example: images, documents, other

Sample Usage

Dynamic Formula

Notes

ToTextModifier(false)

ToTextModifier(false, ““)

ToTextModifier(false, ““, 5, 0, 30)

ToNumberModifier(false)

ToNumberModifier(false,5.0)

ToNumberModifier(false,11,"lowest",true,1,-1)

ToNumberModifier(false,11,"highest",false,-1,100)

ToNumberModifier(false,11,"range",true,1,100)

ToDateModifier(false)

ToDateModifier(false,”2020-09-28 T05:00:00”)

ToDateModifier(false,"2020-09-28T05:00:00+00:00", "range", "2020-01-01T00:00:00+00:00", "2020-09-30T23:59:59+00:00")

ToDropDownModifier(false, StringListFromString(“EAST, WEST, SOUTH”))

BigCommerce requires a default. Not setting one will make the first entry as default.

ToRectangleModifier(false, “WEST”, StringListFromString(“EAST, WEST, SOUTH”))

BigCommerce requires a default. Not setting one will make the first entry as default.

ToRadioButtonsModifier(false, “SOUTH”, StringListFromString(“EAST, WEST, SOUTH”))

BigCommerce requires a default. Not setting one will make the first entry as default.

ToSwatchModifier(true, JSONToDictionary(“{\”BLUE\”:\”#3600FF\”, \”RED\”:\”#FF5C00\”, \”GREEN\”:\”#3FFF00\”}”))

BigCommerce requires a default. Not setting one will make the first entry as default.

ToSwatchModifier(true, “RED”, JSONToDictionary(“{\”BLUE\”:\”#3600FF\”, \”RED\”:\”#FF5C00\”, \”GREEN\”:\”#3FFF00\”}”))

ToCheckBoxModifier(true, “Checkbox 1”)

ToCheckBoxModifier(true, “Checkbox 2”, true)

ToFileUploadModifier(true)

ToFileUploadModifier(true, “specific”, StringListFromString(“images,other”), StringListFromString(“eps”), 1000)

Examples

iPaaS.com Mapping Collection

BigCommerce Admin for the Product

BigCommerce Front End for the Product

In order to accept these values on Product Line Items, they need to be added to Transaction Line Mappings. Please see the Transaction Line Items Documentation for those instructions.

RemoveModifier()

When a mapping with this function exists, the field name in the mapping will be checked for existence. In the case that it exists, it will be removed.

Price Adjusters

You can add an overload to the ToDropDownModifier that accepts a list of prices that will apply price adjusters to the values provided; if there is only one price included it will be used for all values.

For example, if you have 3 values then you can provide 1, or 3 prices, and the first price applies to the first value, the second price to the second value, etc. Here is how that would look in a dynamic formula:

ToDropDownModifier(bool required, string defaultValue, List<string> optionValues, List<decimal> priceModifier)

SpecialVariantOptionExclusions

In some cases, users will want to update ValueData fields (colors or pattern URLs) directly in BC. To do this, create a BigCommerce custom field in iPaaS.com called SpecialVariantOptionExclusions (case sensitive) and map it on the product add/update like so:

ImageURL Functions

iPaaS.com supports sending an external, publically accessible image URL into BigCommerce.

Notes

  • Existing images in BigCommerce will not be duplicated when providing a BigCommerce product id to the function, based on a name likeness match.

  • The function accepts one string (one image) and will flag the image as the thumbnail, sort order 1 in BigCommerce.

  • mappings must return a null value for the field when there is no image provided. Otherwise, the transfer will fail with the following error: 

    Unable to process transfer. Reason: Error calling BigCommerceCallWrapper.Product_Post(ImageURL Regression Tests): The required field 'image_url' was not supplied.

Example Use Case

  • Image 1 and image 2 exist in BigCommerce.

  • End user flags image 1 as thumbnail and sort order as 1 in BigCommerce, image 2 as sort order 2.

  • Image 2 is currently being included in iPaaS.com update mapping.

  • After the next product update from iPaaS, image 2 is flagged as thumbnail sort order 1.

Sample Mappings

Title

Mapping

Notes

Add Only FROM

string ImageURL = (string)(GetCustomFieldValue(CustomFields, "Images")); 

if(string.IsNullOrEmpty(ImageURL)) {return null} else { 

return ProductImageListFromFilenames(0, ImageURL) }

We are passing 0 as the BC product ID

Update Only FROM

string ImageURL = (string)(GetCustomFieldValue(CustomFields,"Images")); 

if(string.IsNullOrEmpty(ImageURL)) {return null} else { 

var BCProductId = (int)(int.Parse(GetExternalId(Id,"product",SpaceportSystemId))); 

return ProductImageListFromFilenames(BCProductId,ImageURL); 

}

Requires BC product ID or duplicate images will be added

Passing Over Multiple Images

This function can accept multiple images, but only when using the following format: 

return ProductImageListFromFilenames(BCProductId, image1, image2, image3);

In the example above, the image1 image2 and image3 objects are strings that contain the image URL.

Images are processed in the order they are passed into the feature. The first image is flagged as the thumbnail, and the sort order in BigCommerce is set to the order of the images provided.

If you pass the feature a list of strings (instead of a dynamic list) however, it will fail with the following error: 

return ProductImageListFromFilenames(BCProductId, myListOfImageStrings);

Sample Mappings

Title

Mapping

Notes

Add Only FROM

string image1 = (string)(GetCustomFieldValue(CustomFields, "Images")); 

string image2 = (string)(GetCustomFieldValue(CustomFields, "Images 2")); 

string image3 = (string)(GetCustomFieldValue(CustomFields, "Images 3")); 

return ProductImageListFromFilenames(0, image1, image2, image3);

Update Only FROM

string image1 = (string)(GetCustomFieldValue(CustomFields, "Images")); 

string image2 = (string)(GetCustomFieldValue(CustomFields, "Images 2")); 

string image3 = (string)(GetCustomFieldValue(CustomFields, "Images 3")); 

var BCProductId = (int)(int.Parse(GetExternalId(Id,"product",SpaceportSystemId))); 

return ProductImageListFromFilenames(BCProductId, image1, image2, image3);

Related Articles
BigCommerce Transactions
BigCommerce Payment Methods
BigCommerce Gift Cards
BigCommerce Customers & Customer Companies
Integration Settings
Did this answer your question?