This article is for developers of your BigCommerce website and is a reference on how to map standalone products and products with variants to your ecommerce store. You can find additional resources on How to Connect Wondersign to Your BigCommerce Store and How to Manage Connector Sync Management Settings.
Requirements/Tools Needed:
You must have a paid plan with BigCommerce
You must have a Clicks or Bricks & Clicks paid plan with Wondersign. For more information, visit wondersign.com/pricing
Getting Started
Standalone Product
Wondersign | BigCommerce | Details |
Object: Product.meta Property: namespace | The Connector uses meta fields to identify its products. | |
Object: Product.meta Property: description | Always set as Product record is created by the Wondersign. | |
Object: Product Property: type | Always set as physical. | |
Object: Product Property: consumerBrand | Object: Brand Property: name | The Connector product sync creates or locates existing 'brand' using the name. |
Object: Product Property:brand_id | If consumerBrand is blank, it falls back to the brand. | |
Object: Product Property: sku | Object: Product Property: sku | Required, must be unique for the entire store, and is not case-sensitive. |
Object: Product Property: name | Object: Product Property: name | Required, must be unique for the entire store, and is not case-sensitive. |
Object: Product Property: description | Object: Product Property: description | |
Object: Product.attributes[] Property: normalizedValues[] | Object: Category Property: name | When attribute = category, the product sync splits all levels of each product category name as follows:
|
Object: Category Property: image_url | The Connector product sync automatically adjusts the image size to 1 MB (BigCommerce admin page limit). If a category doesn't have an image in the Data API, the connector will not overwrite the existing image in BigCommerce. | |
Object: Product Property: categories[].id | ||
Object: Product Property: isSoldIndividually | Object: Category Property: is_visible | The connector will set categoryis_visible to true if it has at least one product or subcategory that has is_visible: true. The connector will set categoryis_visible to false if there are no products or subcategories with is_visible: true. |
Object: Product Property: is_visible | The connector will set the product is_visible in BigCommerce according to its isSoldIndividually value (true or false). | |
Object: Product.price Property: retailPrice | Object: Product Property: Price | *Required. Depending on your settings in the Wondersign Commerce Automation Manager Retail Price may not be returned by Data API. When price.retailPrice is "undefined", which means not present in the response from Data API, the Connector enters an error record in the product sync report and skips the product record while performing the Create or Update operation. |
Object: Product.price Property: cost | Object: Product Property: cost_price | When cost is not present, the Connector product sync will not override the product cost value in the BigCommerce store. |
Object: Product.price Property: listPrice | Object: Product Property: retail_price | When the list price is not present, the Connector will assign a 0 value. |
Object: Product.price.rates[] Property: rate | Object:Product Property: fixed_cost_shipping_price | Only used when Enable Shipping Rate is True in the virtual device settings. |
Object: Product Property: UPC | Object: Product Property: UPC | |
Object: Product Property: itemWeightLbs | Object: Product Property: weight | Required & converts from pounds to BigCommerce values based on the store.weight._units. |
Object: Product Property: itemLengthInches | Object: Product Property: width | Converts from inches to BigCommerce values based on the store.dimension_units. |
Object: Product Property: itemHeightInches | Object: Product Property: height | Converts from inches to BigCommerce values based on the store.dimension_units. |
Object: Product Property: itemDepthInches | Object: Product Property: depth | Converts from inches to BigCommerce values based on the store.dimension_units. |
Object: Product Property: isDirectShipping | Object: Product Property: custom_fields[].name | Set as Free Shipping or Direct To Consumer, according to the Direct Shipping management options. |
Object: Product Property: custom_fields[].value | Set as Yes when isDirectShipping is true and No when it's false. | |
Object: Product Property: is_free_shipping | For standalone products, if the Direct Shipping management option is Free Shipping. | |
Object: Product Property: image | Object: Product Property: images[].image_url | BigCommerce limits the image size to 8 MB each and the Connector product sync automatically adjusts its size. Set the number of images per product in Advanced Configuration. |
Object: Product Property: images[].is_thumbnail | Always set to true. | |
Object: Product Property: additionalImages[] | Object: Product Property: images[].image_url | BigCommerce limits the image size to 8 MB per file. If the product's additional image is a duplicate of the main image, the Connector product sync will skip the duplicate. |
Object: Product Property: productType | Object: Product Property: custom_fields[].name | The Connector creates and maintains a custom field named Product Type. |
Object: Product Property: custom_fields[].value | The Connector assigns the productType value to the Product Type custom field. | |
Object: Product Property: sku + name + productType + | Object: Product Property: search_keywords | The Connector product sync combines the product sku, name, productType, and attribute values by:
|
Object: Product.attributes[] Property: attribute | Object: Product Property: custom_fields[].name | The category attribute is not considered in this custom field. Create a distinct list of attributes to create this custom field. The Connector product sync will capitalize the first letter of each attribute word and separate them with a space. For examples |
Object: Product.attributes[] Property: values[] normalizedValues[] | Object: Product Property: custom_fields[].value | The Connector product sync:
References |
Object: Product Property: channel_id | If the store has the multi-storefront feature enabled (store.features[].multi_storefront_enabled is true), the Connector assigns the product to the default storefront channel 1. | |
Object: Channel Assignments Property: product_id | The Connector uses the BigCommerce product id to assign it to the channel. |
Product Transformation with Variants
Wondersign | BigCommerce | Details |
Object: Product.meta Property: namespace | Always set as wondersign-sync, the product sync extends the product meta object to identify products managed by the Connector. | |
Object: Product.meta Property: description | Always set as Product record is created by the Wondersign. | |
Object: Product Property: type | Always set as physical. | |
Object: Product Property: consumerBrand | Object: Brand Property: name | If empty, the Connector product sync uses the brand property and creates or locates the existing brand name. It must be unique to BigCommerce and is not case-sensitive. If the product has variants, the Connector product sync locates the variant with the first SKU sorted alphabetically and uses its consumerBrand. |
Object: Product Property: brand_id | The Connector product sync assigns the brand_id to the product. | |
Object: Product.variant Property: brand | Object: Brand Property: name | Required but only used when the consumerBrand is empty. |
Object: Product Property: brand_id | The Connector product sync assigns the brand_id to the product. | |
Object: Product.variant Property: variants[].sku | Object: Product Property: variants[].sku | SKUs for variants are required and must be unique for the entire store, across all variants and standalone products. SKUs are not case-sensitive and the Connector product sync will sort the variants of the group alphabetically. |
Object: Product.variant Property: title | Object: Product Property: name | The name of the product is required and must be unique for the entire store. It is not case-sensitive. Currently, CAM does not allow changing this object. |
Object: Product.variant Property: description | Object: Product Property: description | Currently, CAM does not allow changing this object. |
Object: Product.attributes[] Property: normalizedValues[] | Object: Category Property: name | When attribute = category, the product sync splits the levels of each product category name as follows:
There is no category level limit and the Connector creates or locates existing categories using the names. Names must be unique at the same level in BigCommerce and not-case sensitive.
The Connector product sync will distinctly use all product categories in the variant group if the product has variants. |
Object: Category Property: image_url | BigCommerce API doesn't limit the image size, but the admin page limits it to 1 MB each and the Connectors product sync will automatically adjust it. If a category doesn't have an image in the Data API, the connector will not overwrite the existing image in BigCommerce. | |
Object: Product Property: categories[].id | The Connector product sync will assign the categories id to the product. | |
Object: Product Property: categories[].id | Object: Category Property: is_visible | If the category sync management option is false, the Connector will set the category is_visible to true (default value). If the category sync management option is true, the Connector sets category is_visible to true if it has at least one product or subcategory. The connector sets category is_visible to false if there are no products or subcategories. |
Object: Product Property: is_visible | The Connector sets the product is_visible in BigCommerce according to its isSoldIndividually value (true or false). If at least one product in the variant group has isSoldIndividually: true, the connector sets the product is_visible on the BigCommerce as true. | |
Object: Product.price Property: retailPrice | Object: Product Property: variants[].price | Required and the original value is transmitted without modification. Under certain circumstances, the retailPrice (based on the configuration in CAM) may not be returned by Data API. When price.retailPrice is not present, the Connector enters an error record in the product sync report and skips the product record while creating and updating products. |
Object: Product.price Property: cost | Object: Product Property: variants[].cost_price | The original value is transmitted without modification. When the cost is not present in the CK Data API, the product sync will not override the product cost value in the BigCommerce store. |
Object: Product.price Property: listPrice | Object: Product Property: variants[].list_price | The original value is transmitted without modification. When the listPrice is not present in the CK Data API, the product sync will assign to 0. |
Object: Product.price Property: rates[].rate | Object: Product.price Property: variants[] | When the sync settings rate is true, only one service is available, and its original rate value is transmitted without modification. When the rates.rate is not present in the CK Data API, the product sync will not override the product fixed_cost_shipping_price value in the BigCommerce store. |
Object: Product Property: upc | Object: Product Property: variants[].upc | |
Object: Product Property: itemWeightLbs | Object: Product Property: variants[].weight | Required and converts pounds to BigCommerce values based on the store.weight_units. |
Object: Product Property: itemLengthInches | Object: Product Property: variants[].width | Converts inches to BigCommerce values based on store.dimension_units. |
Object: Product Property: itemHeightInches | Object: Product Property: variants[].height | Converts inches to BigCommerce values based on store.dimension_units. |
Object: Product Property: itemDepthInches | Object: Product Property: variants[].depth | Converts inches to BigCommerce values based on store.dimension_units. |
Object: Product Property: isDirectShipping | Object: Product Property: custom_fields[].name | Set as Free Shipping or Direct To Consumer, according to the Direct Shipping management options. |
Object: Product Property: custom_fields[].value | Set as Yes when isDirectShipping is true and No when it's false, combining all the variants' isDirectShipping into a comma-separated string. | |
Object: Product Property: is_free_shipping | This is for products with variants, if the Direct Shipping management option is Free Shipping. | |
Object: Product Property: image | Object: Product Property: images[].image_url | BigCommerce limits the image size to 8 MB each and the Connector product sync automatically adjusts its size. The Connector product sync will locate the variant with the first SKU sorted alphabetically and assign its main image to the BigCommerce product. It will not assign the other variants' main images to the BigCommerce Product, only to the variant. Set the number of images per product in Advanced Configuration in CAM. |
Object: Product Property: images[].is_thumbnail | Always set to true. | |
Object: Product Property: image | Object: Product Property: variants[].image_url | Required and BigCommerce limits the image size to 8 MB each, the Connector product sync will automatically adjust its size. The image depends on the variants options. Variants share the same image If the variant options have:
Variants with specific images:
|
Object: Product Property: additionalImages[] | Object: Product Property: images[].image_url | BigCommerce limits the image size to 8 MB each. If the product's additional image is a duplicate of the main image, the Connector product sync will skip the duplicate, it will combine the variants' additional images and assign them to BigCommerce product images, but will only assign to the BigCommerce product the main image of the first variant. |
Object: Product Property: productType | Object: Product Property: custom_fields[].name | The connector will create and maintain a custom field named Product Type. |
Object: Product Property: custom_fields[].value | The connector will distinctly combine productType values from all products in the variant group in a comma-separated string. Connector will not create the custom_field[] if productType is a variant option. | |
Object: Product Property: variant.variants[].sku + variant.title + | Object: Product Property: search_keywords | The Connector product sync will combine in a comma-separated string the product variants[].sku, title, productType and attribute values of all the products in the variants group by:
|
Object: Product.attributes[] Property: attribute | Object: Product Property: custom_fields[].name | The category is not considered in this property and the Connector product sync:
|
Object: Product.attributes[] Property: values[] normalizedValues[] | Object: Product Property: custom_fields[].value | The Connector:
References |
Object: Product.relatedProducts[] Property: sku | Object: Product Property: custom_fields[].name | Creates a custom field named Collection if the relatedProducts.complete |
Object: Product.variant Property: custom_fields[].value | The product sync combines all related products from the variants into the same custom field value and distinct values from relatedProducts.complete | |
Object: Product.variant Property: options[].option | Object: Product Property: variants[].options_values[]. option_display_name | The type property of the variant option allows the user to select how the variant options are displayed in the BigCommerce storefront (radio_buttons, rectangles, dropdown, product_list, product_list_with_images, or swatch). Currently, the Connector product sync does not set the type property of the variant option. The BigCommerce store will use the default design format of the current theme to define its value. If the type of a variant option is changed, the BigCommerce store will set it back to the default type the next time the connector updates the product or variant. |
Object: Product.variant Property: options[].value | Object: Product Property: variants[].options_values [].label | |
Object: Channel Assignments Property: channel_id | If the store has the multi-storefront feature enabled (store.features[].multi_storefront_ | |
Object: Channel Assignments Property: product_id | The Connector uses the BigCommerce product id to assign it to the channel. |