Big Commerce Create Product
Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)
| Date | Version | Name | Applied changes |
|---|---|---|---|
| 09/08/2023 | v1.0 | Bogomil Pavlov | First Publish |
| 30.11.2023 | v1.1 | Bogomil Pavlov | Dimensions logic changes |
| 01.12.2023 | v1.2 | Bogomil Pavlov | Is free shipping flag changes |
| 06.12.2023 | v1.3 | Beatris Bunova | Clarify images |
| 06.12.2023 | v1.4 | Bogomil Pavlov | Variations Handle |
| 17.04.2023 | v1.5 | Bogomil Pavlov | Multi Store Logic |
| 27.08.2024 | v1.6 | Bogomil Pavlov | Additional Product Categories |
| 02.09.2024 | v1.7 | Bogomil Pavlov | Introduce Custom fields |
The product creation is product per product (if variation all variants). We want all triggers, validations and standardizations to be as per Product Listing general requirements
When we are creating variation products we want to select all the variants with the same Product Account > Variation Group. However if we have already created a variation group on BigCommerce we are not able to add any additional variants and we need to delete and relist the product. Thus we want to return an error that we are not able to add new variants in a created variation group.
<v1.5> We will have two different flows for create product depends on the store type set in Account Big Commerce Single Store - When we have single BC store we are following our standard logic and once the product is created on BC we treat it as Published and there are no additional steps.
Multi Store - When we have multi BC store we will have additional step during the product creation and when the product is created on BC we treat it as Created then we will have additional step to assign the actual channels and finally we will treat the product as Published, the whole flow will look like this: First we will be creating the product on BC and after successful response instead of setting the product as Product Account > Product Status = Product Published we want mark the product as Product Account > Product Status = Product Created which will be our trigger for Channel Assignment flow (which is described in another doc here: Big Commerce Channel Assignment). </v1.5>
API Call: POST https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products
Doc: https://developer.bigcommerce.com/docs/rest-catalog/products#update-a-product
Sample Request: POST https://api.bigcommerce.com/stores/oduzegjfvn/v3/catalog/products Body:
{
"name": "Smith Journal 14152 Test",
"type": "physical",
"sku": "SM-13test3312",
"description": "<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>",
"weight": 1,
"width": 1,
"depth": 1,
"height": 1,
"price": 10,
"cost_price": 20,
"sale_price": 40,
"inventory_level": 4,
"inventory_tracking": "variant",
"categories": [
18,20,50
],
"brand_id": 35,
"brand_name": "Sagaform",
"fixed_cost_shipping_price": 0,
"is_free_shipping": true,
"is_visible": true,
"is_featured": true,
"upc": "1234567891011",
"availability": "available",
"condition": "New",
"is_condition_shown": true,
"gtin": "1234567891011",
"mpn": "1234567891011",
"images": [
{
"is_thumbnail": true,
"image_url": "https://images-riverisland.wearepentagon.com/754968_back.jpeg"
},
{
"image_url": "https://images-riverisland.wearepentagon.com/754968_alt1.jpeg"
}
],
"variants": [
{
"cost_price": 30,
"price": 40,
"sale_price": 50,
"purchasing_disabled": false,
"upc": "12345678",
"inventory_level": 2,
"inventory_tracking": "variant",
"mpn": "1234567890",
"gtin": "012345678905",
"sku": "765124q3",
"option_values": [
{
"option_display_name": "Color",
"label": "Beige"
},
{
"option_display_name": "Size",
"label": "42"
}
]
},
{
"cost_price": 30,
"price": 40,
"sale_price": 50,
"purchasing_disabled": false,
"upc": "09876543",
"inventory_level": 2,
"inventory_tracking": "variant",
"mpn": "098765432",
"gtin": "098765432",
"sku": "7928761q5",
"option_values": [
{
"option_display_name": "Color",
"label": "Black"
},
{
"option_display_name": "Size",
"label": "43"
}
],
}
]
"custom_fields": [
{
"name": "MPN",
"value": "36 11 6 777 349"
}
]
}Mapping:
| Big Commerce Field | Hemi Field | Required | Comment | ||
|---|---|---|---|---|---|
name |
Product Account > Title | Yes | If we have variation we pick the first product account > title | ||
type |
“physical“ |
Yes | Hardcoded as “physical" |
||
sku |
Product > SKU |
OR
Product Account > Variation Group | Yes | If we have Variation Group we push it as skuelse we use our Product > SKU |
| description | | | Product Account > Description | No | |
| weight | | | Product > Weight | Yes | Our weight is in grams however BC expect KGs so we need to convert it.
(Example: 12.5kg) |
| width | | | Product > Width | No | In centimeters (by default we use cm)
<v1.2>If empty we do not want to include it in the payload</v1.2> |
| depth | | | Product > Length | No | In centimeters (by default we use cm)
<v1.2>If empty we do not want to include it in the payload</v1.2> |
| height | | | Product > Height | No | In centimeters (by default we use cm)
<v1.2>If empty we do not want to include it in the payload</v1.2> |
| price | | | Product Account > Price
OR
Product Account > RRP | Yes | If RRP <= Price we push Product Account > Price
If RRP > Price we push Product Account > RRP
Please note if we have a Variation Group for the product price/rrp we pick the price from the first variant |
| cost_price | | | Product Account > Original Price | No | Please note if we have a Variation Group for the product original price we pick the cost price from the first variant |
| sale_price | | | Product Account > Price | No | If RRP > Price we want to push this field as Product Account > Price
If RRP <= Price we include the sale_price with value 0
Please note if we have a Variation Group for the product price we pick the sale from the first variant |
| inventory_level | | | Product Account > Quantity | Yes | If we have a variation group we want to SUM all variant quantities |
| inventory_tracking | | | “variant“ or “product“ | Yes | Hardcoded as “variant“ only if we have Product Account > Variation Group
Hardcoded as “product“ only if we dont have Product Account > Variation Group |
| categories | | | Product Account > Primary Category ID
<v1.6>AND
Product Account Big Commerce > Additional Categories | Yes | We will map the category name against the id and push the ID
Please note if we have a Variation Group and we have different Product Account > Primary Category ID across the variants we want to return an error
Also we want to support more than one category assigned on a product and we want to introduce additional field from which we want to obtain the additional categories if any.
We are doing the same validation and checks like we do for the Primary Category ID.
</v1.6> |
| brand_id | | | Product > Brand
OR
Product Account > Item Specific | Yes | Product Account > Item Specifics is with priority and the Item Specifics Name should be “Brand“
We will map the brand name against the id in the downloaded taxonomy and push the ID
Please note if we have a Variation Group for the product brand we pick the brand from the first variant |
| brand_name | | | Product > Brand
OR
Product Account > Item Specific | Yes | Product Account > Item Specifics is with priority.
We will map the brand name and validate it against the taxonomy and push the name
Please note if we have a Variation Group for the product brand we pick the brand from the first variant |
| fixed_cost_shipping_price | | | Shipping Method > Shipping Service Cost | No | #1 Based on the assigned shipping template we get the Shipping Method > Shipping Service Cost
2 Based on the default shipping template we get the Shipping Method > Shipping Service Cost
3 If there is no assigned or default shipping template we do not include this field in the payload
(If we have more than one method added in the shipping template we pick the one with highest price) |
| is_free_shipping | | | “true” or “false” | No | <v1.2>
We want to control this based n the fixed_cost_shipping_price and if we have fixed_cost_shipping_price > 0 we want always send the is_free_shipping as “false“.
If fixed_cost_shipping_price <= 0 we want is_free_shipping as “true“.
</v1.2>
If there is no assigned or default shipping template we do not include this field in the payload |
| is_visible | | | “true” | Yes | Hardcoded as “true” |
| is_featured | | | Product Account Big Commerce > Featured Product | No | If Product Account Big Commerce > Featured Product = Yes we push “true“If Product Account Big Commerce > Featured Product = No we push “false“ |
| upc | | | Product > UPC | No | If we have a Variation Group we want to exclude this from the payload |
| availability | | | “available“ | Yes | Hardcoded as “available“
Please note even if we have 0 stock product we want to push this as available. |
| condition | | | Product > ConditionID | Yes | Condition Mapping:Big Commerce Condition - Hemi Condition
New - New (with tags)
Used - Used (Pre-owned, Like new)
Refurbished - Refurbished acceptable
We want to use the conditions on the left.
If other condition is selected we want to return internal error |
| gtin | | | Product > EAN
OR
Product Account > Marketplace EAN | No | Product Account > Marketplace EAN is with priority
If we have a Variation Group we want to exclude this from the payload |
| is_condition_shown | | | “true“ | Yes | Hardcoded as “true“ |
| mpn | | | Product > MPN | No | If we have a Variation Group we want to exclude this from the payload |
| <v1.3>images | | | | | |
| | is_thumbnail | | “true” | Yes/No | We want to include this field only for the first of (4) Leading Images as “true”
Images Handling Additional Explanation |
| | image_url | | (6) All Images (Leading + Additional) | Yes | Images Handling Additional Explanation </v1.3> |
| variants | | | | | Include this in the payload only if we have variation group and the fields in this node are required only if we have a variation group |
| | cost_price | | Product Account > Original Price | No | |
| | price | | Product Account > Price
OR
Product Account > RRP | Yes | If RRP <= Price we push Product Account > Price
If RRP > Price we push Product Account > RRP |
| | sale_price | | Product Account > Price | No | If RRP > Price we want to push this field as Product Account > Price
If RRP <= Price we include the sale_price with value 0 |
| | purchasing_disabled | | “false“ | Yes | Hardcoded as “false“ |
| | upc | | Product > UPC | No | |
| | inventory_level | | Product Account > Quantity | Yes | |
| | inventory_tracking | | “variant“ | Yes | hardcoded as “variant“ |
| | mpn | | Product > MPN | No | |
| | gtin | | Product > EAN
Or
Product Account >Marketplace EAN | No | Product Account >Marketplace EAN with priority |
| | sku | | Product > SKU | Yes | |
| | option_values | | | | |
| | | option_display_name | Product Account > Variation Specific Name | Yes | <1.4>Please note BigCommerce support only Variation Specifics and from the Item Specific we will be picking only the brand.
The way we handle Variations is added in the Product Listing general requirements with tag v1.1 |
| | | label | Product Account > Variation Specific Value | Yes | Please note BigCommerce support only Variation Specifics and from the Item Specific we will be picking only the brand.
The way we handle Variations is added in the Product Listing general requirements with tag v1.1</1.4> |
| <v1.7>custom_fields | | | | | |
| | name | Product Account > Item Specific Name | No | Please note we have to add an exception for the Brand since we do not want to add it as custom field. | |
| | value | Product Account > Item Specific Value | No | </v1.7> | |
Sample Response: Status 200 OK
{
"data": {
"id": 14550,
"name": "Smith Journal 14152 Test",
"type": "physical",
"sku": "SM-13test3312",
"description": "<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>",
"weight": 1,
"width": 1,
"depth": 1,
"height": 1,
"price": 10,
"cost_price": 20,
"retail_price": 0,
"sale_price": 40,
"map_price": 0,
"tax_class_id": 0,
"product_tax_code": "",
"calculated_price": 40,
"categories": [
162
],
"brand_id": 38,
"option_set_id": 319,
"option_set_display": "right",
"inventory_level": 4,
"inventory_warning_level": 0,
"inventory_tracking": "variant",
"reviews_rating_sum": 0,
"reviews_count": 0,
"total_sold": 0,
"fixed_cost_shipping_price": 0,
"is_free_shipping": true,
"is_visible": true,
"is_featured": true,
"related_products": [
-1
],
"warranty": "",
"bin_picking_number": "",
"layout_file": "",
"upc": "1234567891011",
"mpn": "1234567891011",
"gtin": "1234567891011",
"date_last_imported": null,
"search_keywords": "",
"availability": "available",
"availability_description": "",
"gift_wrapping_options_type": "any",
"gift_wrapping_options_list": [],
"sort_order": 0,
"condition": "New",
"is_condition_shown": true,
"order_quantity_minimum": 0,
"order_quantity_maximum": 0,
"page_title": "",
"meta_keywords": [],
"meta_description": "",
"date_created": "2024-09-02T10:41:55+00:00",
"date_modified": "2024-09-02T10:41:55+00:00",
"view_count": 0,
"preorder_release_date": null,
"preorder_message": "",
"is_preorder_only": false,
"is_price_hidden": false,
"price_hidden_label": "",
"custom_url": {
"url": "/14550/smith-journal-14152-test/",
"is_customized": false
},
"base_variant_id": null,
"open_graph_type": "product",
"open_graph_title": "",
"open_graph_description": "",
"open_graph_use_meta_description": true,
"open_graph_use_product_name": true,
"open_graph_use_image": true,
"variants": [
{
"id": 13629,
"product_id": 14550,
"sku": "765124q3",
"sku_id": 1307,
"price": 40,
"calculated_price": 50,
"sale_price": 50,
"retail_price": null,
"map_price": null,
"weight": null,
"calculated_weight": 1,
"width": null,
"height": null,
"depth": null,
"is_free_shipping": false,
"fixed_cost_shipping_price": null,
"purchasing_disabled": false,
"purchasing_disabled_message": "",
"image_url": "",
"cost_price": 30,
"upc": "12345678",
"mpn": "1234567890",
"gtin": "012345678905",
"inventory_level": 2,
"inventory_warning_level": 0,
"bin_picking_number": "",
"option_values": [
{
"id": 1525,
"label": "Beige",
"option_id": 647,
"option_display_name": "Color"
},
{
"id": 1527,
"label": "42",
"option_id": 648,
"option_display_name": "Size"
}
]
},
{
"id": 13630,
"product_id": 14550,
"sku": "7928761q5",
"sku_id": 1308,
"price": 40,
"calculated_price": 50,
"sale_price": 50,
"retail_price": null,
"map_price": null,
"weight": null,
"calculated_weight": 1,
"width": null,
"height": null,
"depth": null,
"is_free_shipping": false,
"fixed_cost_shipping_price": null,
"purchasing_disabled": false,
"purchasing_disabled_message": "",
"image_url": "",
"cost_price": 30,
"upc": "09876543",
"mpn": "098765432",
"gtin": "098765432",
"inventory_level": 2,
"inventory_warning_level": 0,
"bin_picking_number": "",
"option_values": [
{
"id": 1526,
"label": "Black",
"option_id": 647,
"option_display_name": "Color"
},
{
"id": 1528,
"label": "43",
"option_id": 648,
"option_display_name": "Size"
}
]
}
],
"images": [
{
"id": 35651,
"product_id": 14550,
"is_thumbnail": false,
"sort_order": 0,
"description": "",
"image_file": "o/085/754968_alt1__19466.jpg",
"url_zoom": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35651/754968_alt1__19466.1725273716.1280.1280.jpg?c=1",
"url_standard": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35651/754968_alt1__19466.1725273716.386.513.jpg?c=1",
"url_thumbnail": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35651/754968_alt1__19466.1725273716.220.290.jpg?c=1",
"url_tiny": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35651/754968_alt1__19466.1725273716.44.58.jpg?c=1",
"date_modified": "2024-09-02T10:41:56+00:00"
},
{
"id": 35650,
"product_id": 14550,
"is_thumbnail": true,
"sort_order": 0,
"description": "",
"image_file": "p/348/754968_back__09400.jpg",
"url_zoom": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35650/754968_back__09400.1725273715.1280.1280.jpg?c=1",
"url_standard": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35650/754968_back__09400.1725273715.386.513.jpg?c=1",
"url_thumbnail": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35650/754968_back__09400.1725273715.220.290.jpg?c=1",
"url_tiny": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35650/754968_back__09400.1725273715.44.58.jpg?c=1",
"date_modified": "2024-09-02T10:41:55+00:00"
}
],
"primary_image": {
"id": 35650,
"product_id": 14550,
"is_thumbnail": true,
"sort_order": 0,
"description": "",
"image_file": "p/348/754968_back__09400.jpg",
"url_zoom": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35650/754968_back__09400.1725273715.1280.1280.jpg?c=1",
"url_standard": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35650/754968_back__09400.1725273715.386.513.jpg?c=1",
"url_thumbnail": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35650/754968_back__09400.1725273715.220.290.jpg?c=1",
"url_tiny": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/14550/images/35650/754968_back__09400.1725273715.44.58.jpg?c=1",
"date_modified": "2024-09-02T10:41:55+00:00"
},
"videos": [],
"custom_fields": [
{
"id": 77514,
"name": "MPN",
"value": "36 11 6 777 349"
}
],
"bulk_pricing_rules": [],
"reviews": [],
"options": [
{
"id": 647,
"product_id": 14550,
"name": "Color1725273716-14550",
"display_name": "Color",
"type": "rectangles",
"sort_order": 0,
"option_values": [
{
"id": 1525,
"label": "Beige",
"sort_order": 0,
"value_data": null,
"is_default": false
},
{
"id": 1526,
"label": "Black",
"sort_order": 0,
"value_data": null,
"is_default": false
}
],
"config": []
},
{
"id": 648,
"product_id": 14550,
"name": "Size1725273716-14550",
"display_name": "Size",
"type": "rectangles",
"sort_order": 0,
"option_values": [
{
"id": 1527,
"label": "42",
"sort_order": 0,
"value_data": null,
"is_default": false
},
{
"id": 1528,
"label": "43",
"sort_order": 0,
"value_data": null,
"is_default": false
}
],
"config": []
}
],
"modifiers": [],
"parent_relations": []
},
"meta": {}
}Response Mapping:
From the response we want to get the product, the variant ids and the custom fields details and store it as Product Account > Channel Item ID and Product Account Big Commerce > Variant Id with all the relevant statuses and flags.
| Big Commerce Field | Hemi Field | Comment | ||
|---|---|---|---|---|
id |
Product Account > Channel Item ID | This will be the same for all variants | ||
variants |
||||
id |
Product Account Big Commerce > Variant Id | This is unique id for each variant | ||
<v1.7>custom_fields |
||||
id |
Product Account Big Commerce > Custom Fields (id) | |||
name |
Product Account Big Commerce > Custom Fields (Name) | |||
value |
Product Account Big Commerce > Custom Fields (Value) | </v1.7> |
Sample Error Response #1:
{
"status": 409,
"title": "The product name is a duplicate",
"type": "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes",
"errors": {
"name": "The product name is a duplicate"
}
}Sample Error Response #2:
{
"status": 422,
"title": "A brand with id: 1000000000 does not exist",
"type": "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes",
"errors": {
"brand_id": "A brand with id: 1000000000 does not exist"
}
}Sample Error Response #3:
{
"status": 422,
"title": "Invalid field(s): image_url",
"type": "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes",
"errors": {
"image_url": "image_url must be an actual URL or an empty string"
}
}Sample Error Response #4:
{
"status": 422,
"title": "One or more assigned category ids do not exist: 0",
"type": "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes",
"errors": {
"categories": "One or more assigned category ids do not exist: 0"
}
}Sample Error Response #5:
{
"status": 409,
"title": "The product name is a duplicate",
"type": "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes",
"errors": {
"name": "The product name is a duplicate"
}
}We want to store the title as error in Product Account > Update Item Error