Big Commerce Get Products
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 |
|---|---|---|---|
| 07/02/2024 | 1.0 | Bogomil Pavlov | First Published |
| 12/07/2024 | v1.1 | Bogomil Pavlov | |
| 19/07/2024 | v1.2 | Bogomil Pavlov | Error Toast when seller not selected |
| 22/07/2024 | v1.3 | Bogomil Pavlov | Add validation for empty variation group |
| 02.09.2021 | v1.4 | Bogomil Pavlov | Include Custom Fields |
| 29.01.2025 | v1.5 | Bogomil Pavlov | Store additional categories |
| 27.02.2025 | v1.6 | Bogomil Pavlov | Logic Rework |
<v1.1>/Since Big Commerce is treated as a marketplace we will be able to directly get the products from their platform and import them in Hemi because we will be updating them only on Big Commerce so it will be already optimised and ready for use data.
The trigger will be a button in Account Big Commerce which will triggers the Get Products in the backend.
The import will cover all our internal required fields and based on the Account and the Seller setup in Hemi we want to inherit their details for Product Account > Account and Product Account > Seller. <v1.2>If we have more than one seller added in the account we want to pick the default first and if we have a case with more than one default seller we pick the one with the lowest id in Hemi. In case of no seller selected we want to return and error and since the trigger is a button it will be good to have an error message in the log that there is no seller selected and a toast which pops up in UI for the user.</1.2> <v1.6>If we have the SKU already and we have the Listing we want to skip the product for import and do not update it. But if we have the SKU in Hemi and the Listing is missing we want to add the Listing without updating anything on the Product.</v1.6> Product > SKU Product > ConditionId Product > Inventory Title <v1.1>Product > Main Image</v1.1> Product Account > Channel Item Id Product Account > Title Product Account > Primary Category Id Product Account > Price we do not want to import the product. Also we want to add another validation and do not download products if the BC taxonomy is missing so it will be good if this cron is triggered to trigger the Get Taxonomy as well before that. <v1.1>Please note all products which do not pass our validation need to be added in the log file which we are sending via email.</v1.1>
Since we do not know how long it will take for the import to be completed once the cron ends we want to send an email notification to the actual user who triggered the button. We want to use our no-reply email from which we will send the email with the following structure and add the error log: Email Subject: “BigCommerce get products completed (instance_name)” Email Body: ”Total imported products: Total skipped products: Total products with error:” Attached files: single .txt file with skipped products and error products containing (sku, id, name) with comma separation Please note if the file size is more than 20MBs we want to provide a link for download.
Please note that for the body of the email we are counting the SKUs, not the listings.
Get All Products
API Call: GET https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products
Parameters: We want only to set the limit as 250 and use the page parameter in order to navigate through pages and the most important parameter is include which will allows us to get also the images and variants.
Docs: https://developer.bigcommerce.com/docs/rest-catalog/products#get-all-products
Sample Request: GET<v1.4> https://api.bigcommerce.com/stores/dj7b5nt46i/v3/catalog/products?limit=250&page=1&include=images,variants,custom_fields </v1.4>
Sample Response: Status 200 OK
{
"id": 1770,
"name": "Genuine Alloy Wheel x1 19\" Star-Spoke 95 Front Rim 36 11 6 753 241",
"type": "physical",
"sku": "36116753241#Storesome",
"description": "Article Number: 36116753241<br><br>Star-spoke 95 front<br>Cast alloy wheel, 19-inch size.<br><br>BMW Technical Info<br><br>9Jx<br>a<br>19 ET:24<br>Single wheel, without tyre.<br><br>Note: Tyres are not included. This rim comes without center cap.<br>If you need the center cap, please, order part number 36 13 6 783 536.<br><br>Not suitable for BMW M-Models<br><br><table cellpadding=\"1\" cellspacing=\"0\" border=\"0\"><tr><td width=\"110\">MPN</td><td width=\"96\">Series</td><td width=\"180\">Chassis</td><td width=\"120\">Body Type</td><td width=\"210\">Model</td><td width=\"210\">Production Code</td><td width=\"100\">Production Year From</td><td width=\"100\">Production Year To</td><td width=\"60\">Weight</td></tr><tr><td>36116753241</td><td>7 Series</td><td>E65</td><td>Saloon</td><td>730d M57N</td><td>(GM21)</td><td>02.07.2001</td><td>-</td><td>14.800 kg</td></tr><tr><td>36116753241</td><td>7 Series</td><td>E65</td><td>Saloon</td><td>730d M57N</td><td>(GM22)</td><td>02.07.2001</td><td>-</td><td>14.800 kg</td></tr><tr><td>36116753241</td><td>7 Series</td><td>E65</td><td>Saloon</td><td>730d M57N2</td><td>(HM21)</td><td>02.07.2001</td><td>-</td><td>14.800 kg</td></tr><tr><td>36116753241</td><td>7 Series</td><td>E65</td><td>Saloon</td><td>730d M57N2</td><td>(HM22)</td><td>02.07.2001</td><td>-</td><td>14.800 kg</td></tr>",
"weight": 13.27,
"width": 0,
"depth": 0,
"height": 0,
"price": 510,
"cost_price": 530,
"retail_price": 0,
"sale_price": 0,
"map_price": 0,
"tax_class_id": 0,
"product_tax_code": "",
"calculated_price": 510,
"categories": [
162
],
"brand_id": 38,
"option_set_id": null,
"option_set_display": "right",
"inventory_level": 0,
"inventory_warning_level": 0,
"inventory_tracking": "product",
"reviews_rating_sum": 0,
"reviews_count": 0,
"total_sold": 0,
"fixed_cost_shipping_price": 0,
"is_free_shipping": false,
"is_visible": true,
"is_featured": false,
"related_products": [
-1
],
"warranty": "",
"bin_picking_number": "",
"layout_file": "",
"upc": "5060269195607",
"mpn": "36 11 6 753 241",
"gtin": "",
"date_last_imported": "2024-03-25T16:33:24+00:00",
"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": "2023-04-21T15:11:12+00:00",
"date_modified": "2024-09-02T10:20:57+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": "/1770/genuine-alloy-wheel-x1-19-star-spoke-95-front-rim-36-11-6-753-241/",
"is_customized": false
},
"base_variant_id": 1728,
"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": 1728,
"product_id": 1770,
"sku": "36116753241#Storesome",
"sku_id": null,
"price": 510,
"calculated_price": 510,
"sale_price": 0,
"retail_price": 0,
"map_price": 0,
"weight": 13.27,
"width": 0,
"height": 0,
"depth": 0,
"is_free_shipping": false,
"fixed_cost_shipping_price": 0,
"calculated_weight": 13.27,
"purchasing_disabled": false,
"purchasing_disabled_message": "",
"image_url": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/1770/images/20397/2466_36116753241__50789.1682520276.386.513.jpg?c=1",
"cost_price": 530,
"upc": "5060269195607",
"mpn": "36 11 6 753 241",
"gtin": "",
"inventory_level": 0,
"inventory_warning_level": 0,
"bin_picking_number": "",
"option_values": []
}
],
"images": [
{
"id": 20397,
"product_id": 1770,
"is_thumbnail": true,
"sort_order": 0,
"description": "Genuine Alloy Wheel x1 19\" Star-Spoke 95 Front Rim 36 11 6 753 241",
"image_file": "x/891/2466_36116753241__50789.jpg",
"url_zoom": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/1770/images/20397/2466_36116753241__50789.1682520276.1280.1280.jpg?c=1",
"url_standard": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/1770/images/20397/2466_36116753241__50789.1682520276.386.513.jpg?c=1",
"url_thumbnail": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/1770/images/20397/2466_36116753241__50789.1682520276.220.290.jpg?c=1",
"url_tiny": "https://cdn11.bigcommerce.com/s-i3kt5xjesl/products/1770/images/20397/2466_36116753241__50789.1682520276.44.58.jpg?c=1",
"date_modified": "2023-04-26T14:44:36+00:00"
}
],
"custom_fields": [
{
"id": 8678,
"name": "MPN",
"value": "36 11 6 753 241"
},
{
"id": 8679,
"name": "Placement",
"value": "Front"
},
{
"id": 8680,
"name": "Size",
"value": "19-inch"
},
{
"id": 8681,
"name": "Warranty",
"value": "2 Years"
},
{
"id": 62561,
"name": "Car Model",
"value": "7 Series"
},
{
"id": 62562,
"name": "Trim Level",
"value": "E65 Saloon"
},
{
"id": 62563,
"name": "Year",
"value": "2002"
}
]
},
"meta": {
"pagination": {
"total": 7848,
"count": 250,
"per_page": 250,
"current_page": 1,
"total_pages": 32,
"links": {
"next": "?limit=250&page=2&include=custom_fields%2Cimages%2Cvariants",
"current": "?limit=250&page=1&include=custom_fields%2Cimages%2Cvariants"
},
"too_many": false
}
}Mapping:
| Big | Commerce | Fields | Hemi Field | Required | Comment | |
|---|---|---|---|---|---|---|
| data | ||||||
| id | Product Account >Channel Item Id | Yes | If we have "base_variant_id": null we ignore this field | |||
| name | Product Account > Title |
AND Product Details > Inventory Title | Yes | This is the single product title and for all variants title | | | type | | | N/A | No | | | | sku | | | Product > SKU OR Product Account > Variation Group | Yes | If we have "base_variant_id": null we use it as Product Account > Variation Group <v1.3>If this field is empty in both cases (single or variation product) we want to skip it</v1.3> | | | description | | | Product Account > Description | No | This is for single product description and all variants description | | | weight | | | Product Details > Weight | No | If we have "base_variant_id": null we ignore this field
Our weight is in grams however BC use KGs so we need to convert it. (Example: 12.5kg) | | | width | | | Product Details > Width | No | If we have "base_variant_id": null we ignore this field | | | depth | | | Product Details > Length | No | If we have "base_variant_id": null we ignore this field | | | height | | | Product Details > Height | No | If we have "base_variant_id": null we ignore this field | | | price | | | Product Account > Price OR Product Account > RRP | Yes | If we have "base_variant_id": null we ignore this field If we have a sale_price we want to store this field as RRP | | | cost_price | | | Product Account > Original Price | No | If we have "base_variant_id": null we ignore this field | | | retail_price | | | N/A | No | | | | sale_price | | | Product Account > Price | No | If we have "base_variant_id": null we ignore this field | | | map_price | | | N/A | No | | | | tax_class_id | | | N/A | No | | | | product_tax_code | | | N/A | No | | | | calculated_price | | | N/A | No | | | | categories | | | <v1.5>Product Account > Primary Category ID OR Product Account BigCommerce> Additional Categories | Yes | This is the single product category and the category for all variants. Based on the taxonomy we want to map the value and store the path.
Please note if the product has more than one category assigned we want to store the additional categories in Product Account BigCommerce> Additional Categories.</v1.5> | | | brand_id | | | Product Account > Item Specific AND Product > Brand | No | This is the single product brand and the brand for all variants. Based on the taxonomy we want to map the value and store the name. When importing in Product Account > Item Specific we will have Name = Brand Value = Mapped brand name | | | option_set_id | | | N/A | No | | | | option_set_display | | | N/A | No | | | | inventory_level | | | Product Account > Quantity | No | If we have "base_variant_id": null we ignore this field | | | inventory_warning_level | | | N/A | No | | | | inventory_tracking | | | N/A | No | | | | reviews_rating_sum | | | N/A | No | | | | reviews_count | | | N/A | No | | | | total_sold | | | N/A | No | | | | fixed_cost_shipping_price | | | N/A | No | | | | is_free_shipping | | | N/A | No | | | | is_visible | | | N/A | No | | | | is_featured | | | Product Account Big Commerce > Feature Product | No | This is the single product feature product and the feature product for all variants. | | | related_products | | | N/A | No | | | | warranty | | | N/A | No | | | | bin_picking_number | | | N/A | No | | | | layout_file | | | N/A | No | | | | upc | | | Product Details > UPC | No | If we have "base_variant_id": null we ignore this field | | | mpn | | | Product Details > MPN | No | If we have "base_variant_id": null we ignore this field | | | gtin | | | Product Details > EAN | No | If we have "base_variant_id": null we ignore this field | | | search_keywords | | | N/A | No | | | | availability | | | N/A | No | | | | availability_description | | | N/A | No | | | | gift_wrapping_options_type | | | N/A | No | | | | gift_wrapping_options_list | | | N/A | No | | | | sort_order | | | N/A | No | | | | condition | | | Product Details > ConditionId | Yes | This is the single product condition and the condition for all variants.
Possible values are New | Used | Refurbished. The mapping is: Hemi New (with tags) = BC New Hemi Used (Pre-owned, Like new) = BC Used Hemi Manufacturer refurbished = BC Refurbished | | | is_condition_shown | | | N/A | No | | | | order_quantity_minimum | | | N/A | No | | | | order_quantity_maximum | | | N/A | No | | | | page_title | | | N/A | No | | | | meta_keywords | | | N/A | No | | | | meta_description | | | N/A | No | | | | date_created | | | N/A | No | | | | date_modified | | | N/A | No | | | | view_count | | | N/A | No | | | | preorder_release_date | | | N/A | No | | | | preorder_message | | | N/A | No | | | | is_preorder_only | | | N/A | No | | | | is_price_hidden | | | N/A | No | | | | price_hidden_label | | | N/A | No | | | | custom_url | | | | | | | | | url | | N/A | No | | | | | is_customized | | N/A | No | | | | base_variant_id | | | | No | Based on this field we will know if we have a variation or single product. If we have "base_variant_id": null this means the product is a variation if we receive an id like base_variant_id": 123 this means the product is single and we can ignore the variants node. | | | open_graph_type | | | N/A | No | | | | open_graph_title | | | N/A | No | | | | open_graph_description | | | N/A | No | | | | open_graph_use_meta_description | | | N/A | No | | | | open_graph_use_product_name | | | N/A | No | | | | open_graph_use_image | | | N/A | No | | | | variants | | | | | We will be using this node only when we have "base_variant_id": null.
Each variant in Hemi is a separate Product Details with Product Account. | | | | id | | Product Account Big Commerce > Variant Id | Yes | Required if we have variation | | | | product_id | | Product Account > Channel Item Id | Yes | | | | | sku | | Product Details > SKU | Yes | | | | | sku_id | | N/A | No | | | | | price | | Product Account > Price OR Product Account > RRP | Yes | If we have a sale_price we want to store this field as RRP | | | | calculated_price | | N/A | No | | | | | sale_price | | Product Account > Price | No | | | | | retail_price | | N/A | No | | | | | map_price | | N/A | No | | | | | weight | | Product Details > Weight | No | Our weight is in grams however BC use KGs so we need to convert it. (Example: 12.5kg) | | | | width | | Product Details > Width | No | | | | | height | | Product Details > Height | No | | | | | depth | | Product Details > Length | No | | | | | is_free_shipping | | N/A | No | | | | | fixed_cost_shipping_price | | N/A | No | | | | | calculated_weight | | N/A | No | | | | | purchasing_disabled | | N/A | No | | | | | purchasing_disabled_message | | N/A | No | | | | | image_url | | N/A | No | | | | | cost_price | | Product Account > Original Price | No | | | | | upc | | Product Details > UPC | No | | | | | mpn | | Product Details > MPN | No | | | | | gtin | | Product Details > EAN | No | | | | | inventory_level | | Product Account > Quantity | No | | | | | inventory_warning_level | | N/A | No | | | | | bin_picking_number | | N/A | No | | | | | option_values | | | | | | | | | id | N/A | No | | | | | | label | Product Account > Variation Specific | No | Product Account > Variation Specific Value | | | | | option_id | N/A | No | | | | | | option_display_name | Product Account > Variation Specific | No | Product Account > Variation Specific Name | | | images | | | | | | | | | id | | N/A | No | | | | | product_id | | N/A | No | | | | | is_thumbnail | | N/A | No | | | | | sort_order | | N/A | No | <v1.1>The image with the lowest sort_order is our Product > Main Image </v1.1> | | | | description | | N/A | No | | | | | image_file | | N/A | No | | | | | url_zoom | | N/A | No | | | | | url_standard | | Product > Main Image OR Product > More Picture URLs | Yes | We want to have the first image always stored as Product > Main Image and all other images should be added as Product > More Picture URLs. Please note we will store every image for every variant. | | | | url_thumbnail | | N/A | No | | | | | url_tiny | | N/A | No | | | | | date_modified | | N/A | No | | | | <v1.4>custom_fields | | | | | | | | | id | | Product Account Big Commerce > Custom Fields (Id) | No | We want to store the id only in Product Account Big Commerce > Custom Fields (Id) | | | | name | | Product Account Big Commerce > Custom Fields (Name) AND Product Account > Item Specifics (Name) | No | | | | | value | | Product Account Big Commerce > Custom Fields (Value) AND Product Account > Item Specifics (Value) | No | </v1.4> | | meta | | | | | No | | | | pagination | | | | | | | | | total | | N/A | No | | | | | count | | N/A | No | | | | | per_page | | N/A | No | | | | | current_page | | N/A | No | Used to track the page | | | | total_pages | | N/A | No | Used to track the page | | | | links | | | | | | | | | previous | N/A | No | Used to track the page | | | | | next | N/A | No | Used to track the page | | | | | current | N/A | No | Used to track the page | | | | too_many | | N/A | No | |
Apart from the mapping we will have to set as default also some of the internal fields because we are not receiving them from the marketplace.
| Hemi Field | Default Value |
|---|---|
| Product Account > Listing Status | Based on the quantity level either Active or Inactive |
| Product Account > Product Status | Product Published |
| Product Account > Dispatch Time Max | -1 |
| Product Account > Immediate Payment | Yes |
| Product Account > VAT | -1 |
Sample Error Response
Status 422
{
"status": 422,
"title": "The sub-resource: variantsr is not available on this resource.",
"type": "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes"
}It is almost impossible to receive an error but even if we do, we want to return it in the terminal and in the log