ArchiveStore OperationsCatalog V2 Products

Products V2

Deprecated

It is recommended to use the new Catalog Products.

Products

A product object represents a saleable item in the catalog.

Deprecated

Avoid using this API operation if possible. It will be removed in a future version.

NameTypeDescription
idintThe unique numerical ID of the product. Increments sequentially.
keyword_filterstring(This property is deprecated.)
namestringThe product name.
typeenumThe product type. One of:
physical – a physical stock unit.
digital – a digital download.
skustringUser-defined product code/stock keeping unit (SKU).
descriptiontextProduct description, which can include HTML formatting.
search_keywordstextA comma-separated list of keywords that can be used to locate the product when searching the store.
availability_descriptionstringAvailability text, displayed on the checkout page under the product title, telling the customer how long it will normally take to ship this product. E.g.: “Usually ships in 24 hours”.
pricedecimalThe product’s price. Should include, or exclude, tax based on the store settings.
cost_pricedecimalThe product’s cost price. Stored for reference only; not used or displayed anywhere on the store.
retail_pricedecimalThe product’s retail cost. If entered, this retail price will be shown on the product page.
sale_pricedecimalSale price. If entered, this will be used instead of value in the price field when calculating the product’s cost.
calculated_pricedecimalPrice as displayed to guests, adjusted for applicable sales and rules. (Cart price might incorporate further discounts for logged-in customers or customer groups.) Read-only.
sort_orderintPriority to give this product when included in product lists on category pages and in search results. Lower integers will place the product closer to the top of the results.
is_visiblebooleanFlag to determine whether or not the product should be displayed to customers browsing. If true, the product will be displayed. If false, the product will be hidden from view.
is_featuredbooleanFlag to determine whether the product should be included in the “featured products” panel for shoppers viewing the store.
related_productsstringDefaults to -1, which causes the store to automatically generate a list of related products. To manually specify the list of related products, include their IDs, separated by commas. For example: 3, 6, 7, 21.
inventory_levelintCurrent inventory level of the product. Simple inventory tracking must be enabled (see the inventory_tracking field) for this to take effect.
inventory_warning_levelintInventory Warning level for the product. When the product’s inventory level drops below this warning level, the store owner will be sent a notification. Simple inventory tracking must be enabled (see the inventory_tracking field) for this to take effect.
warrantytextWarranty information displayed on the product page. Can include HTML formatting.
weightdecimalWeight of the product, which can be used when calculating shipping costs.
widthdecimalWidth of the product, which can be used when calculating shipping costs.
heightdecimalHeight of the product, which can be used when calculating shipping costs.
depthdecimalDepth of the product, which can be used when calculating shipping costs.
fixed_cost_shipping_pricedecimalA fixed shipping cost for the product. If defined, this value will be used instead of normal shipping-cost calculation during checkout.
is_free_shippingbooleanFlag used to indicate whether or not the product has free shipping. If true, the shipping cost for the product will be zero.
inventory_trackingenumThe type of inventory tracking for the product. One of:
none – inventory levels will not be tracked.
simple – inventory levels will be tracked using the inventory_level and inventory_warning_level fields.
sku – inventory levels will be tracked based on individual product options, which maintain their own warning levels and inventory levels.
rating_totalintThe total rating for the product.
rating_countintThe total number of ratings the product has had.
total_soldintTotal quantity of this product sold through transactions.
date_createddateThe date of which the product was created.
brand_idintThe product’s brand
view_countintThe number of times the product has been viewed.
page_titlestringCustom title for the product’s page. If not defined, the product name will be used as the page title.
meta_keywordstextCustom meta keywords for the product page. If not defined, the store’s default keywords will be used.
meta_descriptiontextCustom meta description for the product page. If not defined, the store’s default meta description will be used.
layout_filestringDEPRECATED. The layout template file used to render this product. This field is writable only for stores with a Blueprint theme applied. For Stencil stores, use the V3 Custom Templates API.
is_price_hiddenbooleanThe default false value indicates that this product’s price should be shown on the product page. If set to true, the price will be hidden. (NOTE: To successfully set is_price_hidden to true, the availability value must be disabled.)
price_hidden_labelstringBy default, an empty string. If is_price_hidden is true, the value of price_hidden_label will be displayed instead of the price. (NOTE: To successfully set a non-empty string value for price_hidden_label, the availability value must be disabled.)
categoriesarrayAn array of IDs for the categories this product belongs to. When updating a product, if an array of categories is supplied, then all product categories will be overwritten. Does not accept more than 1,000 ID values.
date_modifieddateThe date that the product was last modified.
event_date_field_namestringName of the field to be displayed on the product page when selecting the event/delivery date.
event_date_typeenumOne of the following values:
none – Disables the event/delivery date requirement and field.
after – The selected date must fall either on, or after, the date specified in the event_date_start field.
before – The selected date must fall either before, or on, the date specified in the event_date_end field.
range – The selected date must fall between the event_date_start and event_date_end dates.
event_date_startdateWhen the product requires the customer to select an event/delivery date, this date is used as the “after” date.
event_date_enddateWhen the product requires the customer to select an event/delivery date, this date is used as the “before” date.
myob_asset_accountstringMYOB Asset Account.
myob_income_accountstringMYOB Income Account.
myob_expense_accountstringMYOB Expense/COS Account.
peachtree_gl_accountstringPeachtree General Ledger Account.
conditionenumThe product’s condition. Will be shown on the product page if the value of the is_condition_shown field is true. Possible values: New, Used, Refurbished.
is_condition_shownbooleanFlag used to determine whether the product’s condition will be shown to the customer on the product page.
preorder_release_datedatePre-order release date. See availability field for details on setting a product’s availability to accept pre-orders.
is_preorder_onlybooleanIf set to false, the product will not change its availability from preorder to available on the release date. Otherwise, on the release date the product’s availability/status will change to available.
preorder_messagestringCustom expected-date message to display on the product page. If undefined, the message defaults to the storewide setting. Can contain the %%DATE%% placeholder, which will be replaced with the release date.
order_quantity_minimumintThe minimum quantity an order must contain in order to purchase this product.
order_quantity_maximumintThe maximum quantity an order can contain when purchasing the product.
open_graph_typeenumType of product. Acceptable values are: product, album, book, drink, food, game, movie, song, tv_show
open_graph_titlestringTitle of the product. If not specified, the product’s name will be used instead.
open_graph_descriptiontextDescription to use for the product. If not specified, the meta_description will be used instead.
is_open_graph_thumbnailbooleanIf set to true, the product thumbnail image will be used as the open graph image.
upcstringThe product UPC code, which is used in feeds for shopping comparison sites.
date_last_importeddateThe date on which the product was last imported using the bulk importer.
option_set_idintThe ID of the option set applied to the product. (NOTE: To remove the option set from the product, set the value to null on update.)
tax_class_idintThe ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)
option_set_displayenumThe position on the product page where options from the option set will be displayed.
bin_picking_numberstringThe BIN picking number for the product.
custom_urlstringCustom URL (if set) overriding the structure dictated in the store’s settings. If no custom URL is set, this will contain the default URL.
primary_imageobjectAn image object, corresponding to the image that is set as the product’s thumbnail. This object includes that image’s id, plus four URL values identifying where to pull the image at different sizes:
standard_url is the image used in the product page’s image box.
tiny_url is the thumbnail image displayed below the product page’s image box.
thumbnail_url is used for product list-box images on category pages and in side panels.
zoom_url is either the original image size provided to BigCommerce, or the merchant-selected Product Zoom Image/Zoomed image size – whichever is smaller. (You can always access the product’s original image via the Product Images resource.)
availabilityenumAvailability of the product. Possible values:
available – the product can be purchased on the storefront.
disabled - the product is listed on the storefront, but cannot be purchased.
preorder – the product is listed for pre-orders.
brandresourceThe product’s brand
downloadsresourceTotal number of downloads for a downloadable product.
imagesresourceSee the Product Images resource for information.
discount_rulesresourceSee the Bulk Pricing resource for information.
configurable_fieldsresourceConfigurable fields for the product.
custom_fieldsresourceSee the Custom Fields resource for information.
videosresourceSee the Product Videos resource for information.
skusresourceStock Keeping Units for the product. See the Product SKU resource for the definition of a sku object.
rulesresourceRules that apply only to this product, based on the product’s option set. See the Product Rules resource for information.
option_setresourceSee the Option Sets resource for information.
optionsresourceOptions from the option set applied to the product. See the Product Options resource for information.
tax_classresourceAssigned tax class, when using a manual tax setup. This can be a number matching one of the tax classes set up in your store.
avalara_product_tax_coderesourceAccepts AvaTax System Tax Codes, which identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to Avalara Premium can calculate sales taxes more accurately.

Stores without Avalara Premium will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive.

For details, please see Avalara’s overview and FAQ on AvaTax System Tax Codes. You can also download codes as a zipfile of spreadsheets, or search or browse codes in Avalara’s Tax Code Search Tool. (These external links are subject to change.)

Gets the collection of products. (Default sorting is by product id, from lowest to highest.)

GET /stores/{store_hash}/v2/products

Filters

Filter parameters can be added to the URL query string to select specific products in the collection.

ParameterTypeExample
min_idint/api/v2/products?min_id={value}
max_idint/api/v2/products?max_id={value}
namestring/api/v2/products?name={value}
keyword_filterstring/api/v2/products?keyword_filter={value}
descriptionstring/api/v2/products?description={value}
skustring/api/v2/products?sku={value}
conditionstring/api/v2/products?condition={value}
availabilitystring/api/v2/products?availability={value}
brand_idstring/api/v2/products?brand_id={value}
min_date_createddateTime or date/api/v2/products?min_date_created={value}
max_date_createddateTime or date/api/v2/products?max_date_created={value}
min_date_modifieddateTime or date/api/v2/products?min_date_modified={value}
max_date_modifieddateTime or date/api/v2/products?max_date_modified={value}
min_date_last_importeddate/api/v2/products?min_date_last_imported={value}
max_date_last_importeddate/api/v2/products?max_date_last_imported={value}
min_pricedecimal/api/v2/products?min_price={value}
max_pricedecimal/api/v2/products?max_price={value}
min_number_soldint/api/v2/products?min_number_sold={value}
max_number_soldint/api/v2/products?max_number_sold={value}
is_visiblestring/api/v2/products?is_visible={value}
is_featuredstring/api/v2/products?is_featured={value}
min_inventory_levelint/api/v2/products?min_inventory_level={value}
max_inventory_levelint/api/v2/products?max_inventory_level={value}
include_skuboolean/api/v2/products?include_sku={value}
categorystring/api/v2/products?category={value}
product_tax_codestring/api/v2/products?product_tax_code={value}

Pagination

Parameters can be added to the URL query string to paginate the collection. The maximum limit is 250. If a limit isn’t provided, up to 50 products are returned by default.

ParameterTypeExample
Pageint/api/v2/products?page={number}
Limitint/api/v2/products?limit={count}

Note

You can filter the retrieved fields by appending one of the following options to your request:

  • ?include=
  • ?include=@summary
  • ?exclude=

For details, syntax, and examples, please see the Get a Product operation.

Response

Example JSON returned in the response:

[
  {
    "id": 32,
    "keyword_filter": null,
    "name": "[Sample] Tomorrow is today, Red printed scarf",
    "type": "physical",
    "sku": "",
    "description": "Densely pack your descriptions with useful information and watch products fly off the shelf.",
    "search_keywords": null,
    "availability_description": "",
    "price": "89.0000",
    "cost_price": "0.0000",
    "retail_price": "0.0000",
    "sale_price": "0.0000",
    "calculated_price": "89.0000",
    "sort_order": 0,
    "is_visible": true,
    "is_featured": true,
    "related_products": "-1",
    "inventory_level": 0,
    "inventory_warning_level": 0,
    "warranty": null,
    "weight": "0.3000",
    "width": "0.0000",
    "height": "0.0000",
    "depth": "0.0000",
    "fixed_cost_shipping_price": "10.0000",
    "is_free_shipping": false,
    "inventory_tracking": "none",
    "rating_total": 0,
    "rating_count": 0,
    "total_sold": 0,
    "date_created": "Fri, 21 Sep 2012 02:31:01 +0000",
    "brand_id": 17,
    "view_count": 4,
    "page_title": "",
    "meta_keywords": null,
    "meta_description": null,
    "layout_file": "product.html",
    "is_price_hidden": false,
    "price_hidden_label": "",
    "categories": [
      14
    ],
    "date_modified": "Mon, 24 Sep 2012 01:34:57 +0000",
    "event_date_field_name": "Delivery Date",
    "event_date_type": "none",
    "event_date_start": "",
    "event_date_end": "",
    "myob_asset_account": "",
    "myob_income_account": "",
    "myob_expense_account": "",
    "peachtree_gl_account": "",
    "condition": "New",
    "is_condition_shown": false,
    "preorder_release_date": "",
    "is_preorder_only": false,
    "preorder_message": "",
    "order_quantity_minimum": 0,
    "order_quantity_maximum": 0,
    "open_graph_type": "product",
    "open_graph_title": "",
    "open_graph_description": null,
    "is_open_graph_thumbnail": true,
    "upc": null,
    "avalara_product_tax_code": "",
    "date_last_imported": "",
    "option_set_id": null,
    "tax_class_id": 0,
    "option_set_display": "right",
    "bin_picking_number": "",
    "custom_url": "/tomorrow-is-today-red-printed-scarf/",
    "primary_image": {
      "id": 247,
      "zoom_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.1280.1280.jpg?c=1",
      "thumbnail_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.220.290.jpg?c=1",
      "standard_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.386.513.jpg?c=1",
      "tiny_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.44.58.jpg?c=1"
    },
    "availability": "available",
    "brand": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/brands/17.json",
      "resource": "/brands/17"
    },
    "images": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/images.json",
      "resource": "/products/32/images"
    },
    "discount_rules": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/discountrules.json",
      "resource": "/products/32/discountrules"
    },
    "configurable_fields": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/configurablefields.json",
      "resource": "/products/32/configurablefields"
    },
    "custom_fields": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/customfields.json",
      "resource": "/products/32/customfields"
    },
    "videos": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/videos.json",
      "resource": "/products/32/videos"
    },
    "skus": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/skus.json",
      "resource": "/products/32/skus"
    },
    "rules": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/rules.json",
      "resource": "/products/32/rules"
    },
    "option_set": null,
    "options": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/options.json",
      "resource": "/products/32/options"
    },
    "tax_class": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/taxclasses/0.json",
      "resource": "/taxclasses/0"
    }
  },
  {
    "id": 33,
    "keyword_filter": null,
    "name": "[Sample] Anna, multi-colored bangles",
    "type": "physical",
    "sku": "",
    "description": "One of the best things you can do to make your store successful is invest some time in writing great product descriptions.</p>",
    "search_keywords": null,
    "availability_description": "",
    "price": "59.0000",
    "cost_price": "0.0000",
    "retail_price": "0.0000",
    "sale_price": "0.0000",
    "calculated_price": "59.0000",
    "sort_order": 0,
    "is_visible": true,
    "is_featured": true,
    "related_products": "-1",
    "inventory_level": 0,
    "inventory_warning_level": 0,
    "warranty": null,
    "weight": "0.5000",
    "width": "0.0000",
    "height": "0.0000",
    "depth": "0.0000",
    "fixed_cost_shipping_price": "0.0000",
    "is_free_shipping": false,
    "inventory_tracking": "none",
    "rating_total": 0,
    "rating_count": 0,
    "total_sold": 0,
    "date_created": "Fri, 21 Sep 2012 02:46:41 +0000",
    "brand_id": 18,
    "view_count": 12,
    "page_title": "",
    "meta_keywords": null,
    "meta_description": null,
    "layout_file": "product.html",
    "is_price_hidden": false,
    "price_hidden_label": "",
    "categories": [
      14
    ],
    "date_modified": "Mon, 24 Sep 2012 05:28:02 +0000",
    "event_date_field_name": "Delivery Date",
    "event_date_type": "none",
    "event_date_start": "",
    "event_date_end": "",
    "myob_asset_account": "",
    "myob_income_account": "",
    "myob_expense_account": "",
    "peachtree_gl_account": "",
    "condition": "New",
    "is_condition_shown": false,
    "preorder_release_date": "",
    "is_preorder_only": false,
    "preorder_message": "",
    "order_quantity_minimum": 0,
    "order_quantity_maximum": 0,
    "open_graph_type": "product",
    "open_graph_title": "",
    "open_graph_description": null,
    "is_open_graph_thumbnail": true,
    "upc": null,
    "avalara_product_tax_code": "",
    "date_last_imported": "",
    "option_set_id": 13,
    "tax_class_id": 0,
    "option_set_display": "right",
    "bin_picking_number": "",
    "custom_url": "/anna-multi-colored-bangles/",
    "primary_image": {
      "id": 245,
      "zoom_url": "https://cdn.url.path/bcapp/et7xe3pz/products/33/images/245/HERO_cocolee_anna_92865__20303.1393831046.1280.1280.jpg?c=1",
      "thumbnail_url": "https://cdn.url.path/bcapp/et7xe3pz/products/33/images/245/HERO_cocolee_anna_92865__20303.1393831046.220.290.jpg?c=1",
      "standard_url": "https://cdn.url.path/bcapp/et7xe3pz/products/33/images/245/HERO_cocolee_anna_92865__20303.1393831046.386.513.jpg?c=1",
      "tiny_url": "https://cdn.url.path/bcapp/et7xe3pz/products/33/images/245/HERO_cocolee_anna_92865__20303.1393831046.44.58.jpg?c=1"
    },
    "availability": "available",
    "brand": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/brands/18.json",
      "resource": "/brands/18"
    },
    "images": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/images.json",
      "resource": "/products/33/images"
    },
    "discount_rules": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/discountrules.json",
      "resource": "/products/33/discountrules"
    },
    "configurable_fields": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/configurablefields.json",
      "resource": "/products/33/configurablefields"
    },
    "custom_fields": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/customfields.json",
      "resource": "/products/33/customfields"
    },
    "videos": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/videos.json",
      "resource": "/products/33/videos"
    },
    "skus": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/skus.json",
      "resource": "/products/33/skus"
    },
    "rules": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/rules.json",
      "resource": "/products/33/rules"
    },
    "option_set": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/optionsets/13.json",
      "resource": "/optionsets/13"
    },
    "options": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/33/options.json",
      "resource": "/products/33/options"
    },
    "tax_class": {
      "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/taxclasses/0.json",
      "resource": "/taxclasses/0"
    }
  }
]

Gets a product.

GET /stores/{store_hash}/v2/products/{id}

Note

You can filter the retrieved fields by appending one of the following options to your request:

  • ?include=
  • ?include=@summary
  • ?exclude=

In particular, you can reduce payload size, and improve performance, by excluding the description field.

Mandatory Fields

However, the following fields are always present on product API requests, and cannot be excluded:

  • id
  • name
  • date_modified
  • primary_image

include

The following sample request will retrieve only the specified date_created, price, and cost_price fields, plus the mandatory fields listed just above:

https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32?include=date_created,price,cost_price

Here is a corresponding sample response:

{
    "id": 32,
    "name": "[Sample] Tomorrow is today, Red printed scarf",
    "price": "89.0000",
    "cost_price": "0.0000",
    "date_created": "Fri, 21 Sep 2012 02:31:01 +0000",
    "date_modified": "Thu, 10 Dec 2015 21:10:17 +0000",
    "primary_image": {
        "id": 247,
        "tiny_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.60.90.jpg?c=1",
        "standard_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.500.750.jpg?c=1",
        "thumbnail_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.190.285.jpg?c=1",
        "zoom_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.1280.1280.jpg?c=1"
    },
    "metadata": []
}

include=@summary

The ?include=@summary option retrieves the following predefined subset of fields, in addition to the mandatory fields listed above:

  • availability
  • calculated_price
  • inventory_tracking
  • sku
  • inventory_level
  • inventory_warning_level
  • is_visible
  • is_featured

Here is a sample request with the ?include=@summary option appended:

https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32?include=@summary

Here is a corresponding sample response:

{
    "id": 32,
    "name": "[Sample] Tomorrow is today, Red printed scarf",
    "sku": "TTRPS",
    "calculated_price": "89.0000",
    "is_visible": true,
    "is_featured": true,
    "inventory_level": 0,
    "inventory_warning_level": 0,
    "inventory_tracking": "none",
    "date_modified": "Thu, 10 Dec 2015 21:10:17 +0000",
    "availability": "available",
    "primary_image": {
        "id": 247,
        "tiny_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.60.90.jpg?c=1",
        "standard_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.500.750.jpg?c=1",
        "thumbnail_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.190.285.jpg?c=1",
        "zoom_url": "https://cdn.url.path/bcapp/k84uuwpy/products/32/images/247/in_123__14581.1348449270.1280.1280.jpg?c=1"
    },
    "metadata": []
}

exclude

The ?exclude= option excludes one or more specified fields. However, you cannot exclude the mandatory id, name, date_modified, or primary_image fields.

Here is a sample request with the ?exclude= option appended:

https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32?exclude=description

We have omitted the corresponding sample response. However, the following section shows a complete sample response for a request submitted with no ?include or ?exclude option. (The effect of the ?exclude=description option shown above would be to omit the "description": field shown as the sixth field below.)

Response

Example JSON returned in the response:

{
  "id": 32,
  "keyword_filter": null,
  "name": "[Sample] Tomorrow is today, Red printed scarf",
  "type": "physical",
  "sku": "",
  "description": "Densely pack your descriptions with useful information and watch products fly off the shelf.",
  "search_keywords": null,
  "availability_description": "",
  "price": "89.0000",
  "cost_price": "0.0000",
  "retail_price": "0.0000",
  "sale_price": "0.0000",
  "calculated_price": "89.0000",
  "sort_order": 0,
  "is_visible": true,
  "is_featured": true,
  "related_products": "-1",
  "inventory_level": 0,
  "inventory_warning_level": 0,
  "warranty": null,
  "weight": "0.3000",
  "width": "0.0000",
  "height": "0.0000",
  "depth": "0.0000",
  "fixed_cost_shipping_price": "10.0000",
  "is_free_shipping": false,
  "inventory_tracking": "none",
  "rating_total": 0,
  "rating_count": 0,
  "total_sold": 0,
  "date_created": "Fri, 21 Sep 2012 02:31:01 +0000",
  "brand_id": 17,
  "view_count": 4,
  "page_title": "",
  "meta_keywords": null,
  "meta_description": null,
  "layout_file": "product.html",
  "is_price_hidden": false,
  "price_hidden_label": "",
  "categories": [
    14
  ],
  "date_modified": "Mon, 24 Sep 2012 01:34:57 +0000",
  "event_date_field_name": "Delivery Date",
  "event_date_type": "none",
  "event_date_start": "",
  "event_date_end": "",
  "myob_asset_account": "",
  "myob_income_account": "",
  "myob_expense_account": "",
  "peachtree_gl_account": "",
  "condition": "New",
  "is_condition_shown": false,
  "preorder_release_date": "",
  "is_preorder_only": false,
  "preorder_message": "",
  "order_quantity_minimum": 0,
  "order_quantity_maximum": 0,
  "open_graph_type": "product",
  "open_graph_title": "",
  "open_graph_description": null,
  "is_open_graph_thumbnail": true,
  "upc": null,
  "avalara_product_tax_code": "",
  "date_last_imported": "",
  "option_set_id": null,
  "tax_class_id": 0,
  "option_set_display": "right",
  "bin_picking_number": "",
  "custom_url": "/tomorrow-is-today-red-printed-scarf/",
  "primary_image": {
    "id": 247,
    "zoom_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.1280.1280.jpg?c=1",
    "thumbnail_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.220.290.jpg?c=1",
    "standard_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.386.513.jpg?c=1",
    "tiny_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.44.58.jpg?c=1"
  },
  "availability": "available",
  "brand": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/brands/17.json",
    "resource": "/brands/17"
  },
  "images": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/images.json",
    "resource": "/products/32/images"
  },
  "discount_rules": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/discountrules.json",
    "resource": "/products/32/discountrules"
  },
  "configurable_fields": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/configurablefields.json",
    "resource": "/products/32/configurablefields"
  },
  "custom_fields": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/customfields.json",
    "resource": "/products/32/customfields"
  },
  "videos": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/videos.json",
    "resource": "/products/32/videos"
  },
  "skus": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/skus.json",
    "resource": "/products/32/skus"
  },
  "rules": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/rules.json",
    "resource": "/products/32/rules"
  },
  "option_set": null,
  "options": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/products/32/options.json",
    "resource": "/products/32/options"
  },
  "tax_class": {
    "url": "https://store-et7xe3pz.mybigcommerce.com/api/v2/taxclasses/0.json",
    "resource": "/taxclasses/0"
  }
}

Gets a count of products.

GET /stores/{store_hash}/v2/products/count

Filters

Filter parameters can be added to the URL query string to select specific products in the collection.

ParameterTypeExample
min_idint/api/v2/products?min_id={value}
max_idint/api/v2/products?max_id={value}
namestring/api/v2/products?name={value}
keyword_filterstring/api/v2/products?keyword_filter={value}
descriptionstring/api/v2/products?description={value}
skustring/api/v2/products?sku={value}
conditionstring/api/v2/products?condition={value}
availabilitystring/api/v2/products?availability={value}
brand_idstring/api/v2/products?brand_id={value}
min_date_createddate/api/v2/products?min_date_created={value}
max_date_createddate/api/v2/products?max_date_created={value}
min_date_modifieddate/api/v2/products?min_date_modified={value}
max_date_modifieddate/api/v2/products?max_date_modified={value}
min_date_last_importeddate/api/v2/products?min_date_last_imported={value}
max_date_last_importeddate/api/v2/products?max_date_last_imported={value}
min_pricedecimal/api/v2/products?min_price={value}
max_pricedecimal/api/v2/products?max_price={value}
min_number_soldint/api/v2/products?min_number_sold={value}
max_number_soldint/api/v2/products?max_number_sold={value}
is_visiblestring/api/v2/products?is_visible={value}
is_featuredstring/api/v2/products?is_featured={value}
min_inventory_levelint/api/v2/products?min_inventory_level={value}
max_inventory_levelint/api/v2/products?max_inventory_level={value}
include_skuboolean/api/v2/products?include_sku={value}
categorystring/api/v2/products?category={value}
product_tax_codestring/api/v2/products?product_tax_code={value}

Note

If no filters are applied, the total number of products is returned.

Response

Example JSON returned in the response:

{
  "count": 44
}

Creates a new product. The example request shows how to create a basic product by sending a product object with the minimum required properties.

POST /stores/{store_hash}/v2/products

Read-only Properties

The following properties of the product are read-only. If one or more of these properties are included in the request, it will be rejected.

  • id
  • calculated_price
  • brand
  • images
  • discount_rules
  • configurable_fields
  • custom_fields
  • primary_image
  • videos
  • rules
  • option_set
  • options
  • tax_class

Requirements

The following properties of the product are required. The request won’t be fulfilled unless these properties are valid.

  • name
  • price
  • categories
  • type
  • availability
  • weight

Note

Create a request by sending a product object with the minimum required properties:

{
    "name": "Plain T-Shirt",
    "type": "physical",
    "description": "This timeless fashion staple will never go out of style!",
    "price": "29.99",
    "categories": [18],
    "availability": "available",
    "weight": "0.5"
}

When the is_visible property is not provided, the product’s visibility is false by default.

To make newly created products immediately visible on the storefront, you must set is_visible to true when you create each product.

You may encounter a case where product information was updated successfully, but related inventory data failed to update. In such cases, BigCommerce will return a 207 status along with the object as updated and a descriptive error message.

207 Multi-Status

To maximize system performance, BigCommerce caps the number of categories to which a product can belong. The maximum is 1,000. If your POST includes an array of more than 1,000 categories ID values, BigCommerce will return a 403 error:

403 Access Denied/Forbidden

If automatic tax is enabled on the store, the value of tax_class_id will have no effect on the calculation of taxes.

Updates an existing product.

PUT /stores/{store_hash}/v2/products/{id}

Read-only Properties

The following properties of the product are read-only. If one or more of these properties are included in the request, it will be rejected.

  • id
  • rating_total
  • rating_count
  • number_sold
  • date_created
  • date_modified
  • date_last_imported
  • calculated_price
  • brand
  • images
  • discount_rules
  • configurable_fields
  • custom_fields
  • primary_image
  • videos
  • rules
  • option_set
  • options
  • tax_class

Requirements

There are no required properties when updating a product.

Note

To update a product, set one or more product properties in the PUT request:

{
    "custom_url": "/plain-tshirt/",
    "is_visible": true
}

For example, you can use a PUT to link a product to an option set:

{
    "option_set_id": 14
}

Invalid property values will produce a 400 Bad Request error response:

Request

{
    "condition": "Worn"
}

Response

400 Bad Request

Trying to set read-only properties will also produce a 400 Bad Request error response:

Request

{
    "number_sold": 99
}

Response

400 Bad Request

You may encounter a case where product information was updated successfully, but related inventory data failed to update. In such cases, BigCommerce will return a 207 status along with the object as updated and a descriptive error message.

207 Multi-Status

To maximize system performance, BigCommerce caps the maximum number of categories to which a product can belong, at 1,000. If your PUT includes an array of more than 1,000 categories ID values, BigCommerce will return a 403 error:

403 Access Denied/Forbidden

If automatic tax is enabled on the store, the value of tax_class_id will have no effect on the calculation of taxes.

Deletes a product.

DELETE /stores/{store_hash}/v2/products/{id}

Note

Successful deletion of a product returns a 204 No Content response:

204 No Content

Deletes all products from the store.

DELETE /stores/{store_hash}/v2/products

Note

Successful deletion of all products returns a 204 No Content response:

204 No Content