NAV

API v2 Documentation

Orders Reference

Orders APIs integrate with point-of-sale, shipping, distribution, and inventory-management systems. They include Orders, Order Coupons, Order Messages, Order Products, Order Shipping Addresses, Order Statuses, Order Taxes, and Shipments.

Orders

The Order object contains a record of the purchase agreement between a shopper and a merchant.

Order Object – Properties

Name Type Description
id int The ID of the order, a read-only value. Do not pass in PUT or POST.
customer_id int The ID of the customer placing the order; or 0 if it was a guest order.
date_created date The date this order was created. If not specified, will default to the current time. The date should be in RFC format, e.g.: Tue, 20 Nov 2012 00:00:00 +0000
date_modified date A read-only value representing the last modification of the order. Do not attempt to modify or set this value in a POST or PUT operation.
date_shipped date A read-only value representing the date of shipment. Do not attempt to modify or set this value in a POST or PUT operation.
status_id int The status ID. See examples under Order Statuses.
status string The status will include one of the string values defined under Order Statuses. This value is read-only. Do not attempt to modify or set this value in a POST or PUT operation.
subtotal_ex_tax decimal Override value for subtotal excluding tax. If specified, the field subtotal_inc_tax is also required.
subtotal_inc_tax decimal Override value for subtotal including tax. If specified, the field subtotal_ex_tax is also required.
subtotal_tax decimal A read-only value. Do not attempt to set or modify this value in a POST or PUT operation.
base_shipping_cost decimal The value of the base shipping cost.
shipping_cost_ex_tax decimal The value of shipping cost, excluding tax.
shipping_cost_inc_tax decimal The value of shipping cost, including tax.
shipping_cost_tax decimal A read-only value. Do not attempt to modify or set this value in a POST or PUT operation.
shipping_cost_tax_class_id int Shipping-cost tax class. A read-only value. Do not attempt to modify or set this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)
base_handling_cost decimal The value of the base handling cost.
handling_cost_ex_tax decimal The value of the handling cost, excluding tax.
handling_cost_inc_tax decimal The value of the handling cost, including tax.
handling_cost_tax decimal A read-only value. Do not attempt to modify or set this value in a POST or PUT operation.
handling_cost_tax_class_id int A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)
base_wrapping_cost decimal The value of the base wrapping cost.
wrapping_cost_ex_tax decimal The value of the wrapping cost, excluding tax.
wrapping_cost_inc_tax decimal The value of the wrapping cost, including tax.
wrapping_cost_tax decimal A read-only value. Do not attempt to modify or set this value in a POST or PUT operation.
wrapping_cost_tax_class_id int A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)
total_ex_tax decimal Override value for the total, excluding tax. If specified, the field total_inc_tax is also required.
total_inc_tax decimal Override value for the total, including tax. If specified, the field total_ex_tax is also required.
total_tax decimal A read-only value. Do not attempt to set or modify this value in a POST or PUT operation.
items_total int The total number of items in the order.
items_shipped int The number of items that have been shipped.
payment_method string The payment method for this order. Can be one of the following: Manual, Credit Card, cash, Test Payment Gateway, etc.
payment_provider_id string The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used).
payment_status enum A read-only value. Do not attempt to set or modify this value in a POST or PUT operation.
refunded_amount decimal The amount refunded from this transaction.
order_is_digital boolean Whether this is an order for digital products.
store_credit_amount decimal Represents the store credit that the shopper has redeemed on this individual order. This is a read-only value. Do not pass in a POST or PUT.
gift_certificate_amount decimal A read-only value. Do not pass in a POST or PUT.
ip_address string IP Address of the customer, if known.
geoip_country string The full name of the country where the customer made the purchase, based on the IP.
geoip_country_iso2 string The country where the customer made the purchase, in ISO2 format, based on the IP.
currency_id int The ID of the currency being used in this transaction. A read-only value. Do not pass in a POST or PUT.
currency_code string The currency code of the currency being used in this transaction. A read-only value. Do not pass in a POST or PUT.
currency_exchange_rate decimal A read-only value. Do not pass in a POST or PUT.
default_currency_id int A read-only value. Do not pass in a POST or PUT.
default_currency_code string The currency code of the default currency for this type of transaction. A read-only value. Do not pass in a POST or PUT.
staff_notes text Any additional notes for staff.
customer_message text Message that the customer entered into the Order Comments box during checkout.
discount_amount decimal Amount of discount for this transaction.
coupon_discount decimal A read-only value. Do not pass in a POST or PUT.
shipping_address_count int The number of shipping addresses associated with this transaction. A read-only value. Do not pass in a POST or PUT.
is_deleted boolean Indicates whether the order was deleted (archived). A read-only value. Do not pass in a POST or PUT.
is_email_opt_in boolean Indicates whether the shopper has selected an opt-in check box (on the checkout page) to receive emails. A read-only value. Do not pass in a POST or PUT.
ebay_order_id string If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be 0.
billing_address object Contains the billing address details for this transaction, specifically: first_name, last_name, company, street_1, street_2, city, state, zip, country, country_iso2, phone, and email. Ensure that state names are spelled out in full, e.g.: California. Required for POST operations.
order_source string Orders submitted via the store’s website will include a www value. Orders submitted via the API will be set to external. A read-only value. Do not pass in a POST or PUT.
external_source string For orders submitted or modified via the API, using a PUT or POST operation, you can optionally pass in a value identifying the system used to generate the order. For example: POS. Otherwise, the value will be null.
products array Array of product objects that make up the order.
shipping_addresses array This is an object array that has different syntax in different operations:

In PUT or POST operations, you can optionally pass a shipping_addresses object array containing one or more shipping addresses. However, if you include more than one address, only the first address will be used, because the API does not currently support shipping to more than one address. If you do not pass a shipping address, the billing address will be used.

For the full list of available name/value pairs, see the Order Shipping Addresses object. Not all fields are required. For a syntax example of syntax, see the Create an Order endpoint.

In GET and other operations, the shipping_addresses object will consist of two addresses. The first is the URI of a JSON object containing the shipping address details. The second is a context path that provides an alternate means of retrieving the data (if, for example, you prefer XML). For syntax, refer to the List Orders endpoint.
coupons object This object is read-only. Do not attempt to pass in a PUT or POST. Contains two name/value pairs:
The url property’s value is the fully qualified address of a JSON object array, containing details of any coupon(s) associated with this transaction.
The resource property’s value is the context path to the Order Coupons resource, which provides an alternate means of retrieving the data (if, for example, you prefer XML).

Order Webhook Events

Order Created

store/order/created

Occurs when an order is received from the checkout, or when a manual order is created in the control panel.

Order Updated

store/order/updated

Occurs when order details are updated through the control panel, or when an order status is changed from the control panel or the API.

Order Archived

store/order/archived

Occurs when an order is archived from the control panel.

Manages
OAuth Scopes store_v2_orders
store_v2_orders_read_only

List Orders

Gets the collection of orders. (The default sort is by order id, from lowest to highest.)

Filters

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

Parameter Type Example
min_id int /api/v2/orders?min_id={value}
max_id int /api/v2/orders?max_id={value}
min_total decimal /api/v2/orders?min_total={value}
max_total decimal /api/v2/orders?max_total={value}
customer_id string /api/v2/orders?customer_id={value}
email string /api/v2/orders?email={value}
status_id string /api/v2/orders?status_id={value}
is_deleted string (‘true’ or 'false’) /api/v2/orders?is_deleted={value}
payment_method string /api/v2/orders?payment_method={value}
min_date_created dateTime or date /api/v2/orders?min_date_created={value}
max_date_created dateTime or date /api/v2/orders?max_date_created={value}
min_date_modified dateTime or date /api/v2/orders?min_date_modified={value}
max_date_modified dateTime or date /api/v2/orders?max_date_modified={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 orders are returned by default.

Parameter Type Example
page int /api/v2/orders?page={number}
limit int /api/v2/orders?limit={count}
sort string /api/v2/orders?sort=date_created:desc

Response

Example JSON returned in the response:

[
  {
    "id": 100,
    "customer_id": 10,
    "date_created": "Wed, 14 Nov 2012 19:26:23 +0000",
    "date_modified": "Wed, 14 Nov 2012 19:26:23 +0000",
    "date_shipped": "",
    "status_id": 11,
    "status": "Awaiting Fulfillment",
    "subtotal_ex_tax": "79.0000",
    "subtotal_inc_tax": "79.0000",
    "subtotal_tax": "0.0000",
    "base_shipping_cost": "0.0000",
    "shipping_cost_ex_tax": "0.0000",
    "shipping_cost_inc_tax": "0.0000",
    "shipping_cost_tax": "0.0000",
    "shipping_cost_tax_class_id": 2,
    "base_handling_cost": "0.0000",
    "handling_cost_ex_tax": "0.0000",
    "handling_cost_inc_tax": "0.0000",
    "handling_cost_tax": "0.0000",
    "handling_cost_tax_class_id": 2,
    "base_wrapping_cost": "0.0000",
    "wrapping_cost_ex_tax": "0.0000",
    "wrapping_cost_inc_tax": "0.0000",
    "wrapping_cost_tax": "0.0000",
    "wrapping_cost_tax_class_id": 3,
    "total_ex_tax": "79.0000",
    "total_inc_tax": "79.0000",
    "total_tax": "0.0000",
    "items_total": 1,
    "items_shipped": 0,
    "payment_method": "cash",
    "payment_provider_id": null,
    "payment_status": "",
    "refunded_amount": "0.0000",
    "order_is_digital": false,
    "store_credit_amount": "0.0000",
    "gift_certificate_amount": "0.0000",
    "ip_address": "50.58.18.2",
    "geoip_country": "",
    "geoip_country_iso2": "",
    "currency_id": 1,
    "currency_code": "USD",
    "currency_exchange_rate": "1.0000000000",
    "default_currency_id": 1,
    "default_currency_code": "USD",
    "staff_notes": "",
    "customer_message": "",
    "discount_amount": "0.0000",
    "coupon_discount": "0.0000",
    "shipping_address_count": 1,
    "is_deleted": false,
    "billing_address": {
      "first_name": "Trisha",
      "last_name": "McLaughlin",
      "company": "",
      "street_1": "12345 W Anderson Ln",
      "street_2": "",
      "city": "Austin",
      "state": "Texas",
      "zip": "78757",
      "country": "United States",
      "country_iso2": "US",
      "phone": "",
      "email": "elsie@example.com"
    },
    "products": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/orders/100/products.json",
      "resource": "/orders/100/products"
    },
    "shipping_addresses": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/orders/100/shippingaddresses.json",
      "resource": "/orders/100/shippingaddresses"
    },
    "coupons": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/orders/100/coupons.json",
      "resource": "/orders/100/coupons"
    }
  }
]

Get an Order

Gets an order.

Response

Example JSON returned in the response:

{
  "id": 100,
  "customer_id": 10,
  "date_created": "Wed, 14 Nov 2012 19:26:23 +0000",
  "date_modified": "Wed, 14 Nov 2012 19:26:23 +0000",
  "date_shipped": "",
  "status_id": 11,
  "status": "Awaiting Fulfillment",
  "subtotal_ex_tax": "79.0000",
  "subtotal_inc_tax": "79.0000",
  "subtotal_tax": "0.0000",
  "base_shipping_cost": "0.0000",
  "shipping_cost_ex_tax": "0.0000",
  "shipping_cost_inc_tax": "0.0000",
  "shipping_cost_tax": "0.0000",
  "shipping_cost_tax_class_id": 2,
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 2,
  "base_wrapping_cost": "0.0000",
  "wrapping_cost_ex_tax": "0.0000",
  "wrapping_cost_inc_tax": "0.0000",
  "wrapping_cost_tax": "0.0000",
  "wrapping_cost_tax_class_id": 3,
  "total_ex_tax": "79.0000",
  "total_inc_tax": "79.0000",
  "total_tax": "0.0000",
  "items_total": 1,
  "items_shipped": 0,
  "payment_method": "cash",
  "payment_provider_id": null,
  "payment_status": "",
  "refunded_amount": "0.0000",
  "order_is_digital": false,
  "store_credit_amount": "0.0000",
  "gift_certificate_amount": "0.0000",
  "ip_address": "50.58.18.2",
  "geoip_country": "",
  "geoip_country_iso2": "",
  "currency_id": 1,
  "currency_code": "USD",
  "currency_exchange_rate": "1.0000000000",
  "default_currency_id": 1,
  "default_currency_code": "USD",
  "staff_notes": "",
  "customer_message": "",
  "discount_amount": "0.0000",
  "coupon_discount": "0.0000",
  "shipping_address_count": 1,
  "is_deleted": false,
  "billing_address": {
    "first_name": "Trisha",
    "last_name": "McLaughlin",
    "company": "",
    "street_1": "12345 W Anderson Ln",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78757",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "elsie@example.com"
  },
  "products": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/orders/100/products.json",
    "resource": "/orders/100/products"
  },
  "shipping_addresses": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/orders/100/shippingaddresses.json",
    "resource": "/orders/100/shippingaddresses"
  },
  "coupons": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/orders/100/coupons.json",
    "resource": "/orders/100/coupons"
  }
}

Get a Count of Orders

Gets a count of the number of orders in the store.

Response

Example JSON returned in the response:

{
  "count": 9
}

Create an Order

Manually create and submit an order.

Read-only Properties

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

Requirements

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

Overriding Preset Values

You can create overrides for calculated values such as product prices, subtotal and totals by sending a fixed value in the request. If values are not supplied for these properties, they will be automatically calculated based on the pre-set store values and tax rules.

Order Products

Calculation of Totals

Order Properties

Changing the Order Status

Request

Example request object:

{
  "customer_id": 0,
  "status_id": 11,
  "date_created": "Thu, 04 Oct 2012 03:24:40 +0000",
  "subtotal_ex_tax": 1705,
  "subtotal_inc_tax": 1915,
  "base_shipping_cost": 0,
  "shipping_cost_ex_tax": 0,
  "shipping_cost_inc_tax": 0,
  "base_handling_cost": 0,
  "handling_cost_ex_tax": 0,
  "handling_cost_inc_tax": 0,
  "base_wrapping_cost": 0,
  "wrapping_cost_ex_tax": 0,
  "wrapping_cost_inc_tax": 0,
  "total_ex_tax": 1705,
  "total_inc_tax": 1915,
  "refunded_amount": 0,
  "order_is_digital": false,
  "staff_notes": "",
  "customer_message": "",
  "discount_amount": 10,
  "billing_address": {
    "first_name": "Trisha",
    "last_name": "McLaughlin",
    "company": "",
    "street_1": "12345 W Anderson Ln",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78757",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "elsie@example.com"
  },
  "shipping_addresses": [
    {
      "first_name": "Trisha",
      "last_name": "McLaughlin",
      "company": "Acme Pty Ltd",
      "street_1": "566 Sussex St",
      "street_2": "",
      "city": "Austin",
      "state": "Texas",
      "zip": "78757",
      "country": "United States",
      "country_iso2": "US",
      "phone": "",
      "email": "elsie@example.com"
    }
  ],
  "products": [
    {
      "product_id": 32,
      "quantity": 2
    },
    {
      "product_id": 33,
      "quantity": 2,
      "product_options": [
        {
          "id": 87,
          "value": 10
        }
      ]
    },
    {
      "name": "My custom product",
      "quantity": 2,
      "price_inc_tax": 10.8,
      "price_ex_tax": 10
    }
  ],
  "external_source": "POS"
}

Response

Example JSON returned in the response:

{
  "id": 100,
  "customer_id": 0,
  "date_created": "Thu, 04 Oct 2012 03:24:40 +0000",
  "date_modified": "Thu, 30 May 2013 01:48:39 +0000",
  "date_shipped": "",
  "status_id": 1,
  "status": "Pending",
  "subtotal_ex_tax": "1705.0000",
  "subtotal_inc_tax": "1915.0000",
  "subtotal_tax": "210.0000",
  "base_shipping_cost": "0.0000",
  "shipping_cost_ex_tax": "0.0000",
  "shipping_cost_inc_tax": "0.0000",
  "shipping_cost_tax": "0.0000",
  "shipping_cost_tax_class_id": 0,
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": "0.0000",
  "wrapping_cost_ex_tax": "0.0000",
  "wrapping_cost_inc_tax": "0.0000",
  "wrapping_cost_tax": "0.0000",
  "wrapping_cost_tax_class_id": 0,
  "total_ex_tax": "1705.0000",
  "total_inc_tax": "1915.0000",
  "total_tax": "210.0000",
  "items_total": 4,
  "items_shipped": 0,
  "payment_method": "Manual",
  "payment_provider_id": null,
  "payment_status": "",
  "refunded_amount": "0.0000",
  "order_is_digital": false,
  "store_credit_amount": "0.0000",
  "gift_certificate_amount": "0.0000",
  "ip_address": "",
  "geoip_country": "",
  "geoip_country_iso2": "",
  "currency_id": 0,
  "currency_code": null,
  "currency_exchange_rate": "0.0000000000",
  "default_currency_id": 0,
  "default_currency_code": null,
  "staff_notes": "",
  "customer_message": "",
  "discount_amount": "10.0000",
  "coupon_discount": "0.0000",
  "shipping_address_count": 1,
  "is_deleted": false,
  "billing_address": {
    "first_name": "Trisha",
    "last_name": "McLaughlin",
    "company": "",
    "street_1": "12345 W Anderson Ln",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78757",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "elsie@example.com"
  },
  "order_source": "external",
  "external_source": "POS",
  "products": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/orders/100/products.json",
    "resource": "/orders/100/products"
  },
  "shipping_addresses": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/orders/100/shippingaddresses.json",
    "resource": "/orders/100/shippingaddresses"
  },
  "coupons": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/orders/100/coupons.json",
    "resource": "/orders/100/coupons"
  }
}

Update an Order

Updates an existing order.

Read-only Properties

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

Changing the Order Status

The status property cannot be edited directly, because it is generated based on the status_id.

Use the status_id property to set the order to a specific state. The list of available statuses is provided by the Order Statuses resource. If the store has subscribed to Avalara Premium, tax documents are submitted when the status_id property changes. The following table details the behavior for PUT operations. See also the list of Paid Statuses.

Existing Status Status Passed Resultant Status Avalara Tax Document Submission
Any None Pending None
Paid or Refunded Paid Paid None
Unpaid or Refunded Unpaid Unpaid None
Paid or Refunded Unpaid Unpaid Tax document voided
Unpaid or Refunded Paid Paid Tax document submitted

Calculated Fields

Edits to the following properties will trigger a recalculation of the subtotal and total:

Delete an Order

Deletes an order.

Delete All Orders

Deletes all orders in the store.

Order Coupons

Coupon code applied to an order.

Order Coupon Object – Properties

Name Type Description
id int
coupon_id int
order_id int
code string
amount decimal
type enum
discount decimal
Manages
OAuth Scopes store_v2_orders
store_v2_orders_read_only

List Order Coupons

Gets the coupon codes applied to an order. (Default sorting is by coupon id, from lowest to highest; however, only one coupon can be applied to each order.)

Filters

There are no filter parameters specific to order_coupons.

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 order_coupons are returned by default.

Parameter Type Example
Page int /api/v2/orders/{order_id}/coupons?page={number}
Limit int /api/v2/orders/{order_id}/coupons?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "coupon_id": 1,
    "order_id": 115,
    "code": "557D2DEA0CCAFA1",
    "amount": "5.0000",
    "type": 1,
    "discount": "4.6600"
  }
]

Get an Order Coupon

Gets a coupon code associated with an order.

Response

Example JSON returned in the response:

{
  "id": 1,
  "coupon_id": 1,
  "order_id": 115,
  "code": "557D2DEA0CCAFA1",
  "amount": "5.0000",
  "type": 1,
  "discount": "4.6600"
}

Order Messages

Messages associated with an order.

Order Message Object – Properties

Name Type Description
id int
order_id int
staff_id int
customer_id int
type enum
subject string
message text
status enum
is_flagged boolean
date_created date
customer resource
Manages
OAuth Scopes store_v2_orders
store_v2_orders_read_only

List Order Messages

Gets the messages associated with an order.

Filters

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

Parameter Type Example
min_id int /api/v2/orders/{order_id}/messages?min_id={value}
max_id int /api/v2/orders/{order_id}/messages?max_id={value}
status string /api/v2/orders/{order_id}/messages?status={value}
customer_id string /api/v2/orders/{order_id}/messages?customer_id={value}
is_flagged string /api/v2/orders/{order_id}/messages?is_flagged={value}
min_date_created dateTime or date /api/v2/orders/{order_id}/messages?min_date_created={value}
max_date_created dateTime or date /api/v2/orders/{order_id}/messages?max_date_created={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 order_messages are returned by default.

Parameter Type Example
page int /api/v2/orders/{order_id}/messages?page={number}
limit int /api/v2/orders/{order_id}/messages?limit={count}

Get Order Message

Gets a message associated with an order.

Order Products Array

Managed by Orders Resource

Nested inside the order object, the products object/array allows you to achieve several goals:

Retrieving Product Information using GET

Name Type Description
url string The URI of a JSON object containing the product details.
resource string A context path that provides an alternate means of retrieving the data (for example, if you prefer XML).

Adding an Existing Product (that Already Exists in the Store) to the Order

Name Type Description
product_id int The ID of the product that you want to add to the order (required).
quantity int How many products of this type to add to the order (required).
product_options array These values might be required, depending on how the product’s options are set up. If the options are required, pass in the id of the product option (not the option itself) and the value of the option (not the product).
price_inc_tax int If you include a value here, it will overwrite the price (including tax) already specified for the product. This property is optional, but if you do include a value for price_inc_tax, you must also include a value for price_ex_tax.
price_ex_tax int If you include a value here, it will overwrite the price (excluding tax) already specified for the product. This property is optional, but if you do include a value for price_ex_tax, you must also include a value for price_inc_tax.

Adding a New Product (that Does Not Already Exist in the Store) to the Order

Name Type Description
name int The name of the custom product tax. (Required.)
quantity int The quantity of the purchase for this custom product tax. (Required. Can be positive or negative. Cannot be zero.)
price_inc_tax decimal The price of the custom product, including tax. (Required.)
price_ex_tax decimal The price of the custom product, excluding tax. (Required.)
sku text The SKU of the custom product. (Optional.)

Order Products

Product line item belonging to an order.

Order Product Object – Properties

Name Type Description
id int
order_id int
product_id int
order_address_id int
name string
sku string
type enum
base_price decimal
price_ex_tax decimal
price_inc_tax decimal
price_tax decimal
base_total decimal
total_ex_tax decimal
total_inc_tax decimal
total_tax decimal
weight decimal
quantity int
base_cost_price decimal
cost_price_inc_tax decimal
cost_price_ex_tax decimal
cost_price_tax decimal
is_refunded boolean
refund_amount decimal
return_id int
wrapping_name string
base_wrapping_cost decimal
wrapping_cost_ex_tax decimal
wrapping_cost_inc_tax decimal
wrapping_cost_tax decimal
wrapping_message text
quantity_shipped int
event_name string
event_date date
fixed_shipping_cost decimal
ebay_item_id string
ebay_transaction_id string
option_set_id int
parent_order_product_id int
is_bundled_product boolean
bin_picking_number string
applied_discounts object
product_options object_array
configurable_fields object_array
Manages
OAuth Scopes store_v2_orders
store_v2_orders_read_only

List Order Products

Gets the product line items associated with an order. (By default, items sort from lowest to highest according to a newly created id, separate from the order_id and the product_id.)

Filters

There are no filter parameters specific to order products.

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 order_products are returned by default.

Parameter Type Example
Page int /api/v2/orders/{order_id}/products?page={number}
Limit int /api/v2/orders/{order_id}/products?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 16,
    "order_id": 115,
    "product_id": 0,
    "order_address_id": 16,
    "name": "Cynthia Gilbert Signature Collection",
    "sku": "",
    "type": "physical",
    "base_price": "93.1800",
    "price_ex_tax": "93.1800",
    "price_inc_tax": "93.1800",
    "price_tax": "0.0000",
    "base_total": "93.1800",
    "total_ex_tax": "93.1800",
    "total_inc_tax": "93.1800",
    "total_tax": "0.0000",
    "weight": "0",
    "quantity": 1,
    "base_cost_price": "0.0000",
    "cost_price_inc_tax": "0.0000",
    "cost_price_ex_tax": "0.0000",
    "cost_price_tax": "0.0000",
    "is_refunded": false,
    "refund_amount": "0.0000",
    "return_id": 0,
    "wrapping_name": "",
    "base_wrapping_cost": "0.0000",
    "wrapping_cost_ex_tax": "0.0000",
    "wrapping_cost_inc_tax": "0.0000",
    "wrapping_cost_tax": "0.0000",
    "wrapping_message": "",
    "quantity_shipped": 0,
    "event_name": null,
    "event_date": "",
    "fixed_shipping_cost": "0.0000",
    "ebay_item_id": "",
    "ebay_transaction_id": "",
    "option_set_id": null,
    "parent_order_product_id": null,
    "is_bundled_product ": false,
    "bin_picking_number": "",
    "applied_discounts": [
      {
        "id": "coupon",
        "amount": 4.66
      }
    ],
    "product_options": [

    ],
    "configurable_fields": [

    ]
  }
]

Get an Order Product

Gets a product line item associated with the order.

Response

Example JSON returned in the response:

{
  "id": 15,
  "order_id": 114,
  "first_name": "Julie",
  "last_name": "Bishop",
  "company": "Yamia",
  "street_1": "988 Comanche Circle",
  "street_2": "",
  "city": "Cypress",
  "zip": "77426-2265",
  "country": "United States",
  "country_iso2": "US",
  "state": "Wyoming",
  "email": "",
  "phone": "5-(248)906-2014",
  "items_total": 1,
  "items_shipped": 0,
  "shipping_method": "None",
  "base_cost": "0.0000",
  "cost_ex_tax": "0.0000",
  "cost_inc_tax": "0.0000",
  "cost_tax": "0.0000",
  "cost_tax_class_id": 2,
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 2,
  "shipping_zone_id": 1,
  "shipping_zone_name": "Default Zone"
}

Get a Count of Order Products

Gets a count of order product line items.

Response

Example JSON returned in the response:

{
  "count": 17
}

Order Shipping Addresses

Customer shipping address belonging to an order.

Order Shipping Address Object – Properties

Name Type Description
id int
order_id int
first_name string
last_name string
company string
street_1 string
street_2 string
city string
zip string
country string
country_iso2 string
state string The name of the state. Should be spelled out in full, e.g.: California.
email string
phone string
items_total int
items_shipped int
shipping_method string
base_cost decimal
cost_ex_tax decimal
cost_inc_tax decimal
cost_tax decimal
cost_tax_class_id int
base_handling_cost decimal
handling_cost_ex_tax decimal
handling_cost_inc_tax decimal
handling_cost_tax decimal
handling_cost_tax_class_id int
shipping_zone_id int
shipping_zone_name string
Manages
OAuth Scopes store_v2_orders
store_v2_orders_read_only

List Order Shipping Addresses

Gets the shipping addresses associated with an order.

Filters

There are no filter parameters specific to order shipping addresses.

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 order_shipping_addresses are returned by default.

Parameter Type Example
page int /api/v2/orders/{order_id}/shipping_addresses?page={number}
limit int /api/v2/orders/{order_id}/shipping_addresses?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 15,
    "order_id": 114,
    "first_name": "Julie",
    "last_name": "Bishop",
    "company": "Yamia",
    "street_1": "988 Comanche Circle",
    "street_2": "",
    "city": "Cypress",
    "zip": "77426-2265",
    "country": "United States",
    "country_iso2": "US",
    "state": "Wyoming",
    "email": "",
    "phone": "5-(248)906-2014",
    "items_total": 1,
    "items_shipped": 0,
    "shipping_method": "None",
    "base_cost": "0.0000",
    "cost_ex_tax": "0.0000",
    "cost_inc_tax": "0.0000",
    "cost_tax": "0.0000",
    "cost_tax_class_id": 2,
    "base_handling_cost": "0.0000",
    "handling_cost_ex_tax": "0.0000",
    "handling_cost_inc_tax": "0.0000",
    "handling_cost_tax": "0.0000",
    "handling_cost_tax_class_id": 2,
    "shipping_zone_id": 1,
    "shipping_zone_name": "Default Zone"
  }
]

Get an Order Shipping Address

Gets a shipping address associated with an order.

Response

Example JSON returned in the response:

{
  "id": 15,
  "order_id": 114,
  "first_name": "Julie",
  "last_name": "Bishop",
  "company": "Yamia",
  "street_1": "988 Comanche Circle",
  "street_2": "",
  "city": "Cypress",
  "zip": "77426-2265",
  "country": "United States",
  "country_iso2": "US",
  "state": "Wyoming",
  "email": "",
  "phone": "5-(248)906-2014",
  "items_total": 1,
  "items_shipped": 0,
  "shipping_method": "None",
  "base_cost": "0.0000",
  "cost_ex_tax": "0.0000",
  "cost_inc_tax": "0.0000",
  "cost_tax": "0.0000",
  "cost_tax_class_id": 2,
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 2,
  "shipping_zone_id": 1,
  "shipping_zone_name": "Default Zone"
}

Get a Count of Shipping Addresses

Gets a count of the number of shipping addresses on an order.

Response

Example JSON returned in the response:

{
  "count": 6
}

Order Statuses

Each order status represents a state in the order fulfillment workflow.

Order Status Object – Properties

Name Type Description
id int
name string
order int
Manages
OAuth Scopes store_v2_orders
store_v2_orders_read_only

List Order Statuses

Gets the list of order statuses.

Filters

There are no filter parameters specific to order_statuses.

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 order_statuses are returned by default.

Parameter Type Example
page int /api/v2/order_statuses?page={number}
limit int /api/v2/order_statuses?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 0,
    "name": "Incomplete",
    "order": 0
  },
  {
    "id": "1",
    "name": "Pending",
    "order": "1"
  },
  {
    "id": "2",
    "name": "Shipped",
    "order": "8"
  },
  {
    "id": "3",
    "name": "Partially Shipped",
    "order": "6"
  },
  {
    "id": "4",
    "name": "Refunded",
    "order": "11"
  },
  {
    "id": "5",
    "name": "Cancelled",
    "order": "9"
  },
  {
    "id": "6",
    "name": "Declined",
    "order": "10"
  },
  {
    "id": "7",
    "name": "Awaiting Payment",
    "order": "2"
  },
  {
    "id": "8",
    "name": "Awaiting Pickup",
    "order": "5"
  },
  {
    "id": "9",
    "name": "Awaiting Shipment",
    "order": "4"
  },
  {
    "id": "10",
    "name": "Completed",
    "order": "7"
  },
  {
    "id": "11",
    "name": "Awaiting Fulfillment",
    "order": "3"
  },
  {
    "id": "12",
    "name": "Manual Verification Required",
    "order": "13"
  },
  {
    "id": "13",
    "name": "Disputed",
    "order": "12"
  }
]

Get an Order Status

Gets a single order status.

Response

Example JSON returned in the response:

{
  "id": "12",
  "name": "Manual Verification Required",
  "order": "12"
}

Order Taxes

Each tax applied to an order. This information can be useful for reporting purposes. All values are read-only.

Order Tax Object – Properties

Name Type Description
id int The unique numeric identifier of the taxes object.
order_id int The unique numeric identifier of the order to which the tax was applied. NOTE: Not included if the store was using the automatic tax feature.
order_address_id int The unique numeric identifier of the order address object associated with the order. NOTE: Not included if the store was using the automatic tax feature.
tax_rate_id int
tax_class_id int The unique numeric identifier of the tax class object. NOTE: will be 0 if automatic tax was enabled or if the default tax class was used.
name string The name of the tax class object.
class string The name of the type of tax that was applied. NOTE: will be “Automatic Tax” if automatic tax was enabled.
rate decimal The tax rate in percentage form.
priority int
priority_amount decimal
line_amount decimal
Manages
OAuth Scopes store_v2_orders
store_v2_orders_read_only

List Order Taxes

Gets the list of taxes applied to an order.

Filters

There are no filter parameters specific to order tax.

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 order_taxes are returned by default.

Parameter Type Example
Page int /api/v2/orders/{order_id}/taxes?page={number}
Limit int /api/v2/orders/{order_id}/taxes?limit={count}

Get an Order Tax

Gets an order tax item.

Shipments

Tracks a package consignment from an order that is shipped from the seller to the buyer.

Shipment Object – Properties

Name Type Description
id int Shipment ID.
order_id int ID of the order associated with this shipment.
customer_id int ID of this order’s customer.
order_address_id int ID of the associated order address.
date_created date Creation date for the shipment.
tracking_number string Tracking number of the shipment.
shipping_method string Extra detail to describe the shipment, with values like: Standard,
My Custom Shipping Method Name, etc. Can also be used for live quotes from some shipping providers.
shipping_provider string Enum of the BigCommerce shipping-carrier integration/module.
(Note: This property should be included in a POST request to create a shipment object. If it is omitted from the request, the property’s value will default to custom, and no tracking link will be generated in the email. To avoid this behavior, you can pass the property as an empty string.)
tracking_carrier string Enum of the delivery service fulfilling the shipment.
comments text Comments the shipper wishes to add.
billing_address object Billing address for this order’s customer.
shipping_address object Shipping address for this order’s customer.
items object_array The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ]
Manages
OAuth Scopes store_v2_orders
store_v2_orders_read_only

List Shipments

Gets the shipments associated with an order.

Filters

There are no filter parameters specific to shipments.

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 shipments are returned by default.

Parameter Type Example
page int /api/v2/orders/{order_id}/shipments?page={number}
limit int /api/v2/orders/{order_id}/shipments?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "order_id": 115,
    "customer_id": 0,
    "order_address_id": 16,
    "date_created": "Wed, 19 Dec 2012 17:17:10 +0000",
    "tracking_number": "111222333444",
    "shipping_method": "None",
    "shipping_provider": "ups",
    "tracking_carrier": "ups",
    "comments": "A sample shipment for order 115",
    "billing_address": {
      "first_name": "Louise",
      "last_name": "Dean",
      "company": "Skiptube",
      "street_1": "147 Meadow Vale Way",
      "street_2": "",
      "city": "Fullerton",
      "state": "Rhode Island",
      "zip": "74674",
      "country": "United States",
      "country_iso2": "US",
      "phone": "7-(086)085-9448",
      "email": ""
    },
    "shipping_address": {
      "first_name": "Louise",
      "last_name": "Dean",
      "company": "Skiptube",
      "street_1": "147 Meadow Vale Way",
      "street_2": "",
      "city": "Fullerton",
      "state": "Rhode Island",
      "zip": "74674",
      "country": "United States",
      "country_iso2": "US",
      "phone": "7-(086)085-9448",
      "email": ""
    },
    "items": [
      {
        "order_product_id": 16,
        "product_id": 0,
        "quantity": 1
      }
    ]
  }
]

Get a Shipment

Gets a shipment associated with an order.

Response

Example JSON returned in the response:

{
  "id": 12,
  "order_id": 114,
  "customer_id": 0,
  "order_address_id": 15,
  "date_created": "Wed, 19 Dec 2012 18:18:23 +0000",
  "tracking_number": "123-123-123",
  "shipping_method": "None",
  "shipping_provider": "usps",
  "tracking_carrier": "usps",
  "comments": null,
  "billing_address": {
    "first_name": "Julie",
    "last_name": "Bishop",
    "company": "Yamia",
    "street_1": "988 Comanche Circle",
    "street_2": "",
    "city": "Cypress",
    "state": "Wyoming",
    "zip": "77426-2265",
    "country": "United States",
    "country_iso2": "US",
    "phone": "5-(248)906-2014",
    "email": ""
  },
  "shipping_address": {
    "first_name": "Julie",
    "last_name": "Bishop",
    "company": "Yamia",
    "street_1": "988 Comanche Circle",
    "street_2": "",
    "city": "Cypress",
    "state": "Wyoming",
    "zip": "77426-2265",
    "country": "United States",
    "country_iso2": "US",
    "phone": "5-(248)906-2014",
    "email": ""
  },
  "items": [
    {
      "order_product_id": 15,
      "product_id": 0,
      "quantity": 1
    }
  ]
}

Get a Count of Shipments

Gets a count of the number of orders that have shipped.

Response

Example JSON returned in the response:

{
  "count": 6
}

Get a Count of Shipments per Order

Gets a count of the number of shipments that have been made for a single order.

Response

Example JSON returned in the response:

{
  "count": 6
}

Create a Shipment

Creates a new shipment for an order.

Read-only Properties

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

Requirements

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

Notes

Request

Example request object:

{
  "tracking_number": "EJ958083578US",
  "comments": "Ready to go...",
  "order_address_id": 1,
  "shipping_provider": "",
  "items": [
    {
      "order_product_id": 15,
      "quantity": 2
    }
  ]
}

Response

Example JSON returned in the response:

{
  "id": 18,
  "order_id": 113,
  "customer_id": 0,
  "order_address_id": 14,
  "date_created": "Wed, 19 Dec 2012 19:49:15 +0000",
  "tracking_number": "EJ958083578US",
  "shipping_method": "None",
  "shipping_provider": "canadapost",
  "tracking_carrier": "canada-post",
  "comments": "Ready to go...",
  "billing_address": {
    "first_name": "Henry",
    "last_name": "Boyd",
    "company": "Kare",
    "street_1": "009 Corben Pass",
    "street_2": "",
    "city": "Laguna Niguel",
    "state": "New Hampshire",
    "zip": "57762",
    "country": "United States",
    "country_iso2": "US",
    "phone": "0-(245)121-8702",
    "email": ""
  },
  "shipping_address": {
    "first_name": "Henry",
    "last_name": "Boyd",
    "company": "Kare",
    "street_1": "009 Corben Pass",
    "street_2": "",
    "city": "Laguna Niguel",
    "state": "New Hampshire",
    "zip": "57762",
    "country": "United States",
    "country_iso2": "US",
    "phone": "0-(245)121-8702",
    "email": ""
  },
  "items": [
    {
      "order_product_id": 14,
      "product_id": 0,
      "quantity": 1
    }
  ]
}

Update a Shipment

Updates an existing shipment associated with an order.

Read-only Properties

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

Request

Example request object:

{
  "tracking_number": "fedex1245",
  "comments": "Notes about the shipment",
  "order_address_id": 1
}

Response

Example JSON returned in the response:

{
  "id": 12,
  "order_id": 114,
  "customer_id": 0,
  "order_address_id": 16,
  "date_created": "Wed, 19 Dec 2012 18:18:23 +0000",
  "tracking_number": "fedex1245",
  "shipping_method": "None",
  "shipping_provider": "fedex",
  "tracking_carrier": "fedex",
  "comments": "Notes about the shipment",
  "billing_address": {
    "first_name": "Julie",
    "last_name": "Bishop",
    "company": "Yamia",
    "street_1": "988 Comanche Circle",
    "street_2": "",
    "city": "Cypress",
    "state": "Wyoming",
    "zip": "77426-2265",
    "country": "United States",
    "country_iso2": "US",
    "phone": "5-(248)906-2014",
    "email": ""
  },
  "shipping_address": {
    "first_name": "Julie",
    "last_name": "Bishop",
    "company": "Yamia",
    "street_1": "988 Comanche Circle",
    "street_2": "",
    "city": "Cypress",
    "state": "Wyoming",
    "zip": "77426-2265",
    "country": "United States",
    "country_iso2": "US",
    "phone": "5-(248)906-2014",
    "email": ""
  },
  "items": [
    {
      "order_product_id": 15,
      "product_id": 0,
      "quantity": 1
    }
  ]
}

Notes

The following properties of the shipments are optional, but if you provide both values, they must refer/map to the same carrier service:

If you provide only the shipping_provider property, then any existing saved tracking_carrier value must refer to same carrier; and vice-versa.

Possible mappings of shipping_provider values to tracking_carrier values are:

Delete a Shipment

Deletes a shipment associated with an order.

Delete Multiple Shipments

Deletes multiple shipments associated with an order.

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 shipments are returned by default.

Parameter Type Example
page int /api/v2/orders/{order_id}/shipments?page={number}
limit int /api/v2/orders/{order_id}/shipments?limit={count}

Products Reference

Products APIs support managing, searching, and displaying product-catalog information. They include Brands, Bulk Pricing Rules, Categories, Configurable Fields, Custom Fields, Google Product Search Mappings, Options, Option Set, Option-Set Options, Option Values, Products, Product Images, Product Options, Product Reviews, Product Rules, Product Videos, and SKUs.

Products

A product object represents a saleable item in the catalog.

Product Object – Properties

Name Type Description
id int The unique numerical ID of the product. Increments sequentially.
keyword_filter string (This property is deprecated.)
name string The product name.
type enum The product type. One of:
physical – a physical stock unit.
digital – a digital download.
sku string User-defined product code/stock keeping unit (SKU).
description text Product description, which can include HTML formatting.
search_keywords text A comma-separated list of keywords that can be used to locate the product when searching the store.
availability_description string Availability 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”.
price decimal The product’s price. Should include, or exclude, tax based on the store settings.
cost_price decimal The product’s cost price. Stored for reference only; not used or displayed anywhere on the store.
retail_price decimal The product’s retail cost. If entered, this retail price will be shown on the product page.
sale_price decimal Sale price. If entered, this will be used instead of value in the price field when calculating the product’s cost.
calculated_price decimal Price 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_order int 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.
is_visible boolean Flag 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_featured boolean Flag to determine whether the product should be included in the “featured products” panel for shoppers viewing the store.
related_products string Defaults 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_level int 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 int Inventory 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.
warranty text Warranty information displayed on the product page. Can include HTML formatting.
weight decimal Weight of the product, which can be used when calculating shipping costs.
width decimal Width of the product, which can be used when calculating shipping costs.
height decimal Height of the product, which can be used when calculating shipping costs.
depth decimal Depth of the product, which can be used when calculating shipping costs.
fixed_cost_shipping_price decimal A fixed shipping cost for the product. If defined, this value will be used instead of normal shipping-cost calculation during checkout.
is_free_shipping boolean Flag used to indicate whether or not the product has free shipping. If true, the shipping cost for the product will be zero.
inventory_tracking enum The 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_total int The total rating for the product.
rating_count int The total number of ratings the product has had.
total_sold int Total quantity of this product sold through transactions.
date_created date The date of which the product was created.
brand_id int The product’s brand
view_count int The number of times the product has been viewed.
page_title string Custom title for the product’s page. If not defined, the product name will be used as the page title.
meta_keywords text Custom meta keywords for the product page. If not defined, the store’s default keywords will be used.
meta_description text Custom meta description for the product page. If not defined, the store’s default meta description will be used.
layout_file string The layout template file used to render this product category.
is_price_hidden boolean The 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 hidden. (NOTE: To successfully set is_price_hidden to true, the availability value must be disabled.)
price_hidden_label string By 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.)
categories array An 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_modified date The date that the product was last modified.
event_date_field_name string Name of the field to be displayed on the product page when selecting the event/delivery date.
event_date_type enum One 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_start date When the product requires the customer to select an event/delivery date, this date is used as the “after” date.
event_date_end date When the product requires the customer to select an event/delivery date, this date is used as the “before” date.
myob_asset_account string MYOB Asset Account.
myob_income_account string MYOB Income Account.
myob_expense_account string MYOB Expense/COS Account.
peachtree_gl_account string Peachtree General Ledger Account.
condition enum The 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_shown boolean Flag used to determine whether the product’s condition will be shown to the customer on the product page.
preorder_release_date date Pre-order release date. See availability field for details on setting a product’s availability to accept pre-orders.
is_preorder_only 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.
preorder_message 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 replaced with the release date.
order_quantity_minimum int The minimum quantity an order must contain in order to purchase this product.
order_quantity_maximum int The maximum quantity an order can contain when purchasing the product.
open_graph_type enum Type of product. Acceptable values are: product, album, book, drink, food, game, movie, song, tv_show
open_graph_title string Title of the product. If not specified, the product’s name will be used instead.
open_graph_description text Description to use for the product. If not specified, the meta_description will be used instead.
is_open_graph_thumbnail boolean If set to true, the product thumbnail image will be used as the open graph image.
upc string The product UPC code, which is used in feeds for shopping comparison sites.
date_last_imported date The date on which the product was last imported using the bulk importer.
option_set_id int The 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_id int The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)
option_set_display enum The position on the product page where options from the option set will be displayed.
bin_picking_number string The BIN picking number for the product.
custom_url string Custom 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_image object An 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.)
availability enum Availability 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.
brand resource The product’s brand
downloads resource Total number of downloads for a downloadable product.
images resource See the Product Images resource for information.
discount_rules resource See the Bulk Pricing/Discount resource for information.
configurable_fields resource See the Configurable Fields resource for information.
custom_fields resource See the Custom Fields resource for information.
videos resource See the Videos resource for information.
skus resource Stock Keeping Units for the product. See the Product SKUs resource for the definition of a sku object.
rules resource Rules that apply only to this product, based on the product’s option set. See Product Rules resource for information.
option_set resource See the Product Option Sets resource for information.
options resource Options from the option set applied to the product. See the Product Options resource for information.
tax_class resource Assigned 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_code resource 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 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.)

Product Webhook Events

Product Created

store/product/created

Occurs when a product is created from the control panel, via bulk import, or via the API.

Product Updated

store/product/updated

Occurs when a product is updated from the control panel or via the API.

Product Deleted

store/product/deleted

Occurs when a product is deleted from the control panel or via the API.

Manages Product Object
OAuth Scopes store_v2_products
store_v2_products_read_only

List Products

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

Filters

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

Parameter Type Example
min_id int /api/v2/products?min_id={value}
max_id int /api/v2/products?max_id={value}
name string /api/v2/products?name={value}
keyword_filter string /api/v2/products?keyword_filter={value}
description string /api/v2/products?description={value}
sku string /api/v2/products?sku={value}
condition string /api/v2/products?condition={value}
availability string /api/v2/products?availability={value}
brand_id string /api/v2/products?brand_id={value}
min_date_created dateTime or date /api/v2/products?min_date_created={value}
max_date_created dateTime or date /api/v2/products?max_date_created={value}
min_date_modified dateTime or date /api/v2/products?min_date_modified={value}
max_date_modified dateTime or date /api/v2/products?max_date_modified={value}
min_date_last_imported date /api/v2/products?min_date_last_imported={value}
max_date_last_imported date /api/v2/products?max_date_last_imported={value}
min_price decimal /api/v2/products?min_price={value}
max_price decimal /api/v2/products?max_price={value}
min_number_sold int /api/v2/products?min_number_sold={value}
max_number_sold int /api/v2/products?max_number_sold={value}
is_visible string /api/v2/products?is_visible={value}
is_featured string /api/v2/products?is_featured={value}
min_inventory_level int /api/v2/products?min_inventory_level={value}
max_inventory_level int /api/v2/products?max_inventory_level={value}
include_sku boolean /api/v2/products?include_sku={value}
category string /api/v2/products?category={value}
product_tax_code string /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.

Parameter Type Example
Page int /api/v2/products?page={number}
Limit int /api/v2/products?limit={count}

Notes

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

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"
    }
  }
]

Get a Product

Gets a product.

Notes

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

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:

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:

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"
  }
}

Get a Product Count

Gets a count of products.

Filters

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

Parameter Type Example
min_id int /api/v2/products?min_id={value}
max_id int /api/v2/products?max_id={value}
name string /api/v2/products?name={value}
keyword_filter string /api/v2/products?keyword_filter={value}
description string /api/v2/products?description={value}
sku string /api/v2/products?sku={value}
condition string /api/v2/products?condition={value}
availability string /api/v2/products?availability={value}
brand_id string /api/v2/products?brand_id={value}
min_date_created date /api/v2/products?min_date_created={value}
max_date_created date /api/v2/products?max_date_created={value}
min_date_modified date /api/v2/products?min_date_modified={value}
max_date_modified date /api/v2/products?max_date_modified={value}
min_date_last_imported date /api/v2/products?min_date_last_imported={value}
max_date_last_imported date /api/v2/products?max_date_last_imported={value}
min_price decimal /api/v2/products?min_price={value}
max_price decimal /api/v2/products?max_price={value}
min_number_sold int /api/v2/products?min_number_sold={value}
max_number_sold int /api/v2/products?max_number_sold={value}
is_visible string /api/v2/products?is_visible={value}
is_featured string /api/v2/products?is_featured={value}
min_inventory_level int /api/v2/products?min_inventory_level={value}
max_inventory_level int /api/v2/products?max_inventory_level={value}
include_sku boolean /api/v2/products?include_sku={value}
category string /api/v2/products?category={value}
product_tax_code string /api/v2/products?product_tax_code={value}

Notes

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

Response

Example JSON returned in the response:

{
  "count": 44
}

Create a Product

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

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.

Requirements

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

Notes

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.

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.

Update a Product

Updates an existing product.

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.

Requirements

There are no required properties when updating a product.

Notes

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

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.

Delete a Product

Deletes a product.

Notes

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

204 No Content

Delete All Products

Deletes all products from the store.

Notes

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

204 No Content

Brands

Brand facets for identifying and categorizing products according to their manufacturer or company metonym.

Brand Object – Properties

Name Type Description
id int
name string The name of the brand. Must be unique.
page_title string The title shown in the browser while viewing the brand.
meta_keywords text Comma-separated list of meta keywords to include in the HTML.
meta_description text A meta description to include.
image_file string A valid image.
search_keywords string A comma-separated list of keywords that can be used to locate this brand.
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Brands

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

Filters

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

Parameter Type Example
name string /api/v2/brands?name={value}
min_id int /api/v2/brands?min_id={value}
max_id int /api/v2/brands?max_id={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, BigCommerce returns up to 50 brands by default.

Parameter Type Example
Page int /api/v2/brands?page={number}
Limit int /api/v2/brands?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "name": "Apple",
    "page_title": "",
    "meta_keywords": "",
    "meta_description": "",
    "image_file": "",
    "search_keywords": ""
  },
  {
    "id": 2,
    "name": "Microsoft",
    "page_title": "",
    "meta_keywords": "",
    "meta_description": "",
    "image_file": "",
    "search_keywords": ""
  }
]

Get a Brand

Gets a brand.

Response

Example JSON returned in the response:

{
  "id": 1,
  "name": "Apple",
  "page_title": "",
  "meta_keywords": "",
  "meta_description": "",
  "image_file": "",
  "search_keywords": ""
}

Get a Count of Brands

Returns the total number of brands in the store.

Response

Example JSON returned in the response:

{
  "count": 25
}

Create a Brand

Creates a new brand.

Read-only Properties

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

Requirements

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

Notes

To maximize system performance, BigCommerce caps the number of brands that can be added to a store at 30,000. If your POST causes the store to exceed the maximum of 30,000 brands, BigCommerce will return a 403 error.

Request

Example request object:

{
  "name": "Xmen",
  "page_title": "X men brand"
}

Response

Example JSON returned in the response:

{
  "id": 10,
  "name": "Xmen",
  "page_title": "X men brand",
  "meta_keywords": null,
  "meta_description": null,
  "image_file": "",
  "search_keywords": ""
}

Update a Brand

Updates an existing brand.

Read-only Properties

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

Requirements

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

Response

Example JSON returned in the response:

{
  "id": 10,
  "name": "Xmen",
  "page_title": "X men brand",
  "meta_keywords": null,
  "meta_description": null,
  "image_file": "t/apirmzk0a__43675.jpg",
  "search_keywords": "xmen, awesomeness"
}

Delete a Brand

Deletes a brand.

Delete All Brands

Deletes all brands belonging to a product.

Bulk Pricing

Bulk pricing rules applied to a product.

Bulk Pricing Object – Properties

Name Type Description
id string The ID of the bulk discount rule.
product_id int The ID of the product associated with this bulk discount rule.
min int The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero.
max int The maximum inclusive quantity of a product to satisfy this rule. Must be greater than the min value, unless this field has a value of 0 (zero), in which case there will be no maximum bound for this rule.
type enum
type_value decimal The value of the discount
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Bulk Pricing Rules

Gets the collection of product bulk pricing rules.

Filters

There are no filter parameters specific to discount_rules.

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 bulk_pricing_rules are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/discount_rules?page={number}
limit int /api/v2/products/{product_id}/discount_rules?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": "1",
    "product_id": 30,
    "min": 100,
    "max": 500,
    "type": "price",
    "type_value": 2
  }
]

Get a Product Bulk Pricing Rule

Gets a product bulk pricing rule.

Response

Example JSON returned in the response:

{
  "id": "1",
  "product_id": 30,
  "min": 100,
  "max": 500,
  "type": "price",
  "type_value": 2
}

Get a Count of Bulk Pricing Rules

Gets a count of the number of bulk pricing rules in the store.

Response

Example JSON returned in the response:

{
  "count": 9
}

Create a Product Bulk Pricing Rule

Creates a new product bulk pricing rule.

Read-only Properties

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

Requirements

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

Notes

To specify that a min or max value is unbounded, these properties must be explicitly set with a value of 0. If neither min nor max properties are included in the request, the existing value will remain unchanged.

The range of the min and max values must not overlap an existing rule associated with the same product.

Request

Example request object:

{
  "min": 100,
  "max": 500,
  "type": "price",
  "type_value": 2
}

Response

Example JSON returned in the response:

{
  "id": "1",
  "product_id": 30,
  "min": 100,
  "max": 500,
  "type": "price",
  "type_value": 2
}

Update a Product Bulk Pricing Rule

Updates an existing product bulk pricing rule.

Read-only Properties

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

Requirements

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

Notes

To specify that a min or max value is unbounded, these properties must be explicitly set with a value of 0. If neither min nor max properties are included in the request, the existing value will remain unchanged.

The range of the min and max values must not overlap an existing rule associated with the same product.

Request

Example request object:

{
  "min": 200,
  "max": 300,
  "type": "fixed",
  "type_value": 10
}

Response

Example JSON returned in the response:

{
  "id": "1",
  "product_id": 30,
  "min": 200,
  "max": 300,
  "type": "fixed",
  "type_value": 10
}

Delete a Product Bulk Pricing Rule

Deletes a product bulk pricing rule.

Delete Multiple Product Bulk Pricing Rules

Deletes bulk pricing rules associated with a product.

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 bulk_pricing_rules are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/discount_rules?page={number}
limit int /api/v2/products/{product_id}/discount_rules?limit={count}

Categories

Index of hierarchical categories used to organize and group products.

Category Object – Properties

Name Type Description
id int A read-only field containing the unique numeric identifier of this category.
parent_id int The ID of the parent category to which this category belongs.
(NOTE: the total number of parent categories cannot exceed seven.)
name string The name of the category. Must be unique.
description text A description for the category.
sort_order int The sort order of the category.
page_title string The page title for the category page.
meta_keywords text Comma-separated list of meta keywords to include in the HTML.
meta_description text A meta description to include.
layout_file string A valid layout file. (Please refer to this article on creating category files.)
parent_category_list array A read-only field containing the ID of this category and the ID of its parent category, if any.
image_file string A valid image.
is_visible boolean Is the category visible?
search_keywords string A comma-separated list of keywords that can be used to locate this brand.
url string The context path of this category.
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Categories

Gets the list of categories. (Default sorting is by category id, from lowest to highest.)

Filters

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

Parameter Type Example
parent_id string /api/v2/categories?parent_id={value}
name string /api/v2/categories?name={value}
is_visible string /api/v2/categories?is_visible={value}
min_id int /api/v2/categories?min_id={value}
max_id int /api/v2/categories?max_id={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 categories are returned by default.

Parameter Type Example
Page int /api/v2/categories?page={number}
Limit int /api/v2/categories?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "parent_id": 0,
    "name": "Shop Mac",
    "description": "",
    "sort_order": 0,
    "page_title": "",
    "meta_keywords": "",
    "meta_description": "",
    "layout_file": "category.html",
    "parent_category_list": [
      1
    ],
    "image_file": "",
    "is_visible": true,
    "search_keywords": "",
    "url": "/shop-mac/"
  }
]

Get a Category

Gets a single category.

Response

Example JSON returned in the response:

{
  "id": 10,
  "parent_id": 1,
  "name": "Xmen toys",
  "description": "",
  "sort_order": 2,
  "page_title": "",
  "meta_keywords": null,
  "meta_description": null,
  "layout_file": "category.html",
  "parent_category_list": [
    1,
    10
  ],
  "image_file": "d/apiy2uz6q__69888.jpg",
  "is_visible": true,
  "search_keywords": "",
  "url": "/xmen-toys/"
}

Get a Count of Categories

Gets a count of the total number of categories in the store.

Response

Example JSON returned in the response:

{
  "count": 10
}

Create a Category

Creates a new category.

Read-only Properties

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

Requirements

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

Notes

To maximize system performance, BigCommerce caps the number of categories that can be added to a store at 16,000. If your POST causes the store to exceed the maximum of 16,000 categories, BigCommerce will return a 403 error.

In addition, BigCommerce caps the total number of parent categories at seven. If your POST includes the ID of a parent category in the parent_id field, BigCommerce will check that parent category and its parent and so on to determine the total number of parent categories. If your POST would cause the total number of parent categories to exceed seven, BigCommerce will return a 403 error.

Request

Example request object:

{
  "name": "Xmen toys"
}

Response

Example JSON returned in the response:

{
  "id": 10,
  "parent_id": 1,
  "name": "Xmen toys",
  "description": "",
  "sort_order": 2,
  "page_title": "",
  "meta_keywords": null,
  "meta_description": null,
  "layout_file": "category.html",
  "parent_category_list": [
    1,
    10
  ],
  "image_file": "d/apiy2uz6q__69888.jpg",
  "is_visible": true,
  "search_keywords": "",
  "url": "/xmen-toys/"
}

Update a Category

Updates an existing category.

Read-only Properties

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

Requirements

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

Notes

To maximize system performance, BigCommerce caps the total number of parent categories at seven. If your PUT includes the ID of a parent category in the parent_id field, BigCommerce will check the parent and any children of the current category to determine the total number of parent categories. If your PUT would cause the total number of parent categories to exceed the maximum of seven, BigCommerce will return a 403 error.

Response

Example JSON returned in the response:

{
  "id": 10,
  "parent_id": 1,
  "name": "Xmen toys",
  "description": "",
  "sort_order": 2,
  "page_title": "",
  "meta_keywords": null,
  "meta_description": null,
  "layout_file": "category.html",
  "parent_category_list": [
    1,
    10
  ],
  "image_file": "d/apiy2uz6q__69888.jpg",
  "is_visible": true,
  "search_keywords": "",
  "url": "/xmen-toys/"
}

Delete a Category

Deletes a category.

Delete All Categories

Deletes all the categories in the store.

Configurable Fields

Configurable fields associated with a product.

Configurable Fields – Properties

Name Type Description
id int
product_id int
name string
type enum
allowed_file_types string
max_size int
select_options text
is_required boolean
sort_order int
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Configurable Fields

Gets the collection of configurable fields associated with a product.

Filters

There are no filter parameters specific to configurable_fields.

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 configurable_fields are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/configurable_fields?page={number}
limit int /api/v2/products/{product_id}/configurable_fields?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "product_id": 30,
    "name": "Manufacturing Country",
    "type": "T",
    "allowed_file_types": "",
    "max_size": 0,
    "select_options": "",
    "is_required": true,
    "sort_order": 1
  }
]

Get a Configurable Field

Gets a configurable field associated with a product.

Response

Example JSON returned in the response:

{
  "id": 1,
  "product_id": 30,
  "name": "Manufacturing Country",
  "type": "T",
  "allowed_file_types": "",
  "max_size": 0,
  "select_options": "",
  "is_required": true,
  "sort_order": 1
}

Get a Count of Configurable Fields

Gets a count of the number of configurable fields in the store.

Response

Example JSON returned in the response:

{
  "count": 0
}

Delete a Configurable Field

Deletes a configurable field associated with a product.

Delete Multiple Configurable Fields

Deletes multiple configurable fields associated with a product.

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 configurable_fields are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/configurable_fields?page={number}
limit int /api/v2/products/{product_id}/configurable_fields?limit={count}

Custom Fields

Custom fields associated with a product.

Custom Field Object – Properties

Name Type Description
id int
product_id int ID of the associated product
name string key
text string value
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Custom Fields

Gets custom fields associated with a product.

Filters

There are no filter parameters specific to custom_fields.

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 custom_fields are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/custom_fields?page={number}
limit int /api/v2/products/{product_id}/custom_fields?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "product_id": 30,
    "name": "Toy manufactured in",
    "text": "USA"
  },
  {
    "id": 2,
    "product_id": 45,
    "name": "Release Date",
    "text": "2013-12-25"
  }
]

Get a Custom Field

Gets a custom field associated with a product.

Response

Example JSON returned in the response:

{
  "id": 2,
  "product_id": 30,
  "name": "Toy manufactured in",
  "text": "USA"
}

Get a Count of Custom Fields

Gets a count of the number of custom fields in the store.

Response

Example JSON returned in the response:

{
  "count": 0
}

Create a Custom Field

Creates a new custom field associated with a product

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "name": "Release Date",
  "text": "2013-12-25"
}

Response

Example JSON returned in the response:

{
  "id": 5,
  "product_id": 45,
  "name": "Release Date",
  "text": "2013-12-25"
}

Update a Custom Field

Updates an existing custom field associated with a product.

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "name": "Release Date",
  "text": "2013-12-31"
}

Response

Example JSON returned in the response:

{
  "id": 5,
  "product_id": 45,
  "name": "Release Date",
  "text": "2013-12-31"
}

Delete a Custom Field

Deletes a custom field associated with a product.

Delete Multiple Custom Fields

Deletes multiple custom fields associated with a product.

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 custom_fields are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/custom_fields?page={number}
limit int /api/v2/products/{product_id}/custom_fields?limit={count}

Google Product Search Mappings

Metadata to support promoting products via Google Shopping search advertising.

Google Product Search Mapping Object – Properties

Name Type Description
enabled boolean [Descriptions are pending – will be added here]
product_id int
category_id int
custom_item boolean
global_trade_item_number string
manufacturer_part_number string
gender string
age_group string
color string
size string
material string
pattern pattern
google_shopping_product_category_path string
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Google Product Search Mappings

Gets the Google Product Search mappings for a product.

Options

Shared attributes that control value facets on a product.

Options Object – Properties

Name Type Description
id int
option_id int
display_name string
sort_order int
is_required boolean
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Options

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

Filters

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

Parameter Type Example
name string /api/v2/options?name={value}
display_name string /api/v2/options?display_name={value}
type string /api/v2/options?type={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 options are returned by default.

Parameter Type Example
Page int /api/v2/options?page={number}
Limit int /api/v2/options?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 3,
    "name": "Colors",
    "display_name": "Color",
    "type": "CS",
    "values": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/options/3/values.json",
      "resource": "/options/3/values"
    }
  },
  {
    "id": 4,
    "name": "Screen Sizes",
    "display_name": "Screen Sizes",
    "type": "RT",
    "values": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/options/4/values.json",
      "resource": "/options/4/values"
    }
  }
]

Get an Option

Gets an option.

Response

Example JSON returned in the response:

{
  "id": 3,
  "name": "Colors",
  "display_name": "Color",
  "type": "CS",
  "values": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/options/3/values.json",
    "resource": "/options/3/values"
  }
}

Get a Count of Options

Gets a count of the number of options in the store.

Response

Example JSON returned in the response:

{
  "count": 4
}

Create an Option

Creates a new option.

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "name": "Color",
  "display_name": "Color",
  "type": "CS"
}

Response

Example JSON returned in the response:

{
  "id": 10,
  "name": "Color",
  "display_name": "Color",
  "type": "CS",
  "values": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/options/10/values.json",
    "resource": "/options/10/values"
  }
}

Update an Option

Updates an existing option.

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "name": "Xmen toys",
  "display_name": "xmen extreme toys",
  "type": "T"
}

Response

Example JSON returned in the response:

{
  "id": 18,
  "name": "Xmen toys",
  "display_name": "xmen extreme toys",
  "type": "T",
  "values": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/options/18/values.json",
    "resource": "/options/18/values"
  }
}

Delete an Option

Deletes an option.

Delete All Options

Deletes all options from the store.

Option Sets

A reusable set of option facets that can be applied to products.

Option Set Object – Properties

Name Type Description
id int
name string The name of the optionset. Must be unique.
options resource
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Option Sets

Gets the collection of option sets. (Default sorting is by option-set id, from lowest to highest.)

Filters

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

Parameter Type Example
name string /api/v2/option_sets?name={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 option_sets are returned by default.

Parameter Type Example
Page int /api/v2/option_sets?page={number}
Limit int /api/v2/option_sets?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "name": "MacBook",
    "options": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/optionsets/1/options.json",
      "resource": "/optionsets/1/options"
    }
  },
  {
    "id": 2,
    "name": "PixelSkin Case",
    "options": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/optionsets/2/options.json",
      "resource": "/optionsets/2/options"
    }
  }
]

Get an Option Set

Gets an option set.

Response

Example JSON returned in the response:

{
  "id": 10,
  "name": "T-Shirt Facets",
  "options": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/optionsets/10/options.json",
    "resource": "/optionsets/13/options"
  }
}

Get a Count of Option Sets

Gets a count of the number of option sets in the store.

Response

Example JSON returned in the response:

{
  "count": 4
}

Create an Option Set

Creates a new Option set.

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "name": "T-Shirts"
}

Response

Example JSON returned in the response:

{
  "id": 10,
  "name": "T-Shirts",
  "options": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/optionsets/10/options.json",
    "resource": "/optionsets/10/options"
  }
}

Update an Option Set

Updates an existing option set.

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "name": "T-shirt Facets"
}

Response

Example JSON returned in the response:

{
  "id": 10,
  "name": "T-shirt Facets",
  "options": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/optionsets/10/options.json",
    "resource": "/optionsets/13/options"
  }
}

Delete an Option Set

Deletes an option set.

Delete All Option Sets

Deletes all option sets in the store.

Option Set Options

Options belonging to an option set.

Option Set Option: Object – Properties

Name Type Description
id int
option_id int The id of the option to which this optionset connects
option_set_id int
display_name string The friendly name used for this optionset
sort_order int The order in which the option is displayed on the product page
is_required boolean Specifies whether customer is required to enter a value for this option before they can add the product to their cart
option resource
values object_array
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Option Set Options

Gets the options associated with an option set. (Default sorting is by option id, from lowest to highest.)

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 option_set_options are returned by default.

Parameter Type Example
Page int /api/v2/option_sets/{option_set_id}/options?page={number}
Limit int /api/v2/option_sets/{option_set_id}/options?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 43,
    "option_id": 18,
    "option_set_id": 14,
    "display_name": "Size",
    "sort_order": 0,
    "is_required": true,
    "option": {
      "url": "https://example.com/api/v2/options/18.json",
      "resource": "/options/18"
    },
    "values": [
      {
        "label": "XS",
        "sort_order": 0,
        "value": "XS",
        "option_value_id": 68
      },
      {
        "label": "S",
        "sort_order": 1,
        "value": "S",
        "option_value_id": 69
      },
      {
        "label": "M",
        "sort_order": 2,
        "value": "M",
        "option_value_id": 70
      },
      {
        "label": "L",
        "sort_order": 3,
        "value": "L",
        "option_value_id": 71
      },
      {
        "label": "XL",
        "sort_order": 4,
        "value": "XL",
        "option_value_id": 72
      }
    ]
  },
  {
    "id": 44,
    "option_id": 3,
    "option_set_id": 14,
    "display_name": "Color",
    "sort_order": 1,
    "is_required": true,
    "option": {
      "url": "https://example.com/api/v2/options/3.json",
      "resource": "/options/3"
    },
    "values": [
      {
        "label": "Silver",
        "sort_order": 1,
        "value": "#cccccc",
        "option_value_id": 7
      },
      {
        "label": "Black",
        "sort_order": 2,
        "value": "#000000",
        "option_value_id": 8
      },
      {
        "label": "Purple",
        "sort_order": 3,
        "value": "#700170",
        "option_value_id": 9
      }
    ]
  }
]

Get an Option Set Option

Gets an option set option.

Response

Example JSON returned in the response:

{
  "id": 4,
  "option_id": 5,
  "option_set_id": 2,
  "display_name": "Clock Speeds (CPU)",
  "sort_order": 0,
  "is_required": true,
  "option": {
    "url": "https://example.com/api/v2/options/5.json",
    "resource": "/options/5"
  }
}

Create an Option Set Option

Creates a new option associated with an option set.

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "option_id": 10,
  "display_name": "Choose a color",
  "sort_order": 1,
  "is_required": true
}

Response

Example JSON returned in the response:

{
  "id": 2,
  "option_id": 10,
  "option_set_id": 1,
  "display_name": "Choose a color",
  "sort_order": 1,
  "is_required": true,
  "option": {
    "url": "https://example.com/api/v2/options/10.json",
    "resource": "/options/10"
  }
}

Update an Option Set Option

Updates an existing option set option.

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "display_name": "Pick a color...",
  "sort_order": 2,
  "is_required": false
}

Response

Example JSON returned in the response:

{
  "id": 2,
  "option_id": 10,
  "option_set_id": 2,
  "display_name": "Pick a color...",
  "sort_order": 2,
  "is_required": false,
  "option": {
    "url": "https://example.com/api/v2/options/10.json",
    "resource": "/options/10"
  }
}

Delete an Option Set Option

Deletes an option belonging to an option set.

Delete Multiple Option Set Options

Deletes multiple options associated with an option set.

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 option_set_options are returned by default.

Parameter Type Example
Page int /api/v2/option_sets/{option_set_id}/options?page={number}
Limit int /api/v2/option_sets/{option_set_id}/options?limit={count}

Option Values

Values that can be selected for an option.

Option Value Object – Properties

Name Type Description
id int A unique, read-only value that identifies this option value.
option_id int A read-only value identifying the option to which this option value is assigned.
label string The name of the label. Cannot be the same as the label of another value already assigned to the option.
sort_order int
value text Acceptable values generally depend on the option type, as defined in the option:

RB: string to be displayed to the customer.
RT: string to be displayed to the customer.
S: string to be displayed to the customer.
P: product ID;
PI: product ID.
CS: one of the following color values – a hexadecimal color code to create a color option (e.g., #0f0000);
a CSS 2.1 color name (e.g., blue);
up to three hexadecimal color codes and/or color names, separated by pipe symbols (e.g., #FF0000|lime|#0000FF);
a URI to an image to create a texture (e.g., http://store.com/images/myimg.png);
or the name of an image file in the store’s WebDAV import folder (e.g., myimg.png).
is_default boolean Whether or not this value is selected by default. For each option, only one option value can be selected by default.
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Option Values

Gets the values belonging to an option. (Default sorting is by option-value id, from lowest to highest.)

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 option_values are returned by default.

Parameter Type Example
Page int /api/v2/options/{option_id}/values?page={number}
Limit int /api/v2/options/{option_id}/values?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "option_id": 3,
    "label": "Silver",
    "sort_order": 2,
    "value": "#cccccc",
    "is_default": true
  },
  {
    "id": 2,
    "option_id": 3,
    "label": "Black",
    "sort_order": 1,
    "value": "#000000",
    "is_default": false
  }
]

Get an Option Value

Gets an option value.

Response

Example JSON returned in the response:

{
  "id": 9,
  "option_id": 3,
  "label": "Purple",
  "sort_order": 3,
  "value": "#700170",
  "is_default": false
}

Create an Option Value

Creates a new option value.

Read-only Properties

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

Requirements

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

Notes

To maximize system performance, BigCommerce caps the total number of values per option at 250. IF the option has 250 values and you try to create another one, BigCommerce will return a 403 error.

When you POST an is_defaultproperty of true, all other option values on the parent option will have their is_default property set to false.

Request

Example request object:

{
  "label": "white",
  "sort_order": 0,
  "value": "#FFFFFF",
  "is_default": true
}

Response

Example JSON returned in the response:

{
  "id": 68,
  "option_id": 3,
  "label": "white",
  "sort_order": 0,
  "value": "#FFFFFF",
  "is_default": true
}

Update an Option Value

Updates an existing option value.

Read-only Properties

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

Requirements

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

Notes

When you PUT an is_default property of true, all other option values on the parent option will have their is_default property set to false.

Request

Example request object:

{
  "label": "whitish",
  "sort_order": 1,
  "value": "#FFFFEF",
  "is_default": true
}

Response

Example JSON returned in the response:

{
  "id": 68,
  "option_id": 3,
  "label": "whitish",
  "sort_order": 1,
  "value": "#FFFFEF",
  "is_default": true
}

Delete an Option Value

Deletes an option value.

Delete Multiple Option Values

Deletes multiple values belonging to an option.

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 option_values are returned by default.

Parameter Type Example
Page int /api/v2/options/{option_id}/values?page={number}
Limit int /api/v2/options/{option_id}/values?limit={count}

Product Images

Images associated with a product.

Product Image Object – Properties

Name Type Description
id int
product_id int The ID of the product to which the image belongs.
image_file string When specifying a product image, the image_file should be specified as either: a path to an image already uploaded via FTP to the import directory (with the path relative to the import directory); or a URL to an image accessible on the internet.
is_thumbnail boolean If true, the image is used as the product’s thumbnail.
sort_order int The order in which the image will be displayed on the product page. Lower integers will give the image a higher priority. If the image is given a lower priority, then when updating, all images with a sort_order the same or greater than the image’s new sort_order value will have their sort_order reordered.
description text The description for the image
date_created date
Manages Product Image Object
OAuth Scopes store_v2_products
store_v2_products_read_only

List Product Images

Gets the images associated with a product. (Default sorting is by image id, from lowest to highest.)

Filters

There are no filter parameters specific to product images.

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 product_images are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/images?page={number}
limit int /api/v2/products/{product_id}/images?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 247,
    "product_id": 32,
    "image_file": "sample_images/in_123__14581.jpg",
    "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.386.513.jpg?c=1",
    "standard_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.220.290.jpg?c=1",
    "tiny_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/247/in_123__14581.1393831046.44.58.jpg?c=1",
    "is_thumbnail": true,
    "sort_order": 0,
    "description": null,
    "date_created": "Mon, 24 Sep 2012 01:14:30 +0000"
  },
  {
    "id": 248,
    "product_id": 32,
    "image_file": "sample_images/in_122__93910.jpg",
    "zoom_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/248/in_122__93910.1393831046.1280.1280.jpg?c=1",
    "thumbnail_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/248/in_122__93910.1393831046.386.513.jpg?c=1",
    "standard_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/248/in_122__93910.1393831046.220.290.jpg?c=1",
    "tiny_url": "https://cdn.url.path/bcapp/et7xe3pz/products/32/images/248/in_122__93910.1393831046.44.58.jpg?c=1",
    "is_thumbnail": false,
    "sort_order": 1,
    "description": null,
    "date_created": "Mon, 24 Sep 2012 01:17:14 +0000"
  }
]

Get a Product Image

Gets a product image.

Response

Example JSON returned in the response:

{
  "id": 248,
  "product_id": 32,
  "image_file": "sample_images/in_122__93910.jpg",
  "zoom_url": "https://cdn.bcapp.dev/bcapp/et7xe3pz/products/32/images/248/in_122__93910.1393831046.1280.1280.jpg?c=1",
  "thumbnail_url": "https://cdn.bcapp.dev/bcapp/et7xe3pz/products/32/images/248/in_122__93910.1393831046.386.513.jpg?c=1",
  "standard_url": "https://cdn.bcapp.dev/bcapp/et7xe3pz/products/32/images/248/in_122__93910.1393831046.220.290.jpg?c=1",
  "tiny_url": "https://cdn.bcapp.dev/bcapp/et7xe3pz/products/32/images/248/in_122__93910.1393831046.44.58.jpg?c=1",
  "is_thumbnail": false,
  "sort_order": 1,
  "description": null,
  "date_created": "Mon, 24 Sep 2012 01:17:14 +0000"
}

Get a Count of Product Images

Gets a count of the number of product images in the store.

Response

Example JSON returned in the response:

{
  "count": 105
}

Create a Product Image

Creates a new product image.

Read-only Properties

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

Requirements

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

Response

Example JSON returned in the response:

{
  "id": 116,
  "product_id": 29,
  "image_file": "p/022/astonishing-x-men-1-100k__36562.jpg",
  "is_thumbnail": false,
  "sort_order": 0,
  "description": "",
  "date_created": "Fri, 21 Dec 2012 18:54:04 +0000"
}

Update a Product Image

Updates an existing product image.

Read-only Properties

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

Requirements

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

Response

Example JSON returned in the response:

{
  "id": 118,
  "product_id": 30,
  "image_file": "k/392/ud2vk0n1l0zcfr7gtlqi__43888.png",
  "is_thumbnail": false,
  "sort_order": 1,
  "description": "",
  "date_created": "Fri, 21 Dec 2012 19:01:03 +0000"
}

Delete a Product Image

Deletes a product image.

Delete Multiple Product Images

Deletes multiple product images.

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 product_images are returned by default.

Parameter Type Example
Page int /api/v2/products/{product_id}/images?page={number}
Limit int /api/v2/products/{product_id}/images?limit={count}

Product Options

Managed by Product Options Resource

Product Options Object – Properties

Title Name Type Description
id int
option_id int
display_name string
sort_order int
is_required boolean
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Product Options

Gets the options associated with a product.

Filters

There are no filter parameters specific to product options.

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 product_options are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/options?page={number}
limit int /api/v2/products/{product_id}/options?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 13,
    "option_id": 8,
    "display_name": "iPod Capacities",
    "sort_order": 0,
    "is_required": true
  },
  {
    "id": 14,
    "option_id": 9,
    "display_name": "Accessories",
    "sort_order": 1,
    "is_required": false
  }
]

Get a Product Option

Gets an option associated with a product.

Response

Example JSON returned in the response:

{
  "id": 14,
  "option_id": 9,
  "display_name": "Accessories",
  "sort_order": 1,
  "is_required": false
}

Product Reviews

Reviews associated with a product.

Product Review Object – Properties

Name Type Description
id int Unique database ID for this product review. Read-only.
product_id int The ID of the product to which this review belongs. Read-only.
author string The review’s author, displayed on the storefront.
date_created date RFC 2822 date that specifies the creation time of the review. (If not specified, will use the current time.)
rating int A whole number from 1–5, specifying the product’s rating in this review.
title string The review’s title, displayed on the storefront.
review text The full text of the review, displayed on the storefront.
status int A status indicator. 0=“Pending”, 1= “Approved”, 2=“Disapproved”.
Manages Product Review Object
OAuth Scopes store_v2_products
store_v2_products_read_only

List Product Reviews

Gets the reviews associated with a product. (Default sorting is by review id, from lowest to highest.)

Filters

There are no filter parameters specific to product reviews.

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 product_reviews are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/reviews?page={number}
limit int /api/v2/products/{product_id}/reviews?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 190,
    "product_id": 5310,
    "author": "John Doe",
    "date_created": "Wed, 12 Dec 2012 06:00:00 +0000",
    "title": "My experience with the widget",
    "review": "This widget worked for me, but might not work for everyone.",
    "rating": 4,
    "status": 1
  },
  {
    "id": 191,
    "product_id": 5310,
    "author": "Jane Doe",
    "date_created": "Tue, 12 Nov 2013 06:00:00 +0000",
    "title": "Great product, slow shipping",
    "review": "Took two weeks to arrive",
    "rating": 3,
    "status": 1
  },
  {
    "id": 192,
    "product_id": 5310,
    "author": "Jimmy Doe",
    "date_created": "Fri, 14 Dec 2012 06:00:00 +0000",
    "title": "Worked for me!",
    "review": "I thought this product was pretty good",
    "rating": 5,
    "status": 1
  }
]

Get a Product Review

Gets a product review.

Response

Example JSON returned in the response:

{
  "id": 190,
  "product_id": 5310,
  "author": "John Doe",
  "date_created": "Wed, 12 Dec 2012 06:00:00 +0000",
  "title": "My experience with the widget",
  "review": "This widget worked for me, but might not work for everyone.",
  "rating": 4,
  "status": 1
}

Create a Product Review

Creates a new product review.

Notes

The review property is the review’s text. The rating property must be a whole number between 1–5. If the optional date_created property is not specified, it defaults to the current date/time. If the optional “status” property is not specified, it defaults to 0 [Pending]. Other allowable values are 1 [Approved] or 2 [Disapproved].)

Read-only Properties

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

Requirements

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

Response

Example JSON returned in the response:

{
  "id": 8,
  "product_id": 32,
  "author": "Jimmy Doe",
  "date_created": "Tue, 05 Mar 2013 06:00:00 +0000",
  "title": "Worked for me!",
  "review": "I thought this product was pretty good",
  "rating": 5,
  "status": 0
}

Update a Product Review

Updates an existing product review. Your request may update any of the properties that are writeable for the Create (POST) operation.

Read-only Properties

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

Response

Example JSON returned in the response:

{
  "id": 8,
  "product_id": 32,
  "author": "Jimmy Doe",
  "date_created": "Tue, 05 Mar 2013 06:00:00 +0000",
  "title": "Worked for me!",
  "review": "I thought this product was pretty good",
  "rating": 5,
  "status": 1
}

Delete a Product Review

Deletes a specified product review. (If successful, this will typically return a 204 No Content.)

Delete All Product Reviews

Deletes all reviews for the specified product. (If successful, this will typically return a 204 No Content.)

Product Rules

Rules that modify the properties of a product, such as weight, price, and product image.

Product Rule Object – Properties

Name Type Description
id int The ID of the rule.
product_id int The ID of the product to which the rule belongs.
sort_order int The order in which the rule will be displayed on the product page. Lower integers will give the rule a higher priority. If the rule is given a lower priority, then when updating, all rules with a sort_order the same or greater than the rule’s new sort_order value will have their sort_order reordered.
is_enabled boolean If set to true, the rule will be evaluated when a customer configures a product’s options.
is_stop boolean If set to true and the rule evaluates to true, no more rules with a higher sort_order will be processed.
price_adjuster object If a product option rule specifies a change to the price based on an option, the price_adjuster object will consist of two name/value pairs. The first pair is named adjuster and contains one of the following values: relative, percentage, or absolute. The percentage value causes the price to vary based on either a positive or negative percentage. The relative value causes the price to vary by either a positive or negative monetary amount. The absolute value resets the price, so it should always be a positive number. The second pair is named adjuster_value and contains a decimal value representing one of the following: the amount to add or subtract from the price, the percentage by which the price should change, or the new price (as per the adjuster setting). If the product option rule does not specify a change to the price based on size or color, price_adjuster will be null.
weight_adjuster object If a product option rule specifies a change to the weight based on an option, the weight_adjuster object will consist of two name/value pairs. The first pair is named adjuster and contains one of the following values: relative or absolute. The relative value causes the weight to vary by either a positive or negative amount. The absolute value resets the weight, so it should always be a positive number. The second pair is named adjuster_value and contains a decimal value representing one of the following: the amount to add or subtract from the weight or the new weight (as per the adjuster setting). If the product option rule does not specify a change to the price based on size or color, weight_adjuster will be null.
is_purchasing_disabled boolean If true this rule prohibits purchasing the product with the configured option values.
purchasing_disabled_message string The message to display if the rule disabled purchasing the product.
is_purchasing_hidden boolean If true the rule hides the options on the product. Setting this to true has no effect if the rule is based on an SKU or has conditions from multiple product options.
image_file string When specifying a product rule, the image_file should be specified as either: A path to an rule already uploaded via FTP in the import directory and the path should be relative from the import directory. It can be a URL to an rule accessible on the internet.
conditions array The conditions array can contain one or more objects. Each object inside the array contains three name/value pairs, but at least one value will be missing at any given time. If a product_option_id value is present, then a option_value_id must also be present. If product_option_id and option_value_id values are present, then a sku_id value must not be present. This also holds true in the reverse, where if a sku_id value exists, values for the product_option_id and option_value_id cannot exist. NOTE: if you can use a SKU value, this is preferred for simplicity. Empty values are represented as null. If multiple objects are included in the array, the software runs through them using an AND/OR logic. Objects with identical product_option_id values will be linked with an OR. Objects with different product_option_id values will be linked with an AND. When one object contains a sku_id value and the other contains product_option_id and option_value_id values, they will be linked with an AND. Two objects which both contain sku_id values will be linked with an OR.
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Product Rules

Gets the collection of rules associated with a product. (Default sorting is by rule id, from lowest to highest.)

Filters

There are no filter parameters specific to product rules.

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 product_rules are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/rules?page={number}
limit int /api/v2/products/{product_id}/rules?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "product_id": 3,
    "sort_order": 0,
    "is_enabled": true,
    "is_stop": false,
    "price_adjuster": null,
    "weight_adjuster": null,
    "is_purchasing_disabled": false,
    "purchasing_disabled_message": "",
    "is_purchasing_hidden": false,
    "image_file": "attribute_rule_images/1_source.jpg",
    "conditions": [
      {
        "product_option_id": 4,
        "option_value_id": 7,
        "sku_id": null
      }
    ]
  },
  {
    "id": 2,
    "product_id": 3,
    "sort_order": 1,
    "is_enabled": true,
    "is_stop": false,
    "price_adjuster": null,
    "weight_adjuster": null,
    "is_purchasing_disabled": false,
    "purchasing_disabled_message": "",
    "is_purchasing_hidden": false,
    "image_file": "attribute_rule_images/2_source.jpg",
    "conditions": [
      {
        "product_option_id": 4,
        "option_value_id": 8,
        "sku_id": null
      }
    ]
  }
]

Get a Product Rule

Gets a single product rule.

Response

Example JSON returned in the response:

{
  "id": 2,
  "product_id": 3,
  "sort_order": 1,
  "is_enabled": true,
  "is_stop": false,
  "price_adjuster": null,
  "weight_adjuster": null,
  "is_purchasing_disabled": false,
  "purchasing_disabled_message": "",
  "is_purchasing_hidden": false,
  "image_file": "attribute_rule_images/2_source.jpg",
  "conditions": [
    {
      "product_option_id": 4,
      "option_value_id": 8,
      "sku_id": null
    }
  ]
}

Get a Count of Product Rules

Gets a count of the number of product rules in the store.

Response

Example JSON returned in the response:

{
  "count": 3
}

Create a Product Rule

Creates a new product rule.

Read-only Properties

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

Requirements

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

Response

Example JSON returned in the response:

{
  "id": 10,
  "product_id": 3,
  "sort_order": 1,
  "is_enabled": true,
  "is_stop": false,
  "price_adjuster": null,
  "weight_adjuster": null,
  "is_purchasing_disabled": false,
  "purchasing_disabled_message": "",
  "is_purchasing_hidden": false,
  "image_file": "attribute_rule_images/2_source.jpg",
  "conditions": [
    {
      "product_option_id": 4,
      "option_value_id": 8,
      "sku_id": null
    }
  ]
}

Update a Product Rule

Updates an existing product rule.

Notes

If you include a conditions object array, its contents will be appended to any existing conditions. This operation does not overwrite existing conditions.

Read-only Properties

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

Requirements

There are no property requirements for updating a product rule.

Response

Example JSON returned in the response:

{
  "id": 2,
  "product_id": 3,
  "sort_order": 2,
  "is_enabled": true,
  "is_stop": false,
  "price_adjuster": null,
  "weight_adjuster": null,
  "is_purchasing_disabled": false,
  "purchasing_disabled_message": "",
  "is_purchasing_hidden": false,
  "image_file": "attribute_rule_images/2_source.jpg",
  "conditions": [
    {
      "product_option_id": 4,
      "option_value_id": 8,
      "sku_id": null
    }
  ]
}

Delete a Product Rule

Deletes a product rule.

Delete Multiple Product Rules

Deletes multiple product rules.

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 product_rules are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/rules?page={number}
limit int /api/v2/products/{product_id}/rules?limit={count}

Videos

Embedded videos displayed on product listings.

Videos Object – Properties

Name Type Description
id string
product_id int
sort_order int
name string
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Product Videos

Gets the videos associated with a product.

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 product_videos are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/videos?page={number}
limit int /api/v2/products/{product_id}/videos?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": "UmhvxsOwhqk",
    "product_id": 30,
    "sort_order": 0,
    "name": "X-Men Evolution: Season 1, Episode 1"
  }
]

Get a Product Video

Gets a product video.

Get a Count of Product Videos

Gets a count of the number of product videos in the store.

Response

Example JSON returned in the response:

{
  "count": 0
}

Create a Product Video

Adds a link to a YouTube video to a product.

Read-only Properties

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

Requirements

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

Notes

Only YouTube videos are supported. To create a new video, pass the full url in the request body.

Request

Example request object:

{
  "url": "https://www.youtube.com/watch?v=4wZ3ZG_Wams"
}

Update Product Video Metadata

Edit the metadata of a product video.

Read-only Properties

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

Requirements

There are no required properties when updating a product video.

Notes

The name, sort_order and url properties of the product video are editable.

Posting a new url will update the id of the video to reference the new video.

Request

Example request object:

{
  "name": "New video title",
  "sort_order": 2
}

Delete a Product Video

Delete a product video.

Delete All Product Videos

Deletes all videos belonging to a product.

SKUs

Stock Keeping Unit identifiers associated with products or product options.

SKU Object – Properties

Name Type Description
id int
product_id int
sku string The unique SKU (stock keeping unit).
price decimal This SKU’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.
adjusted_price decimal The SKU’s price on the storefront – after the product’s base price is inherited, and/or any option set or any product rules are applied. This property is READ-ONLY.
cost_price decimal The product’s cost price.
upc string The UPC (Universal Product Code) for this product combination.
inventory_level int The inventory level for the product.
inventory_warning_level int The inventory warning level for the product .
bin_picking_number string The BIN picking number.
weight decimal This SKU’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.
adjusted_weight decimal This SKU’s weight on the storefront – after the product’s base weight is inherited, and/or any option set or any product rules are applied. This property is READ-ONLY.
is_purchasing_disabled boolean if true, this prohibits purchasing of the SKU.
purchasing_disabled_message string The message to display if purchasing is disabled on this SKU.
image_file string The image that will be displayed when this SKU is selected on the storefront. When updating a SKU image, send the publicly accessible URL. Supported image formats are JPEG, PNG, and GIF.
options object_array This is an object {“product_option_id”: int, “option_value_id”:int}
Manages
OAuth Scopes store_v2_products
store_v2_products_read_only

List Product SKUs

Gets the collection of SKUs associated with a product.

Notes

BigCommerce has updated the SKU schema to include additional price, weight, image, and purchasable properties. We will eventually remove the ability to manage these properties via SKU rules. (Merchants are already constrained from creating SKU-only rules in the BigCommerce control panel.)

Filters

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

Parameter Type Example
min_id int /api/v2/products/{product_id}/skus?min_id={value}
max_id int /api/v2/products/{product_id}/skus?max_id={value}
sku string /api/v2/products/{product_id}/skus?sku={value}
upc string /api/v2/products/{product_id}/skus?upc={value}
inventory_level string /api/v2/products/{product_id}/skus?inventory_level={value}
inventory_warning_level string /api/v2/products/{product_id}/skus?inventory_warning_level={value}
bin_picking_number string /api/v2/products/{product_id}/skus?bin_picking_number={value}
min_inventory_level int /api/v2/products/{product_id}/skus?min_inventory_level={value}
max_inventory_level int /api/v2/products/{product_id}/skus?max_inventory_level={value}
is_low_inventory boolean /api/v2/products/{product_id}/skus?is_low_inventory={value}
product_hash int /api/v2/products/{product_id}/skus?product_hash={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 skus are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/skus?page={number}
limit int /api/v2/products/{product_id}/skus?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "product_id": 5,
    "sku": "MB-1",
    "price": null,
    "adjusted_price": "1.5000",
    "cost_price": "0.0000",
    "upc": "",
    "inventory_level": 0,
    "inventory_warning_level": 0,
    "bin_picking_number": "",
    "weight": null,
    "adjusted_weight": "0.00",
    "is_purchasing_disabled": false,
    "purchasing_disabled_message": "",
    "image_file": "",
    "options": [
      {
        "product_option_id": 15,
        "option_value_id": 17
      },
      {
        "product_option_id": 16,
        "option_value_id": 28
      }
    ]
  },
  {
    "id": 2,
    "product_id": 5,
    "sku": "MB-2",
    "price": null,
    "adjusted_price": "2.0000",
    "cost_price": "0.0000",
    "upc": "",
    "inventory_level": 0,
    "inventory_warning_level": 0,
    "bin_picking_number": "",
    "weight": null,
    "adjusted_weight": "0.00",
    "is_purchasing_disabled": true,
    "purchasing_disabled_message": "We're sorry, this is unavailable.",
    "image_file": "",
    "options": [
      {
        "product_option_id": 15,
        "option_value_id": 18
      },
      {
        "product_option_id": 16,
        "option_value_id": 26
      }
    ]
  }
]

Get a Product SKU

Gets a single product SKU.

Response

Example JSON returned in the response:

{
  "id": 5,
  "product_id": 7,
  "sku": "MBA-1atest",
    "price": null,
    "adjusted_price": "1.5000",
  "cost_price": "0.0000",
  "upc": "",
  "inventory_level": 0,
  "inventory_warning_level": 0,
  "bin_picking_number": "",
    "weight": null,
    "adjusted_weight": "0.00",
    "is_purchasing_disabled": false,
    "purchasing_disabled_message": "",
    "image_file": "https://thinglust.com/eyecandy.png",
  "options": [
    {
      "product_option_id": 20,
      "option_value_id": 51
    }
  ]
}

Get a Count of Product SKUs

Gets a count of the number of product SKUs in the store.

Response

Example JSON returned in the response:

{
  "count": 1235
}

Create a Product SKU

Creates a new product SKU.

Read-only Properties

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

Requirements

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

Notes

To maximize system performance, BigCommerce caps the number of SKUs associated with a product at 500. If you attempt to add a SKU to a product that has 500 SKUs, BigCommerce will return a 403 error.

BigCommerce has updated the SKU schema to include additional price, weight, image, and purchasable properties. We will eventually remove the ability to manage these properties via SKU rules. (Merchants are already constrained from creating SKU-only rules in the BigCommerce control panel.)

Response

Example JSON returned in the response:

{
  "id": 5,
  "product_id": 7,
  "sku": "MBA-1atest",
    "price": null,
    "adjusted_price": "1.5000",
  "cost_price": "0.0000",
  "upc": "",
  "inventory_level": 0,
  "inventory_warning_level": 0,
  "bin_picking_number": "",
    "weight": null,
    "adjusted_weight": "0.00",
    "is_purchasing_disabled": false,
    "purchasing_disabled_message": "",
    "image_file": "",
  "options": [
    {
      "product_option_id": 20,
      "option_value_id": 51
    }
  ]
}

Update a Product SKU

Updates an existing product SKU.

Read-only Properties

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

Requirements

There are no required properties for updating a product SKU.

Response

Example JSON returned in the response:

{
  "id": 5,
  "product_id": 7,
  "sku": "MBA-1atest",
    "price": "4.9900",
    "adjusted_price": "3.9900",
  "cost_price": "2.9900",
  "upc": "",
  "inventory_level": 0,
  "inventory_warning_level": 0,
  "bin_picking_number": "",
    "weight": null,
    "adjusted_weight": "0.00",
    "is_purchasing_disabled": true,
    "purchasing_disabled_message": "We're sorry, this is unavailable.",
    "image_file": "",
  "options": [
    {
      "product_option_id": 20,
      "option_value_id": 51
    }
  ]
}

Delete a Product SKU

Deletes a product SKU.

Delete Multiple Product SKUs

Deletes multiple product SKUs.

Filters

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

Parameter Type Example
min_id int /api/v2/products/{product_id}/skus?min_id={value}
max_id int /api/v2/products/{product_id}/skus?max_id={value}
sku string /api/v2/products/{product_id}/skus?sku={value}
upc string /api/v2/products/{product_id}/skus?upc={value}
inventory_level string /api/v2/products/{product_id}/skus?inventory_level={value}
inventory_warning_level string /api/v2/products/{product_id}/skus?inventory_warning_level={value}
bin_picking_number string /api/v2/products/{product_id}/skus?bin_picking_number={value}
min_inventory_level int /api/v2/products/{product_id}/skus?min_inventory_level={value}
max_inventory_level int /api/v2/products/{product_id}/skus?max_inventory_level={value}
is_low_inventory boolean /api/v2/products/{product_id}/skus?is_low_inventory={value}
product_hash int /api/v2/products/{product_id}/skus?product_hash={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 skus are returned by default.

Parameter Type Example
page int /api/v2/products/{product_id}/skus?page={number}
limit int /api/v2/products/{product_id}/skus?limit={count}

Store Content Reference

Store Content APIs help merchants edit and publish blog posts and Web pages, improve SEO, and drive traffic to stores. They include Blog Posts, Blog Tags, Redirects, and Pages.

Blog Posts

A content entry in the store’s blog.

Blog Post Object – Properties

Name Type Description
id int
title string
url string
preview_url string
body string
tags array of strings
summary string
is_published boolean
published_date date string, or object When including the blog post’s published_date in PUT or POST requests, supply it as a flat date string in valid RFC 2822 or ISO 8601 format.

In GET requests, the published_date is returned as an object, whose members are: date (date string); timezone_type (integer); and timezone (string representing an hours:minutes offset, in the format "+hh:mm" or "-hh:mm").
published_date_iso8601 date string Published date in ISO 8601 format.
meta_description string
meta_keywords string
author string
thumbnail_path string
Manages
OAuth Scopes store_v2_content
store_v2_content_read_only

List Blog Posts

Gets the collection of blog posts. (Default sorting is by published_date, from most-recent to earliest.)

Filters

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

Parameter Type Example
is_published string /stores/{store_hash}/v2/blog/posts?is_published={value}
url string /stores/{store_hash}/v2/blog/posts?url={value}
tag string /stores/{store_hash}/v2/blog/posts?tag={value}
published_date string /stores/{store_hash}/v2/blog/posts?published_date={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 blog_posts are returned by default.

Parameter Type Example
Page int /stores/{store_hash}/v2/blog/posts?page={number}
Limit int /stores/{store_hash}/v2/blog/posts?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 2,
    "title": "Ten Great New Products",
    "url": "/blog/ten-great-new-products/",
    "preview_url": "/blog/ten-great-new-products/?preview=53829a3bb47f4",
    "body": "<p>Here's ten new products that make great gifts...</p>",
    "tags": [
      "New",
      "Products"
    ],
    "summary": "Here's ten new products that make great gifts...",
    "is_published": false,
    "published_date": {
        "date": "2013-05-09 08:35:45.000000",
        "timezone_type": 1,
        "timezone": "+00:00"
        },
    "published_date_iso8601": "2013-05-09T14:35:45+0000",
    "meta_description": null,
    "meta_keywords": "New,Products",
    "author": "",
    "thumbnail_path": ""
  },
  {
    "id": 1,
    "title": "Your first blog post!",
    "url": "/your-first-blog-post/",
    "preview_url": "/your-first-blog-post/",
    "body": "<p> <strong>Welcome to your blog!</strong><br> A blog is a great place to share details on your products, business, and whatever else you think your shoppers might like to hear from you. You can include photos in your blog posts, and even videos. For ideas and inspiration on how to structure your blog, take a look at the BigCommerce <a href='http://blog.bigcommerce.com/' target='_blank'>ecommerce blog</a>.</p><p><strong>How can I delete this post?</strong><br>To delete this post and add your own, log in to your <a href='/admin' target='_blank'>admin area</a>, click the Content tab at the top of the screen, and choose Blog.</p><p><strong>Powered by BigCommerce</strong><br>Your website, online store, and blog are powered by BigCommerce <a href='http://www.bigcommerce.com/' target='_blank'>ecommerce software</a>. It includes everything you need to run a beautiful online store, including <a href='http://www.bigcommerce.com/templates/' target='_blank'>ecommerce website templates</a>, <a href='http://www.bigcommerce.com/features/hosting/' target='_blank'>ecommerce hosting</a>, an <a href='http://www.bigcommerce.com/features/setup/' target='_blank'>online shopping cart</a>, and more.</p>",
    "tags": [
      "Blog",
      "SEO"
    ],
    "summary": " Welcome to your blog! A blog is a great place to share details on your products, business, and whatever else you think your shoppers might like to hear from you. You can include photos in your blog posts, and even videos. For ideas and inspiration on how to structure your blog, take a look [...]",
    "is_published": true,
    "published_date": {
        "date": "2013-05-09 08:35:45.000000",
        "timezone_type": 1,
        "timezone": "+00:00"
        },
    "published_date_iso8601": "2013-05-09T14:35:45+0000",
    "meta_description": "",
    "meta_keywords": "Blog,SEO",
    "author": "",
    "thumbnail_path": ""
  }
]

Get a Blog Post

Gets a blog post.

Response

Example JSON returned in the response:

{
  "id": 1,
  "title": "Your first blog post!",
  "url": "/your-first-blog-post/",
  "preview_url": "/your-first-blog-post/",
  "body": "<p> <strong>Welcome to your blog!</strong><br> A blog is a great place to share details on your products, business, and whatever else you think your shoppers might like to hear from you. You can include photos in your blog posts, and even videos. For ideas and inspiration on how to structure your blog, take a look at the BigCommerce <a href='http://blog.bigcommerce.com/' target='_blank'>ecommerce blog</a>.</p><p><strong>How can I delete this post?</strong><br>To delete this post and add your own, log in to your <a href='/admin' target='_blank'>admin area</a>, click the Content tab at the top of the screen, and choose Blog.</p><p><strong>Powered by BigCommerce</strong><br>Your website, online store, and blog are powered by BigCommerce <a href='http://www.bigcommerce.com/' target='_blank'>ecommerce software</a>. It includes everything you need to run a beautiful online store, including <a href='http://www.bigcommerce.com/templates/' target='_blank'>ecommerce website templates</a>, <a href='http://www.bigcommerce.com/features/hosting/' target='_blank'>ecommerce hosting</a>, an <a href='http://www.bigcommerce.com/features/setup/' target='_blank'>online shopping cart</a>, and more.</p>",
  "tags": [
    "Blog",
    "SEO"
  ],
  "summary": " Welcome to your blog! A blog is a great place to share details on your products, business, and whatever else you think your shoppers might like to hear from you. You can include photos in your blog posts, and even videos. For ideas and inspiration on how to structure your blog, take a look [...]",
  "is_published": true,
    "published_date": {
        "date": "2013-05-09 08:35:45.000000",
        "timezone_type": 1,
        "timezone": "+00:00"
        },
    "published_date_iso8601": "2013-05-09T14:35:45+0000",
  "meta_description": "",
  "meta_keywords": "Blog,SEO",
  "author": "",
  "thumbnail_path": ""
}

Get a Count of Blog Posts

Gets a count of blog posts.

Response

Example JSON returned in the response:

{
  "count": 6
}

Create a Blog Post

Creates a new blog post.

Read-only Properties

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

Requirements

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

Notes

Request

Example request object:

{
  "title": "A Sample Blog Post",
  "body": "<p>This is a blog post.</p>",
  "author": "Author Name",
  "thumbnail_path": "http://cdn.example.com/sample-post.jpg",
  "published_date": "Mon, 09 May 2015 16:20:04 +0400",
  "is_published": true,
  "tags": [
    "Blog",
    "Example"
  ]
}

Update a Blog Post

Updates an existing blog post.

Read-only Properties

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

Notes

Request

Example request object:

{
  "title": "New: A Sample Blog Post",
  "url": "/blog/sample-post",
  "published_date": "Wed, 01 Jan 2017 15:33:33 +0400"
}

Delete a Blog Post

Deletes a blog post.

Delete Multiple Blog Posts

Deletes multiple blog posts in the collection.

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 blog posts are returned by default.

Parameter Type Example
Page int /api/v2/blog/posts?page={number}
Limit int /api/v2/blog/posts?limit={count}

Blog Tags

Index of tags used on the store’s blog.

Manages
OAuth Scopes store_v2_content
store_v2_content_read_only

List Tags

List of tags with associated blog posts.

Response

Example JSON returned in the response:

[
  {
    "tag": "Blog",
    "post_ids": [
      1
    ]
  },
  {
    "tag": "New",
    "post_ids": [
      2
    ]
  },
  {
    "tag": "Products",
    "post_ids": [
      2
    ]
  },
  {
    "tag": "Seo",
    "post_ids": [
      1
    ]
  }
]

Pages

A static Web page on the storefront.

Page Object – Properties

Name Type Description
id int Unique ID of this Web page.
parent_id int ID of any parent Web page.
type enum Enum identifying this page’s type, with the following possible values:
page: free-text page;
link: link to another Web address;
rss_feed: syndicated content from an RSS feed;
contact_form: a contact form;
raw: a page that allows for raw HTML to be entered into the body. (Note: No template is used when rendering the page.)
contact_fields object Where the page’s type is a contact form: object whose members are the fields enabled (in the control panel) for storefront display. Possible members are:
fullname: full name of the customer submitting the form;
phone: customer’s phone number, as submitted on the form;
companyname: customer’s submitted company name;
orderno: customer’s submitted order number;
rma: customer’s submitted RMA (Return Merchandise Authorization) number.
email string Where the page’s type is a contact form: email address that receives messages sent via the form.
name string Page name, as displayed on the storefront.
url string Relative URL on the storefront for this page.
meta_description text Description contained within this page’s <meta> element.
body text HTML or variable that populates this page’s <body> element, in default/desktop view.
mobile_body text HTML or variable that populates this page’s <body> element, in mobile view.
has_mobile_version boolean If true, this page has a mobile version.
is_visible boolean If true, this page appears in the storefront’s navigation menu.
is_homepage boolean If true, this page is the storefront’s home page.
meta_title string Text specified for this page’s <title> element. (If empty, the value of the name property is used.)
layout_file string Layout template for this page.
sort_order int Order in which this page should display on the storefront. (Lower integers specify earlier display.)
meta_title string Text contained within this page’s <title> element.
search_keywords string Comma-separated list of keywords that shoppers can use to locate this page when searching the store.
meta_keywords string Comma-separated list of SEO-relevant keywords to include in the page’s <meta> element.
link string Where the page’s type is a link: this is the target link.
feed string Where the page’s type is an RSS feed: the feed to syndicate.
Manages
OAuth Scopes store_v2_content
store_v2_content_read_only

List Pages

Gets the collection of pages. (Default sorting is by auto-generated ID. This usually generates an order of oldest-to-newest)

Pagination

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

Parameter Type Example
Page int /stores/{store_hash}/v2/pages?page={number}
Limit int /stores/{store_hash}/v2/pages?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "name": "RSS Syndication",
    "meta_title": "",
    "body": "%%Syndicate%%",
    "is_visible": true,
    "parent_id": 0,
    "sort_order": 3,
    "meta_keywords": "",
    "type": "page",
    "meta_description": "",
    "is_homepage": false,
    "layout_file": "",
    "is_customers_only": false,
    "search_keywords": "",
    "has_mobile_version": false,
    "mobile_body": "",
    "url": "/mens/"
  },
  {
    "id": 2,
    "name": "Shipping & Returns",
    "meta_title": "",
    "body": "To edit this page, simply log in to the control panel, click the <strong style=\"font-weight: 400\">Website Content</strong> tab, and choose the <strong style=\"font-weight: 400\"> View Web Pages</strong> option. Click <strong style=\"font-weight: 400\">Edit</strong> next to the <strong style=\"font-weight: 400\">Shipping & Returns</strong> page, and you can change this text. A sample returns policy is shown below, which you can edit as needed. <br/><br/> <em style=\"font-style: normal\"><strong>Returns Policy</strong></em><strong style=\"font-weight: 400\"></em></em><em style=\"font-style: normal\"><br/><br/></em>You may return most new, unopened items within 30 days of delivery for a full refund. We'll also pay the return shipping costs if the return is a result of our error (you received an incorrect or defective item, etc.).<br/><br/>You should expect to receive your refund within four weeks of giving your package to the return shipper, however, in many cases you will receive a refund more quickly. This time period includes the transit time for us to receive your return from the shipper (5 to 10 business days), the time it takes us to process your return once we receive it (3 to 5 business days), and the time it takes your bank to process our refund request (5 to 10 business days).<br/><br/>If you need to return an item, please <a href=\"/contact-us/\">Contact Us</a> with your order number and details about the product you would like to return. We will respond quickly with instructions for how to return items from your order.<br/><br/></strong><strong>Shipping</em></em></em></strong><strong style=\"font-weight: 400\"><em style=\"font-style: normal\"><br/><br/></em>We can ship to virtually any address in the world. Note that there are restrictions on some products, and some products cannot be shipped to international destinations.<br/><br/>When you place an order, we will estimate shipping and delivery dates for you based on the availability of your items and the shipping options you choose. Depending on the shipping provider you choose, shipping date estimates may appear on the shipping quotes page.<br/><br/>Please also note that the shipping rates for many items we sell are weight-based. The weight of any such item can be found on its detail page. To reflect the policies of the shipping companies we use, all weights will be rounded up to the next full pound.</strong><br/>",
    "is_visible": true,
    "parent_id": 0,
    "sort_order": 2,
    "meta_keywords": "",
    "type": "page",
    "meta_description": "",
    "is_homepage": false,
    "layout_file": "page.html",
    "is_customers_only": false,
    "search_keywords": "",
    "has_mobile_version": false,
    "mobile_body": "",
    "url": "/shoes/"
  },
  {
    "id": 3,
    "name": "Blog",
    "is_visible": true,
    "parent_id": 0,
    "sort_order": 2,
    "type": "blog_index",
    "is_homepage": false,
    "is_customers_only": false
  },
  {
    "id": 4,
    "name": "Contact Us",
    "meta_title": "",
    "email": "",
    "body": "We're happy to answer questions or help you with returns.<br/>Please fill out the form below if you need assistance.",
    "is_visible": true,
    "parent_id": 0,
    "sort_order": 1,
    "meta_keywords": "",
    "type": "contact_form",
    "contact_fields": "fullname,phone,orderno",
    "meta_description": "",
    "is_homepage": false,
    "layout_file": "page.html",
    "is_customers_only": false,
    "search_keywords": "",
    "has_mobile_version": false,
    "mobile_body": "",
    "url": "/contact-us/"
  },
  {
  "id": 5,
  "name": "Raw Test Page",
  "body": "<html><head><title>Raw Page</title></head><body>This page type can store raw HTML</body></html>",
  "is_visible": true,
  "parent_id": 0,
  "sort_order": 3,
  "type": "raw",
  "is_homepage": false,
  "is_customers_only": false,
  "search_keywords": "",
  "has_mobile_version": true,
  "mobile_body": "<html><head><title>Page</title></head><body>Mobile Content can be raw as well</body></html>",
  "url": "/Raw-Body-Test-Page/"
  }
]

Get a Page

Gets a page.

Response

Example JSON returned in the response:

{
  "id": 3,
  "name": "Blog",
  "is_visible": true,
  "parent_id": 0,
  "sort_order": 2,
  "type": "blog_index",
  "is_homepage": false,
  "is_customers_only": false
}

Create a Page

Creates a new page.

Read-only Properties

The following property of the page is read-only. If it is included in the request, the request will be rejected:

Requirements

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

Request

Example request object:

{
   "type": "raw",
   "name": "404 Page for Cats",
   "url": "/404-meow/",
   "body": "<html><head><title>Hairball! Not Found</title></head><body>Sorry! You can not haz cheeseburger.</body></html>",
   "mobile_body": "",
   "has_mobile_version": false,
   "is_visible": true,
   "is_homepage": false,
   "is_customers_only": false,
   "sort_order": 12,
   "search_keywords": "dead, missing, broken"
}

Response

Example JSON returned in the response:

{
 "id": 12,
 "name": "404 Page for Cats",
 "body": "<html><head><title>Hairball! Not Found</title></head><body>Sorry! You can not haz cheeseburger.</body></html>",
 "is_visible": true,
 "parent_id": 0,
 "sort_order": 12,
 "type": "raw",
 "is_homepage": false,
 "is_customers_only": false,
 "search_keywords": "dead, missing, broken",
 "has_mobile_version": false,
 "mobile_body": "",
 "url": "/404-meow/"
}

Delete a Page

Deletes a page.

Redirects

A 301 redirect, mapping from a given URL path to another URL. Redirects are used to create custom URL paths that map to resources on the storefront (such as products, categories, brands, etc.), or to manually defined static URLs.

Redirect Object – Properties

Name Type Description
id int
path string The path that will be redirected from
forward forward The destination of the redirect
url string
Manages
OAuth Scopes store_v2_content
store_v2_content_read_only

List Redirects

Gets the collection of URL redirects.

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 redirects are returned by default.

Parameter Type Example
page int /api/v2/redirects?page={number}
limit int /api/v2/redirects?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "path": "/redirect_path1",
    "forward": {
      "type": "manual",
      "ref": "http://www.bigcommerce.com"
    },
    "url": "http://www.bigcommerce.com"
  },
  {
    "id": 2,
    "path": "/redirect_path2",
    "forward": {
      "type": "product",
      "ref": 35
    },
    "url": "http://store.example.com/product-no-35"
  }
]

Get a Redirect

Gets a single URL redirect.

Response

Example JSON returned in the response:

{
  "id": 1,
  "path": "/redirect_path1",
  "forward": {
    "type": "manual",
    "ref": "http://www.bigcommerce.com"
  },
  "url": "http://www.bigcommerce.com"
}

Get a Count of Redirects

Gets a count of redirects.

Response

Example JSON returned in the response:

{
  "count": 0
}

Create a Redirect

Creates a new URL redirect.

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "path": "/mens_clothing",
  "forward": {
    "type": "category",
    "ref": 3
  }
}

Response

Example JSON returned in the response:

{
  "id": 3,
  "path": "/mens_clothing",
  "forward": {
    "type": "category",
    "ref": 3
  },
  "url": "http://store.example.com/mens"
}

Update a Redirect

Updates an existing URL redirect.

Read-only Properties

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

Requirements

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

Delete a Redirect

Deletes a URL redirect.

Delete Multiple Redirects

Deletes multiple URL redirects.

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 redirects are returned by default.

Parameter Type Example
page int /api/v2/redirects?page={number}
limit int /api/v2/redirects?limit={count}

Currency Reference

The Currency object and endpoints manage alternate currency display options on the storefront.

Currency Object – Properties

Name Type Description
id int The ID of the currency. Read-only.
is_default boolean Specifies whether this is the store’s default currency display format. Read-only. (To change the store’s default currency via the BigCommerce control panel, please see this support article.)
date_created date Date on which this currency was created on the store.
date_modified date Date on which this currency was last modified on the store.
country_iso2 string 2-letter ISO Alpha-2 code for this currency’s country.
currency_code string 3-letter ISO 4217 code for this currency.
currency_exchange_rate float Amount of this currency that is equivalent to one U.S. dollar.
auto_update boolean Specifies whether to use the XE Currency Converter service to update the currency conversion. A value of false specifies a static conversion value.
location string Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
token string Symbol for this currency.
decimal_token string Symbol used as the decimal separator in this currency.
thousands_token string Symbol used as the thousands separator in this currency.
decimal_places int Number of decimal places to show for this currency.

List Currencies

Retrieves currency display options.

Response

Example JSON returned in the response:

    {
      "currencies": {
        "currency": [
          {
            "id": 3,
            "is_default": "false",
            "date_created": "Thu, 11 Sep 2014 17:10:12 +0000",
            "date_modified": "Thu, 08 Jan 2015 15:12:48 +0000",
            "country_iso2": "AU",
            "currency_code": "AUD",
            "currency_exchange_rate": "1.3885600000",
            "auto_update": "false",
            "location": "left",
            "token": "$",
            "decimal_token": ".",
            "thousands_token": ",",
            "decimal_places": 2
          },
          {
            "id": 4,
            "is_default": "false",
            "date_created": "Thu, 11 Sep 2014 17:10:12 +0000",
            "date_modified": "Thu, 08 Jan 2015 15:12:48 +0000",
            "country_iso2": "US",
            "currency_code": "USD",
            "currency_exchange_rate": "1.0000000000",
            "auto_update": "false",
            "location": "left",
            "token": "$",
            "decimal_token": ".",
            "thousands_token": ",",
            "decimal_places": 2
          },
          {
            "id": 5,
            "is_default": "false",
            "date_created": "Thu, 11 Sep 2014 17:10:12 +0000",
            "date_modified": "Thu, 08 Jan 2015 15:12:48 +0000",
            "country_iso2": "CA",
            "currency_code": "CAD",
            "currency_exchange_rate": "0.7500000000",
            "auto_update": "false",
            "location": "left",
            "token": "$",
            "decimal_token": ".",
            "thousands_token": ",",
            "decimal_places": 2
          }
        ]
      }
    }

Get a Currency

Retrieves a specified currency.

Response

Example JSON returned in the response:

{
    "id": 3,
    "is_default": "false",
    "date_created": "Thu, 11 Sep 2014 17:10:12 +0000",
    "date_modified": "Thu, 08 Jan 2015 15:12:48 +0000",
    "country_iso2": "AU",
    "currency_code": "AUD",
    "currency_exchange_rate": "1.3885600000",
    "auto_update": "false",
    "location": "left",
    "token": "$",
    "decimal_token": ".",
    "thousands_token": ",",
    "decimal_places": 2
}

Create a Currency

Creates a new currency.

Read-only Properties

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

Notes

The is_default property cannot be set programmatically. To change the store’s default currency via the BigCommerce control panel, please see this support article.

Requirements

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

Request

Example request object:

{
    "country_iso2": "AU",
    "currency_code": "AUD",
    "currency_exchange_rate": "1.3885600000",
    "auto_update": "false",
    "location": "left",
    "token": "$",
    "decimal_token": ".",
    "thousands_token": ",",
    "decimal_places": 2
}

Update a Currency

Updates an existing currency.

Read-only Properties

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

Request

Example request object:

{
    "country_iso2": "AU",
    "currency_code": "AUD",
    "currency_exchange_rate": "1.3885600000",
    "auto_update": "false",
    "location": "left",
    "token": "$",
    "decimal_token": ".",
    "thousands_token": ",",
    "decimal_places": 2
}

Delete a Currency

Deletes a specified currency. (If successful, this will typically return a “204 No Content”.)

Delete All Currencies

Deletes all currencies associated with the store. (If successful, this will typically return a “204 No Content”.)

Customers Reference

Customers APIs manage identity and account details for customers shopping on BigCommerce stores. They include Customers, Customer Addresses, Customer Groups, and Customer Login.

Customers

Identity and account details for customers shopping on Bigcommerce stores.

Customer Object – Properties

Name Type Description
id int
_authentication object Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If not supplied, a password is generated automatically. See the customers resource documentation for more information about the use of this object.
company string The name of the company that the customer works for.
first_name string First name of the customer
last_name string Last name of the customer
email string Email address of the customer
phone string Phone number of the customer
date_created date
date_modified date
store_credit decimal The amount of credit the customer has
registration_ip_address string The IP address of the customer when they signed up
customer_group_id int The group the customer belongs to
notes text Store owner notes on the customer
tax_exempt_category string Used to identify customers that fall into special sales tax categories, in particular, those who are fully or partially exempt from paying sales tax. Stores that subscribe to Avalara Premium will use this code to determine how/whether to apply sales tax. Doesn’t affect the sales tax calculations of stores that don’t subscribe to Avalara Premium. Either blank or contains/accepts a single AvaTax code. Should not contain more than one code. The codes are case-sensitive. Refer to the following page for further information and the full list of codes: http://developer.avalara.com/api-docs/designing-your-integration/handling-tax-exempt-customers
accepts_marketing boolean Records whether the customer would like to receive marketing content from this store. Read‑only.
addresses resource
form_fields object Array of custom fields.

Customer Events

The following customer events are available:

Customer Created

store/customer/created

Occurs when a customer registers from the storefront or is created in the control panel.

Customer Updated

store/customer/updated

Occurs when a customer updates their details in the storefront or is updated in the control panel.

Customer Deleted

store/customer/deleted

Occurs when a customer is deleted in the control panel.

Manages
OAuth Scopes store_v2_customers
store_v2_customers_read_only

List Customers

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

Filters

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

Parameter Type Example
first_name string /api/v2/customers?first_name={value}
last_name string /api/v2/customers?last_name={value}
company string /api/v2/customers?company={value}
email string /api/v2/customers?email={value}
phone string /api/v2/customers?phone={value}
store_credit string /api/v2/customers?store_credit={value}
customer_group_id string /api/v2/customers?customer_group_id={value}
min_id int /api/v2/customers?min_id={value}
max_id int /api/v2/customers?max_id={value}
min_date_created dateTime or date /api/v2/customers?min_date_created={value}
max_date_created dateTime or date /api/v2/customers?max_date_created={value}
min_date_modified dateTime or date /api/v2/customers?min_date_modified={value}
max_date_modified dateTime or date /api/v2/customers?max_date_modified={value}
tax_exempt_category date /api/v2/customers?tax_exempt_category={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 customers are returned by default.

Parameter Type Example
Page int /api/v2/customers?page={number}
Limit int /api/v2/customers?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "company": "",
    "first_name": "Random ",
    "last_name": "Joe Bob",
    "email": "random.joebob@example.com",
    "phone": "252-101-2010",
    "date_created": "Tue, 13 Nov 2012 21:16:41 +0000",
    "date_modified": "Tue, 13 Nov 2012 21:16:41 +0000",
    "store_credit": "0.0000",
    "registration_ip_address": "50.58.18.2",
    "customer_group_id": 0,
    "notes": "",
    "tax_exempt_category": "",
    "accepts_marketing": false,
    "addresses": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/customers/1/addresses.json",
      "resource": "/customers/1/addresses"
    }
  },
  {
    "id": 2,
    "company": "",
    "first_name": "Test",
    "last_name": "Customer",
    "email": "foo@randomcustomer.com",
    "phone": "",
    "date_created": "Wed, 14 Nov 2012 04:47:28 +0000",
    "date_modified": "Wed, 14 Nov 2012 04:47:28 +0000",
    "store_credit": "0.0000",
    "registration_ip_address": "99.191.105.74",
    "customer_group_id": 0,
    "notes": "",
    "tax_exempt_category": "",
    "accepts_marketing": false,
    "addresses": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/customers/2/addresses.json",
      "resource": "/customers/2/addresses"
    }
  }
]

Get a Customer

Gets a customer.

Response

Example JSON returned in the response:

{
  "id": 1,
  "company": "",
  "first_name": "Random ",
  "last_name": "Joe Bob",
  "email": "random.joebob@example.com",
  "phone": "252-101-2010",
  "date_created": "Tue, 13 Nov 2012 21:16:41 +0000",
  "date_modified": "Tue, 13 Nov 2012 21:16:41 +0000",
  "store_credit": "0.0000",
  "registration_ip_address": "50.58.18.2",
  "customer_group_id": 0,
  "notes": "",
  "tax_exempt_category": "",
  "accepts_marketing": false,
  "addresses": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/customers/1/addresses.json",
    "resource": "/customers/1/addresses"
  }
}

Get a Count of Customers

Gets a count of customers.

Response

Example JSON returned in the response:

{
  "count": 3
}

Create a Customer

Creates a new customer.

Read-only Properties

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

Requirements

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

Notes

The _authentication object exposes functionality associated with the customer’s ability to log in to the store. All properties of the _authentication object are optional.

When the _authentication object is not supplied with an update request, then the existing customer password remains the same.

Updating Passwords

To manually update a customer password in the same way as the control panel, supply a value for the password field:

{
    "_authentication": {
        "password": "12w69Y217PYR96J"
    }
}

Confirming Passwords

An additional optional password_confirmation field can also be sent, providing password confirmation as a service:

{
    "_authentication": {
       "password": "12w69Y217PYR96J",
       "password_confirmation": "12w69Y217PYR96J"
    }
}

Forcing Password Resets

To force a customer to reset their password upon their next login attempt, give the force_reset field a value of true, as shown here:

{
    "_authentication": {
        "force_reset": true
    }
}

Update a Customer

Updates an existing customer.

Read-only Properties

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

Requirements

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

Notes

The _authentication object exposes functionality associated with the customer’s ability to log in to the store. All properties of the _authentication object are optional.

When the _authentication object is not supplied with an update request, then the existing customer password remains the same.

Updating Passwords

To manually update a customer password in the same way as the control panel, supply a value for the password field:

{
    "_authentication": {
        "password": "12w69Y217PYR96J"
    }
}

Confirming Passwords

An additional optional password_confirmation field can also be sent, providing password confirmation as a service:

{
    "_authentication": {
       "password": "12w69Y217PYR96J"
       "password_confirmation": "12w69Y217PYR96J"
    }
}

Forcing Password Resets

To force a customer to reset their password upon their next login attempt, give the force_reset field a value of true, as shown here:

{
    "_authentication": {
        "force_reset": true
    }
}

Delete a Customer

Deletes a customer.

Delete All Customers

Deletes all customer objects from the store.

Customer Addresses

Postal address belonging to a customer.

Customer Address Object – Properties

Name Type Description
id int
customer_id int
first_name string The customer address first name.
last_name string The customer address last name.
company string The customer address company name.
street_1 string The customer street address line 1.
street_2 string The customer street address line 2.
city string The customer address city/suburb.
state string The customer address state/province. Do not abbreviate the state; spell out the entire word, e.g.: California. (Cannot be null. As a workaround for addresses that include no state/province string, pass a space as the “state” value.)
zip string The customer address zip/postcode.
country string The customer address country. Must be the full country name.
country_iso2 string
phone string The customer address phone number.
address_type enum
Manages
OAuth Scopes store_v2_customers
store_v2_customers_read_only

List Customer Addresses

Gets the addresses belonging to a customer. (Default sorting is by address id, from lowest to highest.)

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 customer_addresses are returned by default.

Parameter Type Example
Page int /api/v2/customers/{customer_id}/addresses?page={number}
Limit int /api/v2/customers/{customer_id}/addresses?limit={count}

Read-only Properties

The following property is read-only. If included in the request, it will be rejected.

Notes

Allowable values for the address_type property are residential or commercial.

In the example Response below, within the form_fields array, the first custom field is a checkbox field that could return any number of answers. The second custom field is a date field.

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "customer_id": 10,
    "first_name": "Trisha",
    "last_name": "McLaughlin",
    "company": "",
    "street_1": "12345 W Anderson Ln",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78757",
    "country": "United States",
    "country_iso2": "US",
    "phone": ""
  }
]

Get a Customer Address

Gets a customer address.

Read-only Properties

The following property is read-only. If included in the request, it will be rejected.

Notes

Allowable values for the address_type property are residential or commercial.

In the example Response below, within the form_fields array, the first custom field is a checkbox field that could return any number of answers. The second custom field is a date field.

Response

Example JSON returned in the response:

{
  "id": 1,
  "customer_id": 10,
  "first_name": "Trisha",
  "last_name": "McLaughlin",
  "company": "",
  "street_1": "12345 W Anderson Ln",
  "street_2": "",
  "city": "Austin",
  "state": "Texas",
  "zip": "78757",
  "country": "United States",
  "country_iso2": "US",
  "phone": ""
}

Get a Count of Customer Addresses

Gets a count of customer addresses.

Response

Example JSON returned in the response:

{
  "count": 4
}

Create a Customer Address

Creates a new customer address. (Note: The “state” property cannot be null. As a workaround for addresses that include no state/province string, pass a space as the “state” value.)

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "first_name": "Trisha",
  "last_name": "McLaughlin",
  "company": "",
  "street_1": "12345 W Anderson Ln",
  "street_2": "",
  "city": "Austin",
  "state": "Texas",
  "zip": "78757",
  "country": "United States",
  "phone": "512-123-4567"
}

Response

Example JSON returned in the response:

{
  "id": 1,
  "customer_id": 1,
  "first_name": "Trisha",
  "last_name": "McLaughlin",
  "company": "",
  "street_1": "12345 W Anderson Ln",
  "street_2": "",
  "city": "Austin",
  "state": "Texas",
  "zip": "78757",
  "country": "United States",
  "country_iso2": "US",
  "phone": ""
}

Update a Customer Address

Updates an existing customer address.

Read-only Properties

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

Requirements

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

Request

Example request object:

{
  "first_name": "Trisha",
  "last_name": "McLaughlin",
  "company": "",
  "street_1": "12345 W Anderson Ln",
  "street_2": "",
  "city": "Austin",
  "state": "Texas",
  "zip": "78757",
  "country": "United States",
  "phone": ""
}

Response

Example JSON returned in the response:

{
  "id": 1,
  "customer_id": 1,
  "first_name": "Trisha",
  "last_name": "McLaughlin",
  "company": "",
  "street_1": "12345 W Anderson Ln",
  "street_2": "",
  "city": "Austin",
  "state": "Texas",
  "zip": "78757",
  "country": "United States",
  "country_iso2": "US",
  "phone": ""
}

Delete a Customer Address

Deletes a customer address.

Delete Multiple Customer Addresses

Deletes multiple customer addresses.

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 customer_addresses are returned by default.

Parameter Type Example
Page int /api/v2/customers/{customer_id}/addresses?page={number}
Limit int /api/v2/customers/{customer_id}/addresses?limit={count}

Customer Groups

Groupings of customers who share the same level of access and discounts at a store.

Customer Group – Properties

Name Type Description
id int
name string Name of the group
is_default boolean Determines whether new customers are assigned to this group by default.
category_access object Determines the categories to which customers in this group have access to view and order products.

type is an enum specifying the method of category access applied to customers in this group, with the following possible values:
all: customers can access all categories;
specific: customers can access a specific list of categories;
none: customers are prevented from viewing any of the categories in this group.

categories is an array of category IDs and should be supplied only if type is specific.
discount_rules object_array A collection of discount rules that are automatically applied to customers who are members of the group. All discount rules have the following properties:

type is an enum specifying the type of discount rule, with the following possible values:
all: a store-wide rule (applies to everything);
product: a rule applying to a specific product;
category: a rule applying to a specific category.

method is an enum that specifies a price-modifying strategy, with the following possible values:
price: modify the price by the given amount;
percent: modify the price by the given percentage;
fixed: modify the price by a fixed discount.

amount is a decimal number that specifies the value applied to the price modifier.

Product and category rules also require a product_id or category_id field, respectively.
Manages
OAuth Scopes store_v2_customers
store_v2_customers_read_only

List Customer Groups

Gets the collection of customer groups. (Default sorting is by customer-group id, from lowest to highest.)

Filters

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

Parameter Type Example
name string /api/v2/customer_groups?name={value}
is_default boolean /api/v2/customer_groups?is_default={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 customer_groups are returned by default.

Parameter Type Example
Page int /api/v2/customer_groups?page={number}
Limit int /api/v2/customer_groups?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "name": "Retail Customers",
    "is_default": true,
    "category_access": {
      "type": "all"
    },
    "discount_rules": [

    ]
  },
  {
    "id": 2,
    "name": "Wholesale Customers",
    "is_default": false,
    "category_access": {
      "type": "all"
    },
    "discount_rules": [

    ]
  }
]

Get a Customer Group

Gets a customer group.

Response

Example JSON returned in the response:

{
  "id": 3,
  "name": "Student Discounts",
  "is_default": true,
  "category_access": {
    "type": "all"
  },
  "discount_rules": [
    {
      "type": "percent",
      "method": true,
      "amount": "5.0000"
    }
  ]
}

Get a Count of Customer Groups

Gets a count of customer groups.

Response

Example JSON returned in the response:

{
  "count": 3
}

Create a Customer Group

Creates a new customer group.

Requirements

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

Notes

A minimal request requires only the customer group name:

{
    "name": "Wholesale Customers"
}

To assign all new customers to the group by default, set is default to true:

{
    "name": "Retail Customers",
    "is_default": true
}

To restrict customers in the group to only view and order products from a specific set of categories, provide a category access type:

{
    "name": "Bulk Purchasers",
    "category_access": {
        "type": "specific",
        "categories": [7, 12, 20]
    }
}

To provide a 5% store-wide discount for customers in the group, use a discount rule of type all:

{
    "name": "Student Discounts",
    "discount_rules": 
    [{
        "type": "all",
        "method": "percent",
        "amount": 5.00
    }]
}

Update a Customer Group

Updates an existing customer group.

Notes

Any combination of fields can be updated at once. Discount rules are treated in bulk. The entire set of rules is overwritten when a request is sent.

The following request will remove any existing rules, and apply the new ones:

{
        "discount_rules": [
            {
                "type": "all",
                "method": "percent",
                "amount": 2.50
            },
            {
                "type": "product",
                "product_id": 33,
                "method": "percent",
                "amount": 5.00
            },
            {
                "type": "category",
                "category_id": 7,
                "method": "price",
                "amount": 12.00
            }
        ]
}

Delete a Customer Group

Deletes a customer group.

Notes

All existing customers are unassigned from the group when it is deleted.

Delete All Customer Groups

Deletes all customer groups in the store.

Customer Login API

The Customer Login API enables single sign-on (SSO). It allows your apps to generate a token to programmatically log in a storefront customer, by using the login entry point at /login/token/{token}. Here, {token} must be a JSON Web Token (JWT) containing the parameters for the customer login request in its payload, and must be signed by your OAuth application’s client secret.

For a full overview of the JWT standard, please see JWT.IO, where you will find links to client libraries (in many languages) that facilitate the generation and verification of JWT tokens. BigCommerce also supplies helper methods for generating login tokens in our API Client Libraries.

Customer Login Token

A valid JWT token is a string composed of three parts, separated by periods (“.”). Please refer to JWT.IO and RFC 7519 for more details on the format.

Example URL

https://storedomain.com/login/token/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9
.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
{
"typ": "JWT",
"alg": "HS256"
}

Payload

{
"iss": "<application_client_id>",
"iat": "<issued_at>",
"jti": "<unique_string>",
"operation": "customer_login",
"store_hash": "<store_hash>",
"customer_id": "<customer_id>",
"redirect_to": "<relative_path (optional)>",
"request_ip": "<ipv4_address (optional)>"
}

Fields

Field Name Type Description
iss string Indicates the token’s issuer. This is your application’s client ID, which is obtained during application registration in Developer Portal.
iat integer Time when the token was generated. This is a numeric value indicating the number of seconds since the Unix epoch.
jti string Request ID string that must be unique across all requests made by your app. A UUID or other random string would be an appropriate value.
operation enum Must contain the string “customer_login”.
store_hash string Store hash identifying the store you are logging into.
customer_id integer ID of the customer you are logging in, as obtained through the Customer API.
redirect_to string Optional field containing a relative path for the shopper’s destination after login. Will default to /account.php.
request_ip string Optional field containing the expected IP address for the request.

Signature

The headers and payload must be signed using HS256 (HMAC-SHA256) and the application’s client secret.

Sample Code

Code to generate a valid JWT token for a storefront login request is provided in our API Client Libraries. (The headings below are linked to the live code, which might have been updated since publication:)

PHP Sample

    public static function getCustomerLoginToken($id, $redirectUrl = '', $requestIp = '')
    {
        if (empty(self::$client_secret)) {
            throw new Exception('Cannot sign customer login tokens without a client secret');
        }

        $payload = array(
            'iss' => self::$client_id,
            'iat' => time(),
            'jti' => bin2hex(random_bytes(32)),
            'operation' => 'customer_login',
            'store_hash' => self::$store_hash,
            'customer_id' => $id
        );

        if (!empty($redirectUrl)) {
            $payload['redirect_to'] = $redirectUrl;
        }

        if (!empty($requestIp)) {
            $payload['request_ip'] = $requestIp;
        }

        return JWT::encode($payload, self::$client_secret, 'HS256');
    }

Python Sample

import os
import time
import uuid
import jwt


class CustomerLoginTokens(object):
    @classmethod
    def create(cls, client, id, redirect_url=None, request_ip=None):

        # Get the client_secret needed to sign tokens from the environment
        # Intended to play nice with the Python Hello World sample app
        # https://github.com/bigcommerce/hello-world-app-python-flask
        client_secret = os.getenv('APP_CLIENT_SECRET')

        if not client_secret:
            raise AttributeError('No OAuth client secret specified in the environment, '
                                 'please specify an APP_CLIENT_SECRET')

        try:
            client_id = client.connection.client_id
            store_hash = client.connection.store_hash
        except AttributeError:
            raise AttributeError('Store hash or client ID not found in the connection - '
                                 'make sure an OAuth API connection is configured. Basic auth is not supported.')

        payload = dict(iss=client_id,
                       iat=int(time.time()),
                       jti=uuid.uuid4().hex,
                       operation='customer_login',
                       store_hash=store_hash,
                       customer_id=id
                       )

        if redirect_url:
            payload['redirect_url'] = redirect_url

        if request_ip:
            payload['request_ip'] = request_ip

        token = jwt.encode(payload, client_secret, algorithm='HS256')

        return token.decode('utf-8')

    @classmethod
    def create_url(cls, client, id, redirect_url=None, request_ip=None):
        secure_url = client.Store.all()['secure_url']
        login_token = cls.create(client, id, redirect_url, request_ip)
        return '%s/login/token/%s' % (secure_url, login_token)

Ruby Sample

require 'bigcommerce'

Bigcommerce.configure do |config|
  config.store_hash = ENV['BC_STORE_HASH']
  config.client_id = ENV['BC_CLIENT_ID']
  config.client_secret = ENV['BC_CLIENT_SECRET']
  config.access_token = ENV['BC_ACCESS_TOKEN']
end

# Get a customer
customer = Bigcommerce::Customer.all(page: 1).first

# Generate token login url
puts customer.login_token

OAuth Scope

In order to use this feature, your app must be installed in the store, and must have the store_v2_customers_login scope.

Redirection

For flexibility in navigation after login, we support an optional redirect parameter (redirect_to), which in turn supports relative URLs. If the parameter is not specified, the storefront customer will land on their My Account page at /account.php.

Notes

Tokens will be valid for a very short timeframe after they are first generated, so tokens should not be generated in advance. Instead, the application should generate the token and then immediately redirect the user’s browser to /login/token/{token}.

Once a request has been made with a given jti, it cannot be made again. This parameter is used to prevent replay attacks by malicious actors intercepting the request or obtaining it after the fact.

The request_ip field can be used as an additional security precaution, to prevent a malicious actor from intercepting the request and making it from another browser or system before you do. If you supply this value, BigCommerce will check the incoming request to ensure that it is being made from the stated IP address – and will otherwise fail the request. We strongly encourage setting this IP address value; but doing so is optional, to support those cases where this information is not available.

Identifying Logged-In Customers Securely

If your application interacts dynamically with the BigCommerce storefront, and conveys information that is specific to a particular logged-in customer, you must confirm that customer’s identity within the insecure environment of the user’s browser.

Current Customer API

To address this need, BigCommerce provides a Current Customer endpoint, which your app can access via JavaScript on the storefront. This endpoint returns a JWT (JSON Web Token) with identifying details about the customer. The information is signed with your client secret.

Example JavaScript

Below is example JavaScript that will access this JWT. To test the JWT functionality, you can install this JavaScript on your sandbox BigCommerce store. Your application’s Client ID must be included in the request (to identify the requesting application):

<script type="text/javascript">
function customerJWT() {  
    var appClientId = "**BC_CLIENT_ID**"; // TODO: Fill this in with your app's client ID
    var xmlhttp = new XMLHttpRequest();
    xmlhttp.onreadystatechange = function() {
        if (xmlhttp.readyState == XMLHttpRequest.DONE ) {
           if (xmlhttp.status == 200) {
               alert('Customer JWT:\n' + xmlhttp.responseText);
           }
           else if (xmlhttp.status == 404) {
              alert('Not logged in!');
           }
           else {
               alert('Something went wrong');
           }
        }
    };
    xmlhttp.open("GET", "/customer/current.jwt?app_client_id="+appClientId, true);
    xmlhttp.send();
}
customerJWT();
</script>

If you are logged into the storefront with a customer account, the above JavaScript should alert to the browser with a JWT token. If no customer is logged in, BigCommerce will return a 404 response, and you will see an error message.

The JWT returned from this endpoint (example below) can be decoded on JWT.IO, or via any of these libraries.

Example Output

{
  "customer": {
    "id": 4927,
    "email": "john.doe@gmail.com",
    "group_id": "6"
  },
  "iss": "bc/apps",
  "sub": "abc123",
  "iat": 1480831863,
  "exp": 1480832763,
  "version": 1,
  "aud": "6sv16tfx3j5gsopm42ss5dd67g2srvq",
  "application_id": "6sv16tasdgr2b5hs5dd67g2srvq",
  "store_hash": "abc123",
  "operation": "current_customer"
}

By design, your application should send this token to the application’s server, validate it against your client secret, and then use it as a trusted indication of the logged-in customer’s identity, before displaying confidential information to them.

An end-to-end example, which displays a customer’s recently purchased products, is available in our Ruby and PHP sample apps. .

Geography Reference

Geography APIs handle geographic information resources. They include Countries and States.

Countries

A country or territory, identifiable by an ISO 3166 country code.

Country Object – Properties

Name Type Description
id int
country string Country name
country_iso2 string 2 letter countryt code
country_iso3 string 3 letter country code
states resource
Manages
OAuth Scopes default

List Countries

Gets the list of countries.

Filters

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

Parameter Type Example
country string /api/v2/countries?country={value}
country_iso2 string /api/v2/countries?country_iso2={value}
country_iso3 string /api/v2/countries?country_iso3={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 countries are returned by default.

Parameter Type Example
Page int /api/v2/countries?page={number}
Limit int /api/v2/countries?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "country": "Afghanistan",
    "country_iso2": "AF",
    "country_iso3": "AFG",
    "states": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/countries/1/states.json",
      "resource": "/countries/1/states"
    }
  },
  {
    "id": 2,
    "country": "Albania",
    "country_iso2": "AL",
    "country_iso3": "ALB",
    "states": {
      "url": "https://store-bwvr466.mybigcommerce.com/api/v2/countries/2/states.json",
      "resource": "/countries/2/states"
    }
  }
]

Get a Country

Gets a country.

Response

Example JSON returned in the response:

{
  "id": 226,
  "country": "United States",
  "country_iso2": "US",
  "country_iso3": "USA",
  "states": {
    "url": "https://store-bwvr466.mybigcommerce.com/api/v2/countries/226/states.json",
    "resource": "/countries/226/states"
  }
}

Get a Count of Countries

Gets a count of countries.

Response

Example JSON returned in the response:

{
  "count": 243
}

States

A state or province, identifiable by an ISO 3166 subdivision code

State Object – Properties

Name Type Description
id int
state string state name
state_abbreviation string state abbreviation
country_id int
Manages
OAuth Scopes default

List States

Gets the list of states belonging to a country.

Filters

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

Parameter Type Example
state string /api/v2/countries/{country_id}/states?state={value}
state_abbreviation string /api/v2/countries/{country_id}/states?state_abbreviation={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 states are returned by default.

Parameter Type Example
Page int /api/v2/countries/{country_id}/states?page={number}
Limit int /api/v2/countries/{country_id}/states?limit={count}
[
  {
    "id": 1,
    "state": "Alabama",
    "state_abbreviation": "AL",
    "country_id": 226
  },
  {
    "id": 2,
    "state": "Alaska",
    "state_abbreviation": "AK",
    "country_id": 226
  }
]

Get a State

Gets a state belonging to a country.

{
  "id": 1,
  "state": "Alabama",
  "state_abbreviation": "AL",
  "country_id": 226
}

Get a Count of States

Gets a count of the number of states within a specified country.

{
  "count": 65
}

Marketing Reference

Marketing APIs support demand generation and loyalty programs. They include Coupons, Banners, and Gift Certificates.

Coupons

Category or product discounts that can be applied to orders for customers who enter a given code.

Coupon Object – Properties

Name Type Description
id int The coupon’s ID.
name string The name of the coupon.
type enum Acceptable values for this enumerated field are: per_item_discount, per_total_discount, shipping_discount, free_shipping, or percentage_discount.
amount decimal The discount to apply to an order, as either an amount or a percentage. This field’s usage is determined by the coupon type. For example, a type of percentage_discount would determine a percentage here.
min_purchase decimal Specifies a minimum value that an order must have before the coupon can be applied to it.
expires date Specifies when a coupon expires. Coupons need not have an expiry date – you can also control expiry via max_uses or max_uses_per_customer. If you do use this date field, the value must be in RFC 2822 format.
enabled boolean If the coupon is enabled, this field’s value is true; otherwise, false.
code string The coupon code that customers will use to receive their discounts. Value must be unique.
applies_to object Allows you to restrict a coupon to an entity type (category or product), and to specific categories/products. A value of 0 represents all categories/products.
num_uses int Number of times this coupon has been used. This is a read-only field; do not set or modify its value in a POST or PUT request.
max_uses int Maximum number of times this coupon can be used.
max_uses_per_customer int Maximum number of times each customer can use this coupon.
restricted_to object Allows you to restrict coupon usage based on locations, as follows:

To restrict a coupon by country, retrieve the list of ISO2 country codes supported by BigCommmerce as described below under Notes on Location Restrictions. Use the resulting ISO2 code as shown in this example:
"restricted_to": { "countries": ["AU"] }

To restrict a coupon by state/province, retrieve BigCommmerce’s list of supported state/province codes, indexed by ISO2 country codes, as described below under Notes on Location Restrictions. Use the resulting state/province code as shown in this example:
"restricted_to": { "states": { "AU": ["Australian Capital Territory"] } }

To restrict a coupon by ZIP/postal codes, use BigCommerce’s supported ZIP/postal-code patterns, which are indexed by ISO2 country codes. Please see this KB article for an overview, and this KB article for format details. Use the resulting code as shown in this example:
"restricted_to": { "zips": { "AU": ["2000", "20??"] } }
shipping_methods array This is a list of shipping-method names. A shipping method must be enabled on the store to use it with a coupon. To check which shipping methods are enabled, please use the List Shipping Methods endpoint.

Notes on Location Restrictions

For the locations property listed above, you can look up all country_iso2 codes supported by BigCommerce by using the List Countries endpoint, with a request of the following form:

https://{store_hash}/api/v2/countries?limit=250

To look up all state_iso2 codes supported by BigCommerce, you can use the List States endpoint, with a request of the following form. (To supply its {country_id} parameter, query the List Countries endpoint as described just above.)

https://{store_hash}/api/v2/countries/{country_id}/states

For example, to look up codes for all U.S. states and territories, you would use a request of the following form:

https://{store_hash}/api/v2/countries/226/states?limit=100
Manages
OAuth Scopes store_v2_marketing
store_v2_marketing_read_only

List Coupons

Gets the collection of coupons. (Default sorting is by coupon/discount id, from lowest to highest.)

Filters

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

Parameter Type Example
id string /api/v2/coupons?id={value}
code string /api/v2/coupons?code={value}
name string /api/v2/coupons?name={value}
type string /api/v2/coupons?type={value}
min_id int /api/v2/coupons?min_id={value}
max_id int /api/v2/coupons?max_id={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 coupons are returned by default.

Parameter Type Example
Page int /api/v2/coupons?page={number}
Limit int /api/v2/coupons?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "name": "5% off order total",
    "type": "per_item_discount",
    "amount": "5.0000",
    "min_purchase": "0.0000",
    "expires": "",
    "enabled": true,
    "code": "4F75AF0C3802D39",
    "applies_to": {
      "entity": "categories",
      "ids": [
        0
      ]
    },
    "num_uses": 0,
    "max_uses": 0,
    "max_uses_per_customer": 0,
    "restricted_to": {
      "countries": [
        "AU"
      ]
    },
    "shipping_methods": null
  },
  {
    "id": 2,
    "name": "10% off order total",
    "type": "per_item_discount",
    "amount": "10.0000",
    "min_purchase": "0.0000",
    "expires": "",
    "enabled": true,
    "code": "CBD1455FDA13815",
    "applies_to": {
      "entity": "categories",
      "ids": [
        0
      ]
    },
    "num_uses": 0,
    "max_uses": 0,
    "max_uses_per_customer": 0,
    "restricted_to": {
      "states": {
        "AU": [
          "Australian Capital Territory"
        ]
      }
    },
    "shipping_methods": null
  },
  {
    "id": 3,
    "name": "Free shipping",
    "type": "free_shipping",
    "amount": "0.0000",
    "min_purchase": "0.0000",
    "expires": "",
    "enabled": true,
    "code": "7E97D5F3F75FA2D",
    "applies_to": {
      "entity": "categories",
      "ids": [
        0
      ]
    },
    "num_uses": 0,
    "max_uses": 0,
    "max_uses_per_customer": 0,
    "restricted_to": {
      "zips": {
        "AU": [
          "2000",
          "20??"
        ]
      }
    },
    "shipping_methods": null
  },
  {
    "id": 4,
    "name": "$5 off shipping",
    "type": "shipping_discount",
    "amount": "5.0000",
    "min_purchase": "0.0000",
    "expires": "",
    "enabled": true,
    "code": "DC0C1CC8807DAC8",
    "applies_to": {
      "entity": "categories",
      "ids": [
        0
      ]
    },
    "num_uses": 0,
    "max_uses": 0,
    "max_uses_per_customer": 0,
    "restricted_to": null,
    "shipping_methods": null
  },
  {
    "id": 5,
    "name": "only for shipping_flatrate",
    "type": "0",
    "amount": "0.0000",
    "min_purchase": "100.0000",
    "expires": "Thu, 31 Jan 2013 00:00:00 +0000",
    "enabled": false,
    "code": "shippingFlatrate-2",
    "applies_to": {
      "entity": "products",
      "ids": [
        32
      ]
    },
    "num_uses": 0,
    "max_uses": 10,
    "max_uses_per_customer": 0,
    "restricted_to": null,
    "shipping_methods": [
      "shipping_flatrate"
    ]
  }
]

Get a Coupon

Gets a coupon.

Response

Example JSON returned in the response:

{
  "id": 1,
  "name": "5% off order total",
  "type": "per_item_discount",
  "amount": "5.0000",
  "min_purchase": "0.0000",
  "expires": "",
  "enabled": true,
  "code": "4F75AF0C3802D39",
  "applies_to": {
    "entity": "categories",
    "ids": [
      0
    ]
  },
  "num_uses": 0,
  "max_uses": 0,
  "max_uses_per_customer": 0,
  "restricted_to": null,
  "shipping_methods": null
}

Get a Count of Coupons

Gets a count of the number of coupons in the store.

Response

Example JSON returned in the response:

{
  "count": 65
}

Create a Coupon

Creates a new coupon.

Read-only Properties

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

Requirements

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

Notes

The coupon type can be one of the following:

{
  "name": "5% off order total",
  "type": "per_item_discount",
  "code": "4F75AF0C3802D39",
  "enabled": true,
  "amount": "5",
  "applies_to": {
    "entity": "categories",
    "ids": [
      0
    ]
  }
}
{
  "id": 1,
  "name": "5% off order total",
  "type": "per_item_discount",
  "amount": "5.0000",
  "min_purchase": "0.0000",
  "expires": "",
  "enabled": true,
  "code": "4F75AF0C3802D39",
  "applies_to": {
    "entity": "categories",
    "ids": [
      0
    ]
  },
  "num_uses": 0,
  "max_uses": 0,
  "max_uses_per_customer": 0,
  "restricted_to": null,
  "shipping_methods": null
}

Update a Coupon

Updates an existing coupon.

Read-only Properties

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

Requirements

The following property of the coupon is required. If it is not included in the PUT request, its existing value on the coupon will be cleared:

Note that if the applies_to value is cleared, you can restore it to the coupon by reapplying the applies_to value in a new PUT request.

Response

Example JSON returned in the response:

{
  "id": 1,
  "name": "5% off order total",
  "type": "per_item_discount",
  "amount": "5.0000",
  "min_purchase": "0.0000",
  "expires": "",
  "enabled": true,
  "code": "4F75AF0C3802D39",
  "applies_to": {
    "entity": "categories",
    "ids": [
      0
    ]
  },
  "num_uses": 0,
  "max_uses": 0,
  "max_uses_per_customer": 0,
  "restricted_to": null,
  "shipping_methods": null
}

Delete a Coupon

Deletes a coupon.

Delete All Coupons

Deletes all coupons in the store.

Banners

Banners available to display on a store.

Name Type Description
name string Required field.
page enum ‘home_page’, 'category_page’, 'brand_page’, 'search_page’. Required field.
dateto date If the datetype is set as 'custom’, this field specifies the date when the banner should stop being visible on the storefront.
content text Required field.
bannerid int Read-only.
datefrom date If the datetype is set as 'custom’, this field specifies the date when the banner should become visible on the storefront.
datetype enum Accepted values are 'always’ or 'custom’. This specifies whether the banner should be visible during a specific date range. Required field.
location enum 'top’, 'bottom’. Required field.
datecreated date Date the banner was first created. This will default to today’s date.
catorbrandid int ID for the brand or category.
status/visible int Integer value denoting whether or not the banner is visible on the storefront: 1 = visible; 0 = not visible.
Manages Banner Object
OAuth Scopes store_v2_marketing
store_v2_marketing_read_only

List Banners

Gets the banners available. (Default sorting is by banner id, from lowest to highest.)

Filters

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

Parameter Type Example
min_id int /api/v2/banners?min_id={value}
max_id int /api/v2/banners?max_id={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 banners are returned by default.

Parameter Type Example
page int /api/v2/banners?page={number}
limit int /api/v2/banners?limit={count}

Response

Example JSON returned in the response:

    {
      "banners": {
        "banner": [
          {
            "id": "1",
            "name": "Grand Closing Sale",
            "page": "home_page",
            "content": "Thanks for shopping with us.",
            "date_to": "1393218000",
            "item_id": "0",
            "visible": "0",
            "location": "top",
            "date_from": "1391576400",
            "date_type": "custom",
            "date_created": "1392073898"
          },
          {
            "id": "2",
            "name": "New Year Nerd Bling",
            "page": "category_page",
            "content": "Discount on Apparel for Orders of $20 or more to Celebrate 2014. Use code NRDBLING14 at Checkout.",
            "date_to": "1394427600",
            "item_id": "30",
            "visible": "0",
            "location": "top",
            "date_from": "1392008400",
            "date_type": "custom",
            "date_created": "1392073935"
          },
          {
            "id": "3",
            "name": "Test",
            "page": "home_page",
            "content": "The latest in popular board games. Game night fun for the whole family.",
            "date_to": "0",
            "item_id": "0",
            "visible": "0",
            "location": "top",
            "date_from": "0",
            "date_type": "always",
            "date_created": "1429485000"
          },
          {
            "id": "4",
            "name": "Hi, Jason",
            "page": "home_page",
            "content": "Swanky",
            "date_to": "0",
            "item_id": "0",
            "visible": "0",
            "location": "top",
            "date_from": "0",
            "date_type": "always",
            "date_created": "1441858037"
          }
        ]
      }
    }

Get a Banner

Retrieves a specified banner.

Response

Example JSON returned in the response:

    {
      "banner": {
        "id": "4",
        "name": "Hi, Jason",
        "page": "home_page",
        "content": "Swanky",
        "date_to": "0",
        "item_id": "0",
        "visible": "0",
        "location": "top",
        "date_from": "0",
        "date_type": "always",
        "date_created": "1441858037"
      }
    }

Create a Banner

Creates a new banner.

Read-only Properties

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

Requirements

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

Response

Example JSON returned in the response:

    {
      "banner": {
        "id": "5",
        "name": "test",
        "page": "home_page",
        "content": "this is a test",
        "date_to": "0",
        "item_id": "0",
        "visible": "0",
        "location": "top",
        "date_from": "0",
        "date_type": "always",
        "date_created": "1449168936"
      }
    }

Update a Banner

Updates an existing banner. Your request may update any of the properties that are writeable for the Create (POST) operation.

Read-only Properties

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

Response

Example JSON returned in the response:

    {
      "banner": {
        "id": "4",
        "name": "Hi, Jason",
        "page": "home_page",
        "content": "Swanky",
        "date_to": "0",
        "item_id": "0",
        "visible": "0",
        "location": "top",
        "date_from": "0",
        "date_type": "always",
        "date_created": "1441858037"
      }
    }

Delete a Banner

Deletes a specified banner. (If successful, this will typically return a “204 No Content”.)

Delete All Banners

Deletes all banners associated with the store. (If successful, this will typically return a “204 No Content”.)

Gift Certificates

Gift certificates available to offer to a store’s customers.

Gift Certificate Object – Properties

Name Type Description
id int The ID of the gift certificate. Read-only.
code string A unique string that the customer can input to redeem the gift certificate. If this field is not set, a value will be generated.
amount decimal Value of the gift certificate. Required field.
status enum The gift certificate’s status. Affects the customer’s ability to apply the code to orders: Values can be ‘pending’, ’active’, ’disabled’, or ’expired’.
balance decimal Remaining value of the gift certificate. If not set, will default to the amount.
message string Text that will be sent to the recipient, such as ‘Congratulations’.
to_name string Name of the recipient. Required field.
order_id int The ID of the order. Read-only.
template string The email theme to use in the message sent to the recipient.
to_email string Email of the recipient. Required field.
from_name string Name of the customer who purchased the gift certificate. Required field.
from_email string Email of the customer who purchased the gift certificate. Required field.
customer_id int The ID of the customer placing the order.
expiry_date date Date on which the gift certificate is set to expire.
purchase_date date Date the gift certificate was purchased. If not assigned, this will be set to today’s date.

List Gift Certificates

Retrieves the gift certificates available. (Default sorting is by gift-certificate id, from lowest to highest.)

Filters

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

Parameter Type Example
min_id int /api/v2/gift_certificates?min_id={value}
max_id int /api/v2/gift_certificates?max_id={value}
code string /api/v2/gift_certificates?code={value}
to_name string /api/v2/gift_certificates?to_name={value}
to_email string /api/v2/gift_certificates?to_email={value}
from_name string /api/v2/gift_certificates?from_name={value}
from_email string /api/v2/gift_certificates?from_email={value}

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 gift_certificates are returned by default.

Parameter Type Example
page int /api/v2/gift_certificates?page={number}
limit int /api/v2/gift_certificates?limit={count}

Response

Example JSON returned in the response:

    {
      "giftcertificates": {
        "giftcertificate": [
          {
            "id": "24",
            "code": "10R-5E2-BO4-RWT",
            "amount": "1000.0000",
            "status": "active",
            "balance": "500.0000",
            "to_name": "Alyss",
            "order_id": "1281",
            "template": "false",
            "to_email": "test@test.com",
            "from_name": "Noland",
            "from_email": "test1@test.com",
            "customer_id": "0",
            "expiry_date": "0",
            "purchase_date": "1454432829"
          },
          {
            "id": "25",
            "code": "10R-6E3-AO4-RST",
            "amount": "700.0000",
            "status": "active",
            "balance": "700.0000",
            "to_name": "Alyss",
            "order_id": "0",
            "template": "false",
            "to_email": "test@test.com",
            "from_name": "Noland",
            "from_email": "test1@test.com",
            "customer_id": "0",
            "expiry_date": "0",
            "purchase_date": "1454433240"
          },
          {
            "id": "27",
            "code": "15R-6E3-AO4-RST",
            "amount": "50.0000",
            "status": "active",
            "balance": "50.0000",
            "to_name": "Lyss",
            "order_id": "0",
            "template": "false",
            "to_email": "test5@test.com",
            "from_name": "Somethingelse",
            "from_email": "test15@test.com",
            "customer_id": "0",
            "expiry_date": "0",
            "purchase_date": "1454433621"
          }
        ]
      }
    }

Get a Gift Certificate

Retrieves a specified gift certificate.

Response

Example JSON returned in the response:

    {
      "giftcertificate": {
        "id": "24",
        "code": "10R-5E2-BO4-RWT",
        "amount": "500.0000",
        "status": "active",
        "balance": "500.0000",
        "to_name": "Jane",
        "order_id": "1281",
        "template": "false",
        "to_email": "test@test.com",
        "from_name": "Tarzan",
        "from_email": "test1@test.com",
        "customer_id": "0",
        "expiry_date": "0",
        "purchase_date": "1454432829"
      }
    }

Create a Gift Certificate

Creates a new gift certificate.

Read-only Properties

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

Requirements

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

Notes

When a gift certificate is created through the API, no email notification is triggered to the specified recipient.

The gift certificate’s status can be one of the following:

The gift certificate’s template can be one of the following:

Request

Example request object:

    {
      "code": "10R-6E3-AO4-RST",
      "amount": "700.0000",
      "status": "active",
      "to_name": "Jane",
      "to_email": "test@test.com",
      "from_name": "Tarzan",
      "from_email": "test1@test.com"
    }

Response

Example JSON returned in the response:

    {
      "giftcertificate": {
        "id": "25",
        "code": "10R-6E3-AO4-RST",
        "amount": "700.0000",
        "status": "active",
        "balance": "700.0000",
        "to_name": "Jane",
        "order_id": "0",
        "template": "false",
        "to_email": "test@test.com",
        "from_name": "Tarzan",
        "from_email": "test1@test.com",
        "customer_id": "0",
        "expiry_date": "0",
        "purchase_date": "1454433240"
      }
    }

Update a Gift Certificate

Updates an existing gift certificate.

Read-only Properties

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

Request

Example request object:

    {
      "amount": "1000.0000"
    }

Response

Example JSON returned in the response:

    {
      "giftcertificate": {
        "id": "24",
        "code": "10R-5E2-BO4-RWT",
        "amount": "1000.0000",
        "status": "active",
        "balance": "500.0000",
        "to_name": "Jane",
        "order_id": "1281",
        "template": "false",
        "to_email": "test@test.com",
        "from_name": "Tarzan",
        "from_email": "test1@test.com",
        "customer_id": "0",
        "expiry_date": "0",
        "purchase_date": "1454432829"
      }
    }

Delete a Gift Certificate

Deletes a specified gift certificate. (If successful, this will typically return a “204 No Content”.)

Delete All Gift Certificates

Deletes all gift certificates associated with the store. (If successful, this will typically return a “204 No Content”.)

Payments Reference

The Payment Methods object, and List Payment Methods endpoint, help stores receive money from transactions.

Payment Methods

Enabled payment types or methods in a store.

Payment Method Object – Properties

Name Type Description
code string Unique platform-wide code identifying the payment method.
name string Descriptive name of the payment method.
test_mode boolean Determines whether the payment gateway is in test mode. Always false for offline payment methods.
Manages
OAuth Scopes store_v2_information
store_v2_information_read_only

List Payment Methods

Gets the list of enabled payment methods. (Default sorting is by payment method, alphabetically from A to Z.)

Filters

There are no filter parameters specific to payment methods.

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 payment_methods are returned by default.

Parameter Type Example
page int /api/v2/payments/methods?page={number}
limit int /api/v2/payments/methods?limit={count}
[
  {
    "code": "bankdeposit",
    "name": "Bank Deposit",
    "test_mode": false
  },
  {
    "code": "cod",
    "name": "Cash on Delivery",
    "test_mode": false
  },
  {
    "code": "paypalexpress",
    "name": "PayPal Express Checkout",
    "test_mode": false
  },
  {
    "code": "stripe",
    "name": "Stripe",
    "test_mode": false
  }
]

Shipping Methods Reference

The Shipping Methods object and endpoints help manage the shipping of physical items from merchant to shopper.

Shipping Method Object – Properties

A Shipping Method object represents a shipping method enabled within the store.

Name Type Description
id int shipping method id
name string display name for shipping method
method_name string shipping method name
Manages
OAuth Scopes store_v2_information
store_v2_information_read_only

List Shipping Methods

Gets the list of shipping methods. (Default sorting is by shipping-method id, from lowest to highest.)

Filters

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

Parameter Type Example
id string /api/v2/shipping/methods?id={value}
min_id int /api/v2/shipping/methods?min_id={value}
max_id int /api/v2/shipping/methods?max_id={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 shipping_methods are returned by default.

Parameter Type Example
Page int /api/v2/shipping/methods?page={number}
Limit int /api/v2/shipping/methods?limit={count}

Response

Example JSON returned in the response:

[
  {
    "id": 1,
    "name": "Australia Post",
    "method_name": "shipping_auspost"
  },
  {
    "id": 2,
    "name": "Canada Post",
    "method_name": "shipping_canpost"
  }
]

Get a Shipping Method

Gets a shipping method.

Response

Example JSON returned in the response:

{
  "id": 1,
  "name": "Australia Post",
  "method_name": "shipping_auspost"
}

Store Information Reference

The Store Information object, and Get Store Information endpoint, manage store profile settings.

Store Information Object – Properties

A Store Information object represents an individual store’s profile and metadata.

Name Type Description
id string Unique store identifier.
domain string Primary domain name.
secure_URL string Store’s current HTTPS URL.
name string Store’s name.
first_name string Primary contact’s first name (as defined during the store sign-up process).
last_name string Primary contact’s last name (as defined during the store sign-up process).
address string Display address.
country string Country where the store is located (as defined during the store sign-up process).
phone string Display phone number.
admin_email string Email address of the store administrator/owner.
order_email string Email address for orders and fulfillment.
timezone object An object that defines the store’s time zone, following conventions of the PHP date function. (For details, please see: http://php.net/manual/en/function.date.php.) This object contains the following elements:
name: a string identifying the time zone, in the format: <Continent-name>/<City-name>.
raw_offset: a negative or positive number, identifying the offset from UTC/GMT, in seconds, during winter/standard time.
dst_offset: -/+ (number) offset from UTC/GMT, in seconds, during summer/daylight saving time.
dst_correction: a boolean indicating whether this time zone observes daylight saving time.
date_format is a nested object, which contains the following internal elements:
* display: string that defines dates’ display format, in the pattern: M jS Y;
* export: string that defines the CSV export format for orders, customers, and products, in the pattern: M jS Y;
* extended_display: string that defines dates’ extended-display format, in the pattern: M jS Y @ g:i A.
language string Default language code.
currency string Default currency code.
currency_symbol string Default symbol for values in the currency.
decimal_separator string Default decimal separator for values in the currency.
thousands_separator string Default thousands separator for values in the currency.
decimal_places string Default decimal places for values in the currency.
currency_symbol_location string Default position of the currency symbol (left or right).
weight_units string Default weight units (metric or imperial).
dimension_units string Default dimension units (metric or imperial).
dimension_decimal_places string The number of decimal places.
dimension_decimal_token string The symbol that separates the whole numbers from the decimal points.
dimension_thousands_token string The symbol used to denote thousands.
plan_name string Name of the BigCommerce plan to which this store is subscribed.
plan_level string Level of the BigCommerce plan to which this store is subscribed.
industry string Industry, or vertical category, in which the business operates. (As selected from drop-down list during the store sign-up process.)
logo object
is_price_entered_with_tax boolean A Boolean value that indicates whether or not prices are entered with tax.
active_comparison_modules array
features object Array of flags for features that affect app compatibility or functionality. Child stencil_enabled element is a Boolean that indicates whether a store is using a Stencil theme.

Store Information – Webhook Events

Store Cancelled

store/app/uninstall

Occurs when a client store is cancelled and uninstalled from the platform.

Manages
OAuth Scopes store_v2_information
store_v2_information_read_only

Get a Store’s Information

Gets metadata about a store.

Response

Example JSON returned in the response:

{
  "id": "cl1xgr",
  "domain": "sandbox.mybigcommerce.com",
  "secure_url": "https://store-abc123.mybigcommerce.com",
  "name": "My Sandbox Store",
  "first_name": "Sylvester",
  "last_name": "Biggs",
  "address": "555 Test Way\nQuality City, CA 94109\nUSA",
  "country": "United States",
  "phone": "567-098-9274",
  "admin_email": "admin@bigcommerce.com",
  "order_email": "order@bigcommerce.com",
  "timezone": {
    "name": "America/Vancouver",
    "raw_offset": -28800,
    "dst_offset": -25200,
    "dst_correction": true,
    "date_format": {
      "display": "M jS Y",
      "export": "M jS Y",
      "extended_display": "M jS Y @ g:i A"
    }
  },
  "language": "en",
  "currency": "USD",
  "currency_symbol": "$",
  "decimal_separator": ".",
  "thousands_separator": ",",
  "decimal_places": 2,
  "currency_symbol_location": "left",
  "weight_units": "LBS",
  "dimension_units": "Inches",
  "dimension_decimal_places": "2",
  "dimension_decimal_token": ".",
  "dimension_thousands_token": ",",
  "plan_name": "15 Day Free Trial",
  "plan_level": "Trial",
  "industry": "Books/Music/Video",
  "logo": {
    "url": "http://cdn6.bigcommerce.com/s-cl1xgr/product_images/sandbox_logo_lp_1410899221__28020.jpg",
    "mobile_url": false
  },
  "is_price_entered_with_tax": false,
  "active_comparison_modules": [

  ],
  "features": {
    "stencil_enabled": false
  }
}

System Reference

The Get a Timestamp endpoint generates a timestamp ping to check the system status.

Manages
OAuth Scopes default

Get a Timestamp

Gets the system timestamp.

Notes

The time resource is useful for validating API authentication details and testing client connections.

It returns the system timestamp at the time of the request.

{
  "time": 1393657780
}

Tax Class Reference

The Tax Class object, and endpoints, manage tax calculations applied to sales. Tax classes are used to apply different tax rates for specific types of products and orders.

Tax Class Object – Properties

The tax_class object contains the ID and name of the tax class used to calculate tax for stores that use manually created tax classes.

Name Type Description
id int The unique numerical ID of the tax class. A read-only value which is automatically assigned and increments sequentially.
name string The name of the tax class.
Manages
OAuth Scopes store_v2_information
store_v2_information_read_only

List Tax Classes

Gets the tax classes set up for a store. (Default sorting is by tax-class id, from lowest to highest.)

Filters

There are no filter parameters specific to tax_classes.

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 tax_classes are returned by default.

Parameter Type Example
page int /api/v2/tax_classes?page={number}
limit int /api/v2/tax_classes?limit={count}

Get a Tax Class

Gets a tax class.

Webhooks Reference

The Webhooks object, and endpoints, register and manage webhooks that connect events from a store to external URLs.

Webhook Object – Properties

Name Type Description
id int A read-only value that uniquely identifies a webhook object. Do not attempt to set this value in a PUT or POST.
client_id string The OAuth client ID that uniquely identifies your application. BigCommerce returns this name-value pair in the JSON body of its responses.
store_hash string The hash value that uniquely identifies the store. Your application does not need to set this value via the JSON object; instead, you pass it in the path of your API requests.
scope enum The events that the webhook listens on. The full list of possibilities is in this overview.
destination string The fully qualified URI that BigCommerce uses as a callback. At runtime, when there is an event that your webhook is listening on, BigCommerce will send a POST request to this URI. Must be HTTPS.
headers object Optional name-value pairs that you can set when you create the webhook. At runtime, BigCommerce will include the name-value pair(s) in the HTTP header of its POST request to your callback URI.
is_active boolean Can contain one of three values: true, false, or <blank>. Default is no value, i.e., <blank>. If false, the webhook is inactive and will not send POST requests to the callback URI when an event occurs. If true, the webhook is active.
created_at int The time at which the webhook was created.
updated_at int The time at which the webhook was last updated.
Manages
OAuth Scopes default

List Hooks

Index of registered webhooks.

Response

Example JSON returned in the response:

[
  {
    "id": 101,
    "store_hash": "5ueh97",
    "client_id": "40c672b9177b5d3a8dbfad24321be15d",
    "scope": "store/order/*",
    "headers": {
      "X-Custom-Auth-Header": "{secret_auth_password}"
    },
    "destination": "https://app.example.com/orders",
    "created_at": "2013-01-17T11:27:50+11:00",
    "updated_at": "2013-01-17T11:27:50+11:00",
    "is_active": true
  },
  {
    "id": 102,
    "store_hash": "5ueh97",
    "client_id": "40c672b9177b5d3a8dbfad24321be15d",
    "scope": "store/product/created",
    "headers": {
      "X-Custom-Auth-Header": "{secret_auth_password}"
    },
    "destination": "https://app.example.com/products",
    "created_at": "2013-01-17T11:27:50+11:00",
    "updated_at": "2013-01-17T11:27:50+11:00",
    "is_active": true
  }
]

Get a Hook

Gets a registered webhook.

Response

Example JSON returned in the response:

{
  "id": 101,
  "store_hash": "5ueh97",
  "client_id": "40c672b9177b5d3a8dbfad24321be15d",
  "scope": "store/order/*",
  "headers": {
    "X-Custom-Auth-Header": "{secret_auth_password}"
  },
  "destination": "https://app.example.com/orders",
  "created_at": "2013-01-17T11:27:50+11:00",
  "updated_at": "2013-01-17T11:27:50+11:00",
  "is_active": true
}

Create a Hook

Register a new webhook.

Requirements

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

Notes

Scopes can be specified using wildcard syntax, or the full path to an event.

Request

Example request object:

{
  "scope": "store/order/*",
  "headers": {
    "X-Custom-Auth-Header": "{secret_auth_password}"
  },
  "destination": "https://app.example.com/orders",
  "is_active": true
}

Update a Hook

Edit the details of a registered webhook.

Request

Example request object:

{
  "destination": "https://app.example.com/orders_changed",
  "is_active": true
}

Response

Example JSON returned in the response:

{
  "id": 101,
  "store_hash": "5ueh97",
  "client_id": "40c672b9177b5d3a8dbfad24321be15d",
  "scope": "store/order/*",
  "headers": {
    "X-Custom-Auth-Header": "secret_hooks_auth_password"
  },
  "destination": "https://app.example.com/orders_changed",
  "created_at": "2013-01-17T11:27:50+11:00",
  "updated_at": "2013-01-18T11:27:50+11:00",
  "is_active": true
}

Delete a Hook

Deletes a single webhook.

Supported Browsers

Below are the browsers supported for the BigCommerce control panel. We drop support when a version falls below 2% of usage. The browsers are sorted by popularity, with the most popular browsers at the top.

Desktop
Chrome latest
Firefox latest
Internet Explorer 10 or later
Safari latest

For a current list of target browsers (desktop and mobile) that BigCommerce supports for storefronts using our themes, please see this support page.

API Status Codes

The API responds to requests with different HTTP status codes depending on the result from the request. Error responses might also include an error message in the body to assist the client in resolving the problem.

2xx Success

These codes are returned for requests that were understood and processed successfully.

Code Definition Purpose
200 OK For successful GET and PUT requests.
201 Created For a successful POST request.
202 Accepted For a request that resulted in a scheduled task being created to perform the actual request.
204 No Content For a successful request that produced no response (such as DELETE requests).

3xx Redirection

These codes are returned for requests that have resulted in the client needing to take further action to complete the request.

Code Definition Purpose
301 Moved Permanently When the API routes have changed (unlikely) or if the incoming request is not secure (http) then it will be redirect to the secure (https) version.
302 Found When the resource was found at a different location. When a request to a deprecated version of the API is received, a 302 Found response will be issued to the current API version.
304 Not Modified If an If-Modified-Since header is sent in the request and the resource has not been modified since the specified date, then this response will be sent. See resource specific pages for support for the If-Modified-Since header.

4xx Client Error

Code Definition Purpose
400 Bad Request Issued when a malformed request was sent. Examples are:
* Invalid syntax
* Missing required data
* Webhook requests missing Content-Type in the HTTP header.
401 Unauthorized This response is sent when your client failed to provide credentials or its credentials were invalid.
403 Forbidden Returned when permissions do not allow the operation or when the operation exceeds a limit.
* Check your app in My Apps to review the OAuth scopes you requested, and whether they support the request that you made.
* Changes to the store owner’s account can cause this error, including a change to the email address. Roll back those changes to correct this issue.
* This error can also occur when your request exceeds a limit imposed on the resource in question. For example, a store cannot exceed 16,000 categories. For more information, see the documentation of the resource in question.
404 Not Found When a particular resource doesn’t exist or couldn’t be found.
405 Method Not Allowed The resource was found, but doesn’t support the request method. Issued when either a specific method isn’t yet implemented on a resource, or the resource doesn’t support the method at all. For example, a PUT on /orders is invalid, but a PUT on /orders/{_id_} is valid.
406 Not Acceptable When the client specifies a response content type in the Accept header that is not supported.
409 Conflict A change requested by the client is being rejected, due to a condition imposed by the server. The exact reasons for this response will vary from one resource to the next. An example might be attempting to delete a category whose deletion would cause products to be orphaned. Additional information about the conflict, and about how to resolve it, might be available in the response’s details section.
413 Request Entity Too Large When the client requests too many objects. For example, the limit parameter exceeded the maximum.
415 Unsupported Media Type Returned due to issues with the Content-Type header. Examples are:
* The header specifies an unsupported content type.
* The header is missing (except with the webhooks resource, which returns a 400 in this case).
429 Too Many Requests When an OAuth client exceeds the rate limit for API requests to a store.

5xx Server Error

These codes are returned for requests that could not be processed due to an internal error with the API or server.

Code Definition Purpose
500 Internal Server Error When an error has occurred within the API.
501 Not Implemented When a request method is sent that is not supported by the API (e.g., TRACE, PATCH).
503 Service Unavailable When the store is marked as “Down for Maintenance,” or the store is being upgraded to a new version.
507 Insufficient Storage When the store has reached a limitation for the resource, according to their BigCommerce plan (e.g., 500-product limit).
509 (Deprecated) Bandwidth Limit Exceeded Returned to apps using Basic Authentication that have exceeded their rate limits.

Data Types

int

An integer number, with a maximum value of 2147483647. Negatives are disallowed, unless otherwise specified.

decimal(M, D)

A decimal number of up to M digits in total, including D digits after the decimal point. Negatives are disallowed, unless otherwise specified.

string(M)

A string of text up to M characters in length.

text

A string of text, up to ~16,777,216 bytes in length.

boolean

A boolean value: true or false. In JSON, it will be represented using the native boolean type. In XML, it will be the literal strings true or false.

date

An RFC 2822 date. All dates output by BigCommerce API responses are in GMT (+0000) time. However, you can use any time zone on inputs, as the offset information will be converted accordingly.

datetime

An ISO 8601 datetime value. This is currently supported only as an input parameter on filters. Date values in responses remain in the RFC 2822 format.

enum

An enumeration of string values. The only allowed values are those specified in the field’s description.

object

An object with its own set of fields.

country code

A two-character, ISO 3166-1 alpha-2 country code.

email address

A valid email address. 250 characters maximum.

variable

Variable data, depending on context. See the field definition for specifics.

array

A simple list of values. In JSON, this will be an array. In XML, the field will contain a set of <value> elements.

resource

A string representing a URI reference to another resource within the current version of the API.

null

A null value. In JSON this is represented as the native null type. In XML, it is represented as the literal string NULL.