NAV
Subscribe to developer updates

v3 API Reference

Object References

Activate

Request definition for activation endpoint.

Name Type Description
variation_id string The variation identifier.
which string Which configuration to use. Acceptable values: original, last_activated, last_created.

Adjuster

Price and weight adjusters for product variants.

Name Type Description
adjuster (optional) string The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. Acceptable values: relative, percentage.
adjuster_value (optional) number The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront.

AppliedCoupon

A coupon applied to a cart.

Name Type Description
id string The coupon ID.
code string The coupon code.
name string The coupon name, as specified by the merchant.
slug string Automatically-generated description for the discount.
coupon_type string A key name that identifies the type of coupon.
discounted_amount number The discounted amount applied within a given context.

AppliedDiscount

A discount applied to a cart.

Name Type Description
id number ID of the applied discount.
discounted_amount number The discounted amount applied within a given context.

AVSResult

Address Verification Service result from payment gateway.

Name Type Description
code (optional) string AVS code.
message (optional) string AVS message.
street_match (optional) string AVS Code for street matching result.
postal_match (optional) string AVS Code for postal matching result.

BaseError

Error payload for the BigCommerce API.

Name Type Description
status (optional) integer The HTTP status code.
title (optional) string The error title describing the particular error.
type (optional) string
instance (optional) string

BaseItem

Base object for purchasable items in a cart.

Name Type Required Description
id string false ID for the line item.
variant_id number false ID for the product variant.
product_id number false ID for the product.
name string false The product’s name.
url string (URI format) false The product’s URL.
quantity number true Quantity in this line item.
is_taxable boolean false Whether this item is taxable.
url string (URI format) false Product image’s URL.
discounts array false Array of AppliedDiscount objects.
coupons array false Array of AppliedCoupon objects.
discount_amount number false The total value of all discounts applied to this item.
coupon_amount number false The total value of all coupons applied to this item.
list_price number false Item’s list price, as quoted by the manufacturer/distributor.
sale_price number false Item’s price after all discounts are applied. (The final price before tax calculation.)
extended_list_price number false Item’s list price multiplied by the quantity.
extended_sale_price number false Item’s sale price multiplied by the quantity.

Body

Request definition for activation endpoint.

Name Type Description
variation_id string The variation identifier.
which string Which configuration to use.

Enum: original, last_activated, last_created.

Brand

Common Brand properties.

Name Type Description
name (optional) string The name of the brand. If used, must be unique.
page_title (optional) string The title shown in the browser while viewing the brand.
meta_keywords (optional) string array Comma-separated list of meta keywords to include in the HTML.
meta_description (optional) string A meta description to include.
search_keywords (optional) string A comma-separated list of keywords that can be used to locate this brand.
image_url (optional) string Image URL used for this category on the storefront. Images can be uploaded via form file post to /brands/{brandId}/image, or by providing a publicly accessible URL in this field.
id (optional) integer The unique numeric ID of the brand; increments sequentially.

BulkPricingRule

Common BulkPricingRule properties.

Name Type Description
quantity_min (optional) integer The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero.
quantity_max (optional) integer The maximum inclusive quantity of a product to satisfy this rule. Must be greater than the quantity_min value – unless this field has a value of 0 (zero), in which case there will be no maximum bound for this rule.
type (optional) string The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product.
amount (optional) number (double float) The value of the adjustment by the bulk pricing rule.
id (optional) integer The ID of the bulk pricing rule.

CartEntity

A cart contains a collection of items, prices, discounts, etc. It does not contain customer-related data.

Name Type Description
id string Cart ID, provided after creating a cart with a POST.
currency object A Currency object.
is_tax_included boolean Whether tax is included in cart amounts.
base_amount number Cost of cart’s contents, before applying discounts.
discount_amount number Discounted amount.
cart_amount number Sum of line-items amounts, minus cart-level discounts and coupons. This amount includes taxes (where applicable).
coupons array Array of AppliedCoupon objects.
discounts array Array of AppliedDiscount objects.
created_time ISO-8601 string. Time when the cart was created.
updated_time ISO-8601 string. Time when the cart was last updated.

CatalogSummary

A BigCommerce Catalog Summary object describes a lightweight summary of the catalog.

Name Type Description
inventory_count (optional) integer A count of all inventory items in the catalog.
inventory_value (optional) number (double float) Total value of store’s inventory.
primary_category_id (optional) integer ID of the category containing the most products.
primary_category_name (optional) string Name of the category containing the most products.

catalogproducts_bulk_pricing_rules

Common BulkPricingRule properties.

Name Type Description
quantity_min (optional) integer The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero.
quantity_max (optional) integer The maximum inclusive quantity of a product to satisfy this rule. Must be greater than the quantity_min value – unless this field has a value of 0 (zero), in which case there will be no maximum bound for this rule.
type (optional) string The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product.
amount (optional) number (double float) The value of the adjustment by the bulk pricing rule.

catalogproducts_custom_fields

Common CustomField properties.

Name Type Description
name (optional) string The name of the field, shown on the storefront, orders, etc.
value (optional) string The name of the field, shown on the storefront, orders, etc.

catalogproducts_option_values

Common OptionValueProduct properties.

Name Type Description
option_display_name (optional) string The name of the option.
label (optional) string The label of the option value.

catalogproducts_variants

Common Variant properties.

Name Type Description
cost_price (optional) number (double float) The cost price of the variant.
price (optional) number (double float) This variant’s base price on the storefront. If this value is null, the product’s default price (set in the Product resource’s price field) will be used as the base price.
weight (optional) number (double float) This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
width (optional) number (double float) Width of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default width (set in the Product resource’s width field) will be used as the base width.
height (optional) number (double float) Height of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default height (set in the Product resource’s height field) will be used as the base height.
depth (optional) number (double float) Depth of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default depth (set in the Product resource’s depth field) will be used as the base depth.
is_free_shipping (optional) boolean Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.
fixed_cost_shipping_price (optional) number (double float) A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
purchasing_disabled (optional) boolean If true, this variant will not be purchasable on the storefront.
purchasing_disabled_message (optional) string If purchasing_disabled is true, this message should show on the storefront when the variant is selected.
image_url (optional) string The image that will be displayed when this variant is selected on the storefront. When updating a SKU image, send the publicly accessible URL. Supported image formats are JPEG, PNG, and GIF. Generic product images not specific to the variant should be stored on the product.
upc (optional) string The UPC code used in feeds for shopping comparison sites and external channel integrations.
inventory_level (optional) integer Inventory level for the variant, which is used when the product’s inventory_tracking is set to variant.
inventory_warning_level (optional) integer When the variant hits this inventory level, it is considered low stock.
bin_picking_number (optional) string Identifies where in a warehouse the variant is located.
product_id (optional) integer
sku (optional) string
option_values (optional) array of catalogproducts_option_values

catalogproductsproduct_id_variants

Common Variant properties.

Name Type Description
cost_price (optional) number (double float) The cost price of the variant.
price (optional) number (double float) This variant’s base price on the storefront. If this value is null, the product’s default price (set in the Product resource’s price field) will be used as the base price.
weight (optional) number (double float) This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
width (optional) number (double float) Width of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default width (set in the Product resource’s width field) will be used as the base width.
height (optional) number (double float) Height of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default height (set in the Product resource’s height field) will be used as the base height.
depth (optional) number (double float) Depth of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default depth (set in the Product resource’s depth field) will be used as the base depth.
is_free_shipping (optional) boolean Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.
fixed_cost_shipping_price (optional) number (double float) A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
purchasing_disabled (optional) boolean If true, this variant will not be purchasable on the storefront.
purchasing_disabled_message (optional) string If purchasing_disabled is true, this message should show on the storefront when the variant is selected.
image_url (optional) string The image that will be displayed when this variant is selected on the storefront. When updating a SKU image, send the publicly accessible URL. Supported image formats are JPEG, PNG, and GIF. Generic product images not specific to the variant should be stored on the product.
upc (optional) string The UPC code used in feeds for shopping comparison sites and external channel integrations.
inventory_level (optional) integer Inventory level for the variant, which is used when the product’s inventory_tracking is set to variant.
inventory_warning_level (optional) integer When the variant hits this inventory level, it is considered low stock.
bin_picking_number (optional) string Identifies where in a warehouse the variant is located.
product_id (optional) integer
sku (optional) string

catalogproductsproduct_idcomplexrules_conditions

Common ComplexRuleCondition properties.

Name Type Description
id (optional) integer The unique numeric ID of the rule condition; increments sequentially.
rule_id (optional) integer The unique numeric ID of the rule with which the condition is associated.
modifier_id (optional) integer The unique numeric ID of the modifier with which the rule condition is associated.
modifier_value_id (optional) integer The unique numeric ID of the modifier value with which the rule condition is associated.
variant_id (optional) integer The unique numeric ID of the variant with which the rule condition is associated.

catalogproductsproduct_idvariants_option_values

The model for a POST to create option values with a variant.

Name Type Description
id (optional) integer
option_id (optional) integer

Category

Common Category properties.

Name Type Description
parent_id (optional) integer The unique numeric ID of the category’s parent. This field controls where the category sits in the tree of categories that organize the catalog.
name (optional) string The name displayed for the category. Name is unique with respect to the category’s siblings.
description (optional) string The product description, which can include HTML formatting.
views (optional) integer Number of views the category has on the storefront.
sort_order (optional) integer Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be.
page_title (optional) string Custom title for the category page, if not defined the category name will be used as the meta title.
search_keywords (optional) string A comma-separated list of keywords that can be used to locate the category when searching the store.
meta_keywords (optional) string array Custom meta keywords for the category page. If not defined, the store’s default keywords will be used. Must post as an array like: [“awesome”,“sauce”].
meta_description (optional) string Custom meta description for the category page. If not defined, the store’s default meta description will be used.
layout_file (optional) string The layout template file used to render this category.
is_visible (optional) boolean Flag to determine whether the product should be displayed to customers browsing the store. If true, the category will be displayed. If false, the category will be hidden from view.
default_product_sort (optional) string Determines how the products are sorted on category page load.

Enum: use_store_settings, featured, newest, best_selling, alpha_asc, alpha_desc, avg_customer_review, price_asc, price_desc.
image_url (optional) string Image URL used for this category on the storefront. Images can be uploaded via form file post to /categories/{categoryId}/image, or by providing a publicly accessible URL in this field.
custom_url (optional) inline_response_200_27_custom_url

CategoryNode

A BigCommerce category node object. Used to reflect parent <> child category relationships.

Name Type Description
id (optional) integer The unique numeric ID of the category; increments sequentially.
parent_id (optional) integer The unique numeric ID of the category’s parent. This field controls where the category sits in the tree of categories that organize the catalog.
name (optional) string The name displayed for the category. Name is unique with respect to the category’s siblings.
is_visible (optional) boolean Flag to determine whether the product should be displayed to customers browsing the store. If true, the category will be displayed. If false, the category will be hidden from view.
url (optional) string The custom URL for the category on the storefront.
children (optional) array of CategoryNode objects The list of children of the category.

CollectionMeta

Data about the response, including pagination and collection totals.

Name Type Description
pagination (optional) inline_response_200_meta_pagination [Description to follow.]

ComplexRule

Common ComplexRule properties.

Name Type Description
product_id (optional) integer The unique numeric ID of the product with which the rule is associated; increments sequentially.
sort_order (optional) integer Priority this rule will be given, when making adjustments to the product properties.
enabled (optional) boolean Flag for determining whether the rule is to be used when adjusting a product’s price, weight, image, or availabilty.
stop (optional) boolean Flag for determining whether other rules should not be applied after this rule has been applied.
purchasing_disabled (optional) boolean Flag for determining whether the rule should disable purchasing of a product when the conditions are applied.
purchasing_disabled_message (optional) string Message displayed on the storefront when a rule disables the purchasing of a product.
purchasing_hidden (optional) boolean Flag for determining whether the rule should hide purchasing of a product when the conditions are applied.
price_adjuster (optional) inline_response_200_15_adjusters_price
weight_adjuster (optional) inline_response_200_15_adjusters_price
id (optional) integer The unique numeric ID of the rule; increments sequentially.
image_url (optional) string The URL for an image displayed on the storefront when the conditions are applied.
conditions (optional) array of inline_response_200_19_conditions

ComplexRuleCondition

Common ComplexRuleCondition properties.

Name Type Description
id (optional) integer The unique numeric ID of the rule condition; increments sequentially.
rule_id (optional) integer The unique numeric ID of the rule with which the condition is associated.
modifier_id (optional) integer The unique numeric ID of the modifier with which the rule condition is associated.
modifier_value_id (optional) integer The unique numeric ID of the modifier value with which the rule condition is associated.
variant_id (optional) integer The unique numeric ID of the variant with which the rule condition is associated.
combination_id (optional) integer (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or of the Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3.

ContactEntity

Cart API object representing a contact person and their email address.

Name Type Description
name string Name of the person.
email string An address in email “@” format.

CreditCard

A credit-card model.

Name Type Description
card_type (optional) string The credit-card type: Visa, MasterCard, etc.
card_iin (optional) string The IIN of a credit-card number.
card_last4 (optional) string The last 4 digits of a credit-card number.

Currency

Cart API currency object. This will always match between cart and checkout.

Name Type Description
code string An ISO-4217 currency code.

Custom

Custom payment from manual order.

Name Type Description
payment_method (optional) string Text entered for payment in the control panel.

CustomField

Common CustomField properties.

Name Type Description
name (optional) string The name of the field, shown on the storefront, orders, etc.
value (optional) string The name of the field, shown on the storefront, orders, etc.
id (optional) integer The unique numeric ID of the custom field; increments sequentially.

CustomUrlCategory

The custom URL for the category on the storefront.

Name Type Description
url (optional) string Category URL on the storefront.
is_customized (optional) boolean Returns true if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides).

CustomUrlProduct

The custom URL for the product on the storefront.

Name Type Description
url (optional) string Product URL on the storefront.
is_customized (optional) boolean Returns true if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides).

CVVResult

Card Verification Value result from payment gateway.

Name Type Description
code (optional) string CVV code.
message (optional) string CVV message.

DetailedErrors

Name Type Description
additionalProperties string [Description to follow.]

ErrorResponse

Error payload for the BigCommerce API.

Name Type Description
status (optional) integer The HTTP status code.
title (optional) string The error title describing the particular error.
type (optional) string
instance (optional) string
errors (optional) string map

GiftCertificate

A gift-certificate model.

Name Type Description
code (optional) string The gift-certificate code.
original_balance (optional) float The balance on a gift certificate when it was purchased.
starting_balance (optional) float The balance on a gift certificate at the time of this purchase.
remaining_balance (optional) float The remaining balance on a gift certificate.
status (optional) string The status of a gift certificate. Acceptable values: active – gift certificate is active; pending – gift certificate purchase is pending; disabled – gift certificate is disabled; expired – gift certificate is expired.

GiftWrapping

Cart API object representing a gift-wrapping option.

Name Type Description
name string Name of the gift-wrapping option.
message string Message to accompany the gift-wrapping option.
amount number (float) Gift-wrapping price per product.
amount_as_integer number Gift-wrapping price per product, expressed as an integer.

ImageResponse

Response payload for the Bigcommerce API.

Name Type Description
data (optional) inline_response_200_10_data
meta (optional) object Empty meta object, may be used later

inline_response_200

Response payload for the Bigcommerce API.

Name Type Description
data (optional) array of inline_response_200_data
meta (optional) inline_response_200_meta

inline_response_200_bulk_pricing_rules

Common BulkPricingRule properties

Name Type Description
quantity_min (optional) integer The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero.
quantity_max (optional) integer The maximum inclusive quantity of a product to satisfy this rule. Must be greater than the quantity_min value – unless this field has a value of 0 (zero), in which case there will be no maximum bound for this rule.
type (optional) string The type of adjustment that is made. Values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product.
amount (optional) double float (number) The value of the adjustment by the bulk pricing rule.
id (optional) integer The ID of the bulk pricing rule.

inline_response_200_custom_fields

Common CustomField properties.

Name Type Description
name (optional) string The name of the field, shown on the storefront, orders, etc.
value (optional) string The name of the field, shown on the storefront, orders, etc.
id (optional) integer The unique numeric ID of the custom field; increments sequentially.

inline_response_200_custom_url

The custom URL for the product on the storefront.

Name Type Description
url (optional) string Product URL on the storefront.
is_customized (optional) boolean Returns true if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides).

inline_response_200_data

Common Product properties.

Name Type Description
name (optional) string The product name.
type (optional) string The product type. One of: physical – a physical stock unit; digital – a digital download.
sku (optional) string User defined product code/stock keeping unit (SKU).
description (optional) string The product description, which can include HTML formatting.
weight (optional) double float (number) Weight of the product, which can be used when calculating shipping costs.
width (optional) double float (number) Width of the product, which can be used when calculating shipping costs.
depth (optional) double float (number) Depth of the product, which can be used when calculating shipping costs.
height (optional) double float (number) Height of the product, which can be used when calculating shipping costs.
price (optional) double float (number) Price of the product. The price should include or exclude tax, based on the store settings.
cost_price (optional) double float (number) Cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.
retail_price (optional) double float (number) Retail cost of the product. If entered, the retail cost price will be shown on the product page.
sale_price (optional) double float (number) If entered, this sale price will be used instead of the value in the price field when calculating the product’s cost.
tax_class_id (optional) integer The ID of the tax class applied to the product. (NOTE: This value ignored if automatic tax is enabled.)
product_tax_code (optional) string Accepts an AvaTax System Tax Code, to identify products or services that fall into special sales-tax categories. By using these codes, merchants who subscribe to BigCommerce’s Avalara Premium integration 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 documentation.
categories (optional) integer array An array of IDs for the categories to which this product belongs. When updating a product, if an array of categories is supplied, all product categories will be overwritten. Does not accept more than 1,000 ID values.
brand_id (optional) integer The ID associated with the product’s brand.
inventory_level (optional) integer Current inventory level of the product. Simple inventory tracking must be enabled (See the inventory_tracking field) for this to take any effect.
inventory_warning_level (optional) integer Inventory warning level for the product. When the product’s inventory level drops below the warning level, the store owner will be informed. Simple inventory tracking must be enabled (see the inventory_tracking field) for this to take any effect.
inventory_tracking (optional) string The type of inventory tracking for the product. Acceptable values are: none – inventory levels will not be tracked; product – inventory levels will be tracked using the inventory_level and inventory_warning_level fields; variant – inventory levels will be tracked based on variants, which maintain their own warning levels and inventory levels.
fixed_cost_shipping_price (optional) double float (number) A fixed shipping cost for the product. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
is_free_shipping (optional) boolean Flag used to indicate whether the product has free shipping. If true, the shipping cost for the product will be zero.
is_visible (optional) boolean Flag to determine whether the product should be displayed to customers browsing the store. If true, the product will be displayed. If false, the product will be hidden from view.
is_featured (optional) boolean Flag to determine whether the product should be included in the featured products panel when viewing the store.
related_products (optional) integer array An array of IDs for the related products.
warranty (optional) string Warranty information displayed on the product page. Can include HTML formatting.
bin_picking_number (optional) string The BIN picking number for the product.
layout_file (optional) string The layout template file used to render this product.
upc (optional) string The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.
search_keywords (optional) string A comma-separated list of keywords that can be used to locate the product when searching the store.
availability (optional) string The product’s availability. Availability options are: available – the product can be purchased in the storefront; disabled – the product is listed in the storefront, but cannot be purchased; preorder – the product is listed for pre-orders.
availability_description (optional) string Availability text displayed on the checkout page, under the product title. Tells the customer how long it will normally take to ship this product, for example: “Usually ships in 24 hours.”
gift_wrapping_options_type (optional) string Type of gift-wrapping options. Values: any – allow any gift-wrapping options in the store; none – disallow gift-wrapping on the product; list – provide a list of IDs in the gift_wrapping_options_list field.
gift_wrapping_options_list (optional) integer array A list of gift-wrapping option IDs.
sort_order (optional) integer Priority 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.
condition (optional) string The product condition. Will be shown on the product page if the is_condition_shown field’s value is true. Possible values: New, Used, Refurbished.
is_condition_shown (optional) boolean Flag used to determine whether the product condition is shown to the customer on the product page.
order_quantity_minimum (optional) integer The minimum quantity an order must contain, to be eligible to purchase this product.
order_quantity_maximum (optional) integer The maximum quantity an order can contain when purchasing the product.
page_title (optional) string Custom title for the product page. If not defined, the product name will be used as the meta title.
meta_keywords (optional) string array Custom meta keywords for the product page. If not defined, the store’s default keywords will be used.
meta_description (optional) string Custom meta description for the product page. If not defined, the store’s default meta description will be used.
view_count (optional) integer The number of times the product has been viewed.
preorder_release_date (optional) DateTime string Pre-order release date. See the availability field for details on setting a product’s availability to accept pre-orders.
preorder_message (optional) string Custom 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 substituted for the release date.
is_preorder_only (optional) boolean If 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.
is_price_hidden (optional) boolean Set to false by default, indicating that this product’s price should be shown on the product page. If set to true, the price is hidden. (NOTE: To successfully set is_price_hidden to true, the availability value must be disabled.)
price_hidden_label (optional) string By default, an empty string. If is_price_hidden is true, the value of price_hidden_label is displayed instead of the price. (NOTE: To successfully set a non-empty string value, with is_price_hidden set to true, the availability value must be disabled.)
custom_url (optional) inline_response_200_custom_url
id (optional) integer The unique numeric ID of the product; increments sequentially.
calculated_price (optional) double float (number) The price of the product, unless a sale_price is set.
reviews_rating_sum (optional) integer The total rating for the product.
reviews_count (optional) integer The number of times the product has been rated.
custom_fields (optional) array of inline_response_200_custom_fields
bulk_pricing_rules (optional) array of inline_response_200_bulk_pricing_rules
date_created (optional) DateTime string The date on which the product was created.
date_modified (optional) DateTime string The date on which the product was modified.
images (optional) array of inline_response_200_images
videos (optional) array of inline_response_200_videos
variants (optional) array of inline_response_200_variants
base_variant_id (optional) integer The unique identifier of the base variant associated with a simple product. This value is null for complex products.

inline_response_200_images

Common ProductImage properties.

Name Type Description
is_thumbnail (optional) boolean Flag for identifying whether the image is used as the product’s thumbnail.
sort_order (optional) integer The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a sort_order the same as or greater than the image’s new sort_order value will have their sort_orders reordered.
description (optional) string The description for the image.
id (optional) integer The unique numeric ID of the image; increments sequentially.
product_id (optional) integer The unique numeric identifier for the product with which the image is associated.
image_file (optional) string The local path to the original image file uploaded to BigCommerce.
url_zoom (optional) string The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled.
url_standard (optional) string The standard URL for this image. By default, this is used for product-page images.
url_thumbnail (optional) string The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels.
url_tiny (optional) string The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page.
date_modified (optional) DateTime string The date on which the product image was modified.

inline_response_200_meta

Data about the response, including pagination and collection totals.

Name Type Description
pagination (optional) inline_response_200_meta_pagination

inline_response_200_meta_pagination

Data about the response, including pagination and collection totals.

Name Type Description
total (optional) integer Total number of items in the result set.
count (optional) integer Total number of items in the collection response.
per_page (optional) integer The number of items per page returned in the collection, controlled by the limit parameter.
current_page (optional) integer The page number currently displayed within the collection.
total_pages (optional) integer The total number of pages in the collection.
links (optional) inline_response_200_meta_pagination_links

Pagination links for the previous and next parts of the whole collection.

Name Type Description
previous (optional) string Link to the previous page returned in the response.
current (optional) string Link to the current page returned in the response.
next (optional) string Link to the next page returned in the response.

inline_response_200_option_values

Common OptionValueProduct properties.

Name Type Description
option_display_name (optional) string The name of the option.
label (optional) string The label of the option value.
id (optional) integer
option_id (optional) integer

inline_response_200_variants

Common Variant properties.

Name Type Description
cost_price (optional) double float (number) The cost price of the variant. Not affected by Price List prices.
price (optional) double float (number) This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s default price (set in the Product resource’s price field) will be used as the base price.
sale_price (optional) double float (number) This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s price field) will be used as the sale price.
retail_price (optional) double float (number) This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s price field) will be used as the retail price.
weight (optional) double float (number) This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
width (optional) double float (number) Width of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default width (set in the Product resource’s width field) will be used as the base width.
height (optional) double float (number) Height of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default height (set in the Product resource’s height field) will be used as the base height.
depth (optional) double float (number) Depth of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default depth (set in the Product resource’s depth field) will be used as the base depth.
is_free_shipping (optional) boolean Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.
fixed_cost_shipping_price (optional) double float (number) A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
purchasing_disabled (optional) boolean If true, this variant will not be purchasable on the storefront.
purchasing_disabled_message (optional) string If purchasing_disabled is true, this message should show on the storefront when the variant is selected.
image_url (optional) string The image that will be displayed when this variant is selected on the storefront. When updating a SKU image, send the publicly accessible URL. Supported image formats are JPEG, PNG, and GIF. Generic product images not specific to the variant should be stored on the product.
upc (optional) string The UPC code used in feeds for shopping comparison sites and external channel integrations.
inventory_level (optional) integer Inventory level for the variant, which is used when the product’s inventory_tracking is set to variant.
inventory_warning_level (optional) integer When the variant hits this inventory level, it is considered low stock.
bin_picking_number (optional) string Identifies where in a warehouse the variant is located.
id (optional) integer
product_id (optional) integer
sku (optional) string
sku_id (optional) integer Read-only reference to v2 API’s SKU ID. Will be null if it is a base variant.
option_values (optional) array of inline_response_200_option_values Array of option and option values IDs that make up this variant. Will be empty if the variant is the product’s base variant.

inline_response_200_videos

Common ProductVideo properties.

Name Type Description
title (optional) string The title for the video. If left blank, this will be filled in according to data on a host site.
description (optional) string The description for the video. If left blank, this will be filled in according to data on a host site.
sort_order (optional) integer The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a sort_order the same as or greater than the video’s new sort_order value will have their sort_orders reordered.
type (optional) string The video type (a short name of a host site).

Enum: youtube.
id (optional) integer The unique numeric ID of the product video; increments sequentially.
video_id (optional) string The ID of the video on a host site.
product_id (optional) integer The unique numeric identifier for the product with which the image is associated.
length (optional) string Length of the video. This will be filled in according to data on a host site.

inline_response_200_10_data

An object containing a publicly accessible image URL, or a form post that contains an image file.

Name Type Description
image_url (optional) string A public URL for a GIF, JPEG, or PNG image.

inline_response_200_11_config

Name Type Description
default_value (optional) string The default value (date, text, multi_line_text, numbers_only_text). Shown on a date option as an ISO-8601–formatted string, or on a text option as a string.
checked_by_default (optional) boolean Flag for setting the checkbox to be checked by default.
checkbox_label (optional) string Label displayed for the checkbox option.
date_limited (optional) boolean Flag to limit the dates allowed to be entered on a date option.
date_limit_mode (optional) string The type of limit that is allowed to be entered on a date option.

Enum: earliest, range, latest.
date_earliest_value (optional) date The earliest date allowed to be entered on the date option, as an ISO-8601–formatted string.
date_latest_value (optional) date The latest date allowed to be entered on the date option, as an ISO-8601–formatted string.
file_types_mode (optional) string The kind of restriction on the file types that can be uploaded with a file upload option. Acceptable values: specific – restricts uploads to particular file types; all – allows all file types.
file_types_supported (optional) string array The type of files allowed to be uploaded if the file_type_option is set to specific. Acceptable values: images – allows upload of image MIME types (bmp, gif, jpg, jpeg, jpe, jif, jfif, jfi, png, wbmp, xbm, tiff); documents – allows upload of document MIME types (txt, pdf, rtf, doc, docx, xls, xlsx, accdb, mdb, one, pps, ppsx, ppt, pptx, pub, odt, ods, odp, odg, odf); other – allows file types defined in the file_types_other array.
file_types_other (optional) string array A list of other file types allowed with the file upload option.
file_max_size (optional) integer The maximum size for a file that can be used with the file upload option.
text_characters_limited (optional) boolean
text_min_length (optional) integer The minimum length allowed for a text or multi-line text option.
text_max_length (optional) integer
text_lines_limited (optional) boolean Flag to validate the maximum number of lines allowed on a multi-line text input.
text_max_lines (optional) integer The maximum number of lines allowed on a multi-line text input.
number_limited (optional) boolean Flag to limit the value of a number (numbers_only_text) option.
number_limit_mode (optional) string The type of limit on values entered for a number (numbers_only_text) option.

Enum: lowest, highest, range.
number_lowest_value (optional) number The lowest allowed value for a number (numbers_only_text) option if number_limited is true.
number_highest_value (optional) number The highest allowed value for a number (numbers_only_text) option if number_limited is true.
number_integers_only (optional) boolean Flag to limit the input on a number (numbers_only_text) option to whole numbers only.
product_list_adjusts_inventory (optional) boolean Flag for automatically adjusting inventory on a product included in the list (product_list, product_list_with_images).
product_list_adjusts_pricing (optional) boolean Flag to add the optional product’s price to the main product’s price (product_list, product_list_with_images) .
product_list_shipping_calc (optional) string How to factor the optional product’s weight and package dimensions into the shipping quote (product_list, product_list_with_images). Acceptable values: none – don’t adjust; weight – use shipping weight only; package – use weight and dimensions.

inline_response_200_11_option_values

Common OptionValue properties.

Name Type Description
is_default (optional) boolean The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers.
label (optional) string The display text identifying the value on the storefront.
sort_order (optional) integer The order in which the value will be displayed on the product page.
value_data (optional) object Extra data describing the value, based on the type of option or modifier with which the value is associated. Allowable values: swatch requires an array of colors, with up to three hexidecimal color keys; product list requires a product_id; checkbox requires a boolean flag, called checked_value, to determine which value is considered to be the checked state.
id (optional) integer The unique numeric ID of the value; increments sequentially.

inline_response_200_15_adjusters

Name Type Description
price (optional) inline_response_200_15_adjusters_price
weight (optional) inline_response_200_15_adjusters_price
image_url (optional) string The URL for an image displayed on the storefront when the modifier value is selected.
purchasing_disabled (optional) inline_response_200_15_adjusters_purchasing_disabled

inline_response_200_15_adjusters_price

Name Type Description
adjuster (optional) string The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront.

Enum: relative, percentage.
adjuster_value (optional) number The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront.

inline_response_200_15_option_values

Common OptionValue properties.

Name Type Description
is_default (optional) boolean The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers.
label (optional) string The display text identifying the value on the storefront.
sort_order (optional) integer The order in which the value will be displayed on the product page.
value_data (optional) object Extra data describing the value, based on the type of option or modifier with which the value is associated. Allowable values: swatch requires an array of colors, with up to three hexidecimal color keys; product list requires a product_id; checkbox requires a boolean flag, called checked_value, to determine which value is considered to be the checked state.
adjusters (optional) inline_response_200_15_adjusters
id (optional) integer The unique numeric ID of the value; increments sequentially.

inline_response_200_19_conditions

Common ComplexRuleCondition properties.

Name Type Description
id (optional) integer The unique numeric ID of the rule condition; increments sequentially.
rule_id (optional) integer The unique numeric ID of the rule with which the condition is associated.
modifier_id (optional) integer The unique numeric ID of the modifier with which the rule condition is associated.
modifier_value_id (optional) integer The unique numeric ID of the modifier value with which the rule condition is associated.
variant_id (optional) integer The unique numeric ID of the variant with which the rule condition is associated.
combination_id (optional) integer (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or of the Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3.

inline_response_200_27_custom_url

The custom URL for the category on the storefront.

Name Type Description
url (optional) string Category URL on the storefront.
is_customized (optional) boolean Returns true if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides).

inline_response_200_35_custom

Custom payment from manual order.

Name Type Description
payment_method (optional) string Text entered for payment in the control panel.

inline_response_200_35_offline

Offline payment (e.g., check or purchase order).

Name Type Description
display_name (optional) string Display name for the offline payment.

inline_response_200_39_data_errors

Name Type Description
error (optional) string The error.
message (optional) string The message.

inline_response_200_39_data_warnings

Name Type Description
message (optional) string The message.
warning (optional) string The warning.

inline_response_201

The job identifier.

Name Type Description
job_id (optional) string The job identifier.

inline_response_204

No-content response for the BigCommerce API.

Name Type Description
status (optional) integer 204 HTTP status code.
title (optional) string The error title describing the situation.
type (optional) string
instance (optional) string

inline_response_404

Error payload for the BigCommerce API.

Name Type Description
status (optional) integer 404 HTTP status code.
title (optional) string The error title describing the particular error.
type (optional) string
instance (optional) string

inline_response_409

Error payload for the BigCommerce API.

Name Type Description
status (optional) integer The HTTP status code.
title (optional) string The error title describing the particular error.
type (optional) string
instance (optional) string
errors (optional) string map

ItemDigital

A downloadable item in a cart.

Name Type Description
download_file_urls array Array of URLs to download all files that are part of this product.
items string The combined downloads-page URL.
download_page_url string URL for a downloadable item.
download_size string “Combined download size for this product’s files, in human-readable style. E.g.: 30MB.”

ItemGiftCertificate

A gift certificate that can be applied to a cart item.

Name Type Required Description
id string false ID for this gift certificate.
name string false GiftCertificate-provided name that will appear in the control panel.
theme string true The email theme to use in the message sent to the recipient. Currently supports Birthday, Boy, Celebration, Christmas, General, and Girl.
amount number true Value of the gift certificate. Must be between $1.00 and $1,000.00.
is_taxable boolean false Whether the gift certificate’s redemption is taxable.
sender object true A ContactEntity object representing the gift certificate’s sender.
recipient object true A ContactEntity object representing the gift certificate’s recipient.
message string false Text that will be sent to the recipient, such as “Congratulations.” Limited to 200 characters.

ItemPhysical

A physical item in a cart.

Name Type Description
is_require_shipping boolean Flag for whether this item requires shipping.
gift_wrapping object A GiftWrapping object.

Job

A theme-processing job.

Name Type Description
errors (optional) array of inline_response_200_39_data_errors The errors.
id (optional) string The identifier.
percent_complete (optional) number The percent complete.
result (optional) string map The result.
status (optional) string The status.
time (optional) string The time.
warnings (optional) array of inline_response_200_39_data_warnings Warnings reported on this job.

JobId

Identifier of a theme-processing job.

Name Type Description
job_id (optional) string The job identifier.

LineItem

A line item within a cart.

Name Type Required Description
physical_items array true Array of ItemPhysical
digital_items array true Array of ItemDigital
gift_certificates array true Array of ItemGiftCertificate

Meta

Empty meta object; might be used later.

Metafield

Common Metafield properties.

Name Type Description
permission_set (optional) string Determines whether the field is completely private to the app that owns the field (app_only), or visible to other API consumers (read), or completely open for reading and writing to other apps (write).

Enum: app_only, read, write.
namespace (optional) string Namespace for the metafield, for organizational purposes.
key (optional) string The name of the field, for example: location_id, color.
value (optional) string The value of the field, for example: 1, blue.
description (optional) string Description for the metafield.
resource_type (optional) string The type of resource with which the metafield is associated. Acceptable values: category, brand, product, variant.
resource_id (optional) integer The unique identifier for the resource with which the metafield is associated.
id (optional) integer The unique identifier for the metafield.
created_at (optional) DateTime string Date and time of the metafield’s creation.
updated_at (optional) DateTime string Date and time when the metafield was last updated.

Modifier

Common Modifier properties.

Name Type Description
type (optional) string The type of modifier, which determines how it will display on the storefront.

Acceptable values: date, checkbox, file, text, multi_line_text, numbers_only_text, radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch.

For reference, former v2 API values are: D = date, C = checkbox, F = file, T = text, MT = multi_line_text, N = numbers_only_text, RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch.
required (optional) boolean Whether or not this modifer is required at checkout
config (optional) inline_response_200_11_config
option_values (optional) array of inline_response_200_15_option_values

ModifierValue

Common ModifierValue properties.

Name Type Description
is_default (optional) boolean The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers.
label (optional) string The display text identifying the value on the storefront.
sort_order (optional) integer The order in which the value will be displayed on the product page.
value_data (optional) object Extra data describing the value, based on the type of the associated option or modifier. Allowable values: swatch requires an array of colors, with up to three hexidecimal color keys; product list requires a product_id; checkbox requires a boolean flag, called checked_value, to determine which value is considered to be the checked state.
adjusters (optional) inline_response_200_15_adjusters
id (optional) integer The unique numeric ID of the value; increments sequentially.

NoContent

No-content response for the BigCommerce API.

Name Type Description
status (optional) integer 204 HTTP status code.
title (optional) string The error title describing the situation.
type (optional) string
instance (optional) string

NotFound

Error payload for the BigCommerce API.

Name Type Description
status (optional) integer 404 HTTP status code.
title (optional) string The error title describing the particular error.
type (optional) string
instance (optional) string

Offline

Offline payment (e.g., check or purchase order).

Name Type Description
display_name (optional) string Display name for the offline payment.

Option

Common Option properties.

Name Type Description
id (optional) integer The unique numerical ID of the option; increments sequentially.
product_id (optional) integer The unique numerical ID of the product to which the option belongs.
display_name (optional) string The name of the option, as shown on the storefront.
type (optional) string The type of option, which determines how it will display on the storefront.

Acceptable values: radio_buttons, rectangles, dropdown, product_list, product_list_with_images, swatch.

For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch.
config (optional) inline_response_200_11_config
option_values (optional) array of inline_response_200_11_option_values

OptionConfig

Name Type Description
default_value (optional) string The default value (date, text, multi_line_text, numbers_only_text). Shown on a date option as an ISO-8601–formatted string, or on a text option as a string.
checked_by_default (optional) boolean Flag for setting the checkbox to be checked by default.
checkbox_label (optional) string Label displayed for the checkbox option.
date_limited (optional) boolean Flag to limit the dates allowed to be entered on a date option.
date_limit_mode (optional) string The type of limit that is allowed to be entered on a date option.

Enum: earliest, range, latest.
date_earliest_value (optional) date The earliest date allowed to be entered on the date option, as an ISO-8601–formatted string.
date_latest_value (optional) date The latest date allowed to be entered on the date option, as an ISO-8601–formatted string.
file_types_mode (optional) string The kind of restriction on the file types that can be uploaded with a file upload option. Acceptable values: specific – restricts uploads to particular file types; all – allows all file types.
file_types_supported (optional) string array The type of files allowed to be uploaded if the file_type_option is set to specific. Acceptable values: images – allows upload of image MIME types (bmp, gif, jpg, jpeg, jpe, jif, jfif, jfi, png, wbmp, xbm, tiff); documents – allows upload of document MIME types (txt, pdf, rtf, doc, docx, xls, xlsx, accdb, mdb, one, pps, ppsx, ppt, pptx, pub, odt, ods, odp, odg, odf); other – allows file types defined in the file_types_other array.
file_types_other (optional) string array A list of other file types allowed with the file upload option.
file_max_size (optional) integer The maximum size for a file that can be used with the file upload option.
text_characters_limited (optional) boolean
text_min_length (optional) integer The minimum length allowed for a text or multi-line text option.
text_max_length (optional) integer
text_lines_limited (optional) boolean Flag to validate the maximum number of lines allowed on a multi-line text input.
text_max_lines (optional) integer The maximum number of lines allowed on a multi-line text input.
number_limited (optional) boolean Flag to limit the value of a number (numbers_only_text) option.
number_limit_mode (optional) string The type of limit on values entered for a number (numbers_only_text) option.

Enum: lowest, highest, range.
number_lowest_value (optional) number The lowest allowed value for a number (numbers_only_text) option if number_limited is true.
number_highest_value (optional) number The highest allowed value for a number (numbers_only_text) option if number_limited is true.
number_integers_only (optional) boolean Flag to limit the input on a number (numbers_only_text) option to whole numbers only.
product_list_adjusts_inventory (optional) boolean Flag for automatically adjusting inventory on a product included in the list (product_list, product_list_with_images).
product_list_adjusts_pricing (optional) boolean Flag to add the optional product’s price to the main product’s price (product_list, product_list_with_images) .
product_list_shipping_calc (optional) string How to factor the optional product’s weight and package dimensions into the shipping quote (product_list, product_list_with_images). Acceptable values: none – don’t adjust; weight – use shipping weight only; package – use weight and dimensions.

OptionValue

Common OptionValue properties.

Name Type Description
is_default (optional) boolean The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers.
label (optional) string The display text identifying the value on the storefront.
sort_order (optional) integer The order in which the value will be displayed on the product page.
value_data (optional) object Extra data describing the value, based on the type of option or modifier with which the value is associated. Allowable values: swatch requires an array of colors, with up to three hexidecimal color keys; product list requires a product_id; checkbox requires a boolean flag, called checked_value, to determine which value is considered to be the checked state.
id (optional) integer The unique numeric ID of the value; increments sequentially.

OptionValueVariant

Common OptionValueProduct properties.

Name Type Description
option_display_name (optional) string The name of the option.
label (optional) string The label of the option value.
id (optional) integer
option_id (optional) integer

Pagination

Data about the response, including pagination and collection totals.

Name Type Description
total (optional) integer Total number of items in the result set.
count (optional) integer Total number of items in the collection response.
per_page (optional) integer The number of items per page returned in the collection, controlled by the limit parameter.
current_page (optional) integer The page number currently displayed within the collection.
total_pages (optional) integer The total number of pages in the collection.
links (optional) inline_response_200_meta_pagination_links

Product

Common Product properties.

Name Type Description
name (optional) string The product name.
type (optional) string The product type: physical – a physical stock unit; digital – a digital download.
sku (optional) string User-defined product code/stock keeping unit (SKU).
description (optional) string The product description, which can include HTML formatting.
weight (optional) number (double float) Weight of the product, which can be used when calculating shipping costs.
width (optional) number (double float) Width of the product, which can be used when calculating shipping costs.
depth (optional) number (double float) Depth of the product, which can be used when calculating shipping costs.
height (optional) number (double float) Height of the product, which can be used when calculating shipping costs.
price (optional) number (double float) The price of the product. The price should include or exclude tax, based on the store settings.
cost_price (optional) number (double float) The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store.
retail_price (optional) number (double float) The retail cost of the product. If entered, the retail cost price will be shown on the product page.
sale_price (optional) number (double float) If entered, the sale price will be used instead of value in the price field when calculating the product’s cost.
tax_class_id (optional) integer The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)
product_tax_code (optional) string Accepts AvaTax System Tax Codes, which identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to BigCommerce’s Avalara Premium integration 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 documentation.
categories (optional) integer array An array of IDs for the categories to which this product belongs. When updating a product, if an array of categories is supplied, all product categories will be overwritten. Does not accept more than 1,000 ID values.
brand_id (optional) integer The ID associated with the product’s brand.
inventory_level (optional) integer Current inventory level of the product. Simple inventory tracking must be enabled (see the inventory_tracking field) for this to take effect.
inventory_warning_level (optional) integer Inventory warning level for the product. When the product’s inventory level drops below the warning level, the store owner will be informed. Simple inventory tracking must be enabled (see the inventory_tracking field) for this to take effect.
inventory_tracking (optional) string The type of inventory tracking for the product. Values are: none – inventory levels will not be tracked; product – inventory levels will be tracked using the inventory_level and inventory_warning_level fields; variant – inventory levels will be tracked based on variants, which maintain their own warning levels and inventory levels.
fixed_cost_shipping_price (optional) number (double float) A fixed shipping cost for the product. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
is_free_shipping (optional) boolean Flag used to indicate whether the product has free shipping. If true, the shipping cost for the product will be zero.
is_visible (optional) boolean Flag used to determine whether the product should be displayed to customers browsing the store. If true, the product will be displayed. If false, the product will be hidden from view.
is_featured (optional) boolean Flag used to determine whether the product should be included in the featured products panel when visitors view the store.
related_products (optional) integer array An array of IDs for related products.
warranty (optional) string Warranty information displayed on the product page. Can include HTML formatting.
bin_picking_number (optional) string The BIN picking number for the product.
layout_file (optional) string The layout template file used to render this product.
upc (optional) string The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations.
search_keywords (optional) string A comma-separated list of keywords that can be used to locate the product when searching the store.
availability (optional) string The product’s availability. Availability options are: available – the product can be purchased in the storefront; disabled – the product is listed in the storefront, but cannot be purchased; preorder – the product is listed for pre-orders.
availability_description (optional) string Availability text displayed on the checkout page, under the product title. Tells the customer how long it will normally take to ship this product, for example: “Usually ships in 24 hours.”
gift_wrapping_options_type (optional) string Type of gift-wrapping options. Values: any – allow any gift-wrapping options in the store; none – disallow gift-wrapping on the product; list – provide a list of IDs in the gift_wrapping_options_list field.
gift_wrapping_options_list (optional) integer array A list of gift-wrapping option IDs.
sort_order (optional) integer Priority 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.
condition (optional) string The product condition. Will be shown on the product page if the is_condition_shown field’s value is true. Possible values: New, Used, Refurbished.
is_condition_shown (optional) boolean Flag used to determine whether the product condition is shown to the customer on the product page.
order_quantity_minimum (optional) integer The minimum quantity an order must contain, to be eligible to purchase this product.
order_quantity_maximum (optional) integer The maximum quantity an order can contain when purchasing the product.
page_title (optional) string Custom title for the product page. If not defined, the product name will be used as the meta title.
meta_keywords (optional) string array Custom meta keywords for the product page. If not defined, the store’s default keywords will be used.
meta_description (optional) string Custom meta description for the product page. If not defined, the store’s default meta description will be used.
view_count (optional) integer The number of times the product has been viewed.
preorder_release_date (optional) DateTime string Pre-order release date. See the availability field for details on setting a product’s availability to accept pre-orders.
preorder_message (optional) string Custom 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 substituted for the release date.
is_preorder_only (optional) boolean If set to false, the product will not change its availability from preorder to available on the release date. Otherwise, the product’s availability/status will change to available on the release date.
is_price_hidden (optional) boolean Set to false by default, indicating that this product’s price should be shown on the product page. If set to true, the price is hidden. (NOTE: To successfully set is_price_hidden to true, the availability value must be disabled.)
price_hidden_label (optional) string By default, an empty string. If is_price_hidden is true, the value of price_hidden_label is displayed instead of the price. (NOTE: To successfully set a non-empty string value, with is_price_hidden set to true, the availability value must be disabled.)
custom_url (optional) inline_response_200_custom_url Object for custom product URLs.
custom_fields (optional) array of catalogproducts_custom_fields Objects for custom fields.
bulk_pricing_rules (optional) array of catalogproducts_bulk_pricing_rules Objects for bulk discounts.
variants (optional) array of catalogproducts_variants Objects for variants of this product.

ProductImage

The full ProductImage model.

Name Type Description
id integer The unique numeric ID of the image; increments sequentially.
product_id integer The unique numeric identifier for the product with which the image is associated.
image_file string The local path to the original image file uploaded to BigCommerce.
url_zoom string The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled.
url_standard string The standard URL for this image. By default, this is used for product-page images.
url_thumbnail string The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels.
url_tiny string The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page.
date_modified DateTime string The date on which the product image was modified.

productReview

Common ProductReview properties.

Name Type Description
title (optional) string The title for the product review.
text (optional) string The text for the product review.
status (optional) string The status of the product review. Must be one of approved, disapproved or pending.
rating (optional) integer The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.
email (optional) string The email of the reviewer. Must be a valid email or empty string.
name (optional) string The name of the reviewer.
date_reviewed (optional) DateTime string Date the product was reviewed.

productVideo

Common ProductVideo properties.

Name Type Description
title (optional) string The title for the video. If left blank, this will be filled in according to data on a host site.
description (optional) string The description for the video. If left blank, this will be filled in according to data on a host site.
sort_order (optional) integer The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a sort_order the same as or greater than the video’s new sort_order value will have their sort_orders reset.
type (optional) string The video type (a short name of a host site).

Enum: youtube.
video_id (optional) string The ID of the video on a host site.

ResourceImage

An object containing a publicly accessible image URL, or a form post that contains an image file.

Name Type Description
image_url (optional) string A public URL for a GIF, JPEG, or PNG image.

StoreCredit

A store credit model.

Name Type Description
remaining_balance (optional) string Remaining balance of shopper’s store credit.

Subscriber

Common Subscriber properties.

Name Type Description
id (optional) integer The unique numeric ID of the subscriber; increments sequentially.
email (optional) string The email of the subscriber. Must be unique.
first_name (optional) string The first name of the subscriber.
last_name (optional) string The last name of the subscriber.
source (optional) string The source of the subscriber. Values are: storefront, order, or custom.
order_id (optional) integer The ID of the source order, if source was an order.

Theme

A theme.

Name Type Description
variations (optional) array of themes_variations The variations.
uuid (optional) string The identifier.

themes_variations

A variation.

Name Type Description
description (optional) string The description.
external_id (optional) string The external identifier.
name (optional) string The name.
uuid (optional) string The identifier.

Transaction

Payload to create a transaction in BigCommerce.

Name Type Description
event string Store event that created the transaction. Acceptable values: purchase, authorization, capture, refund, void, pending, settled.
method string The payment method. Acceptable values: credit_card – a credit-card transaction; electronic_wallet – an online wallet; store_credit – a transaction using store credit; gift_certificate – a transaction using a gift certificate; apple_pay_card – credit card that is mapped to a token within Apple Pay; apple_pay_token – encrypted token that is mapped to a credit card within Apple Pay; custom – manual payment methods; token – payment token; nonce – temporary payment token; offsite – online payment off the site (e.g., PayPal); offline – payment method that takes place offline.
amount number (float) Amount of money in the transaction.
currency ISO-4217 string Currency used for the transaction.
gateway string The payment gateway, where applicable. Acceptable values: 2checkout, adyen, amazon, authorizenet, bankdeposit, braintree, cheque, cod, custom, firstdatagge4, giftcertificate, hps, instore, klarna, migs, moneyorder, nmi, paypalexpress, paypalpaymentsprous, paypalpaymentsprouk, plugnpay, qbmsv2, securenet, square, storecredit, stripe, testgateway, usaepay.
gateway_transaction_id (optional) string The transaction ID returned by the payment gateway for this transaction item.
date_created (optional) DateTime string The datetime of the transaction.
test (optional) boolean True if the transaction performed was a test, or if the gateway is in test mode.
status (optional) string Status of the transaction. Acceptable values: ok, error.
fraud_review (optional) boolean Result of gateway fraud review, if any. Default is false.
reference_transaction_id (optional) integer Identifier for an existing transaction, upon which this transaction acts.
offline (optional) inline_response_200_35_offline Object for offline payment (e.g., check or purchase order).
custom (optional) inline_response_200_35_custom Object for custom payment from a manual order.

Variant

Common Variant properties.

Name Type Description
cost_price (optional) number (double float) The cost price of the variant.
price (optional) number (double float) This variant’s base price on the storefront. If this value is null, the product’s default price (set in the Product resource’s price field) will be used as the base price.
weight (optional) number (double float) This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
width (optional) number (double float) Width of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default width (set in the Product resource’s width field) will be used as the base width.
height (optional) number (double float) Height of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default height (set in the Product resource’s height field) will be used as the base height.
depth (optional) number (double float) Depth of the variant, which can be used when calculating shipping costs. If this value is null, the product’s default depth (set in the Product resource’s depth field) will be used as the base depth.
is_free_shipping (optional) boolean Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.
fixed_cost_shipping_price (optional) number (double float) A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
purchasing_disabled (optional) boolean If true, this variant will not be purchasable on the storefront.
purchasing_disabled_message (optional) string If purchasing_disabled is true, this message should show on the storefront when the variant is selected.
image_url (optional) string The image that will be displayed when this variant is selected on the storefront. When updating a SKU image, send the publicly accessible URL. Supported image formats are JPEG, PNG, and GIF. Generic product images not specific to the variant should be stored on the product.
upc (optional) string The UPC code used in feeds for shopping comparison sites and external channel integrations.
inventory_level (optional) integer Inventory level for the variant, which is used when the product’s inventory_tracking is set to variant.
inventory_warning_level (optional) integer When the variant hits this inventory level, it is considered low stock.
bin_picking_number (optional) string Identifies where in a warehouse the variant is located.
id (optional) integer
product_id (optional) integer
sku (optional) string
sku_id (optional) integer Read-only reference to v2 API’s SKU ID. Null if it is a base variant.
option_values (optional) array of inline_response_200_option_values Array of option and option-values IDs that make up this variant. If the variant is the product’s base variant, this will be empty.

Variation

A variation.

Name Type Description
description (optional) string The description.
external_id (optional) string The external identifier.
name (optional) string The name.
uuid (optional) string The identifier.