NAV
  • API v2 Documentation
  • Orders Reference
  • Products Reference
  • Store Content Reference
  • Currency Reference
  • Customers Reference
  • Geography Reference
  • Marketing Reference
  • Payments Reference
  • Shipping Zones Reference
  • Shipping Methods Reference
  • Store Information Reference
  • System Reference
  • Tax Class Reference
  • Subscribe to developer updates

    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.
    custom_status string Contains the same string value as the Order Statuses object's custom_label property.
    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 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 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",
        "custom_status": "Someone do something!",
        "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",
      "custom_status": "Someone do something!",
      "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",
      "custom_status": "Awaiting customer checkout",
      "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

    Archives an order.

    Delete All Orders

    Archives 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

    Product line items 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 Unique numeric ID for this order status.
    name string Predefined label for this order status.
    order int Ordinal position in which this status is displayed to merchants in the control panel's Orders >
    Order Statuses page.
    system_label string Takes same value as name. (Provided for consistency with BigCommerce's internal API.)
    system_description string Extended description of this order status. Predefined by BigCommerce, and not customizable.
    custom_label string Merchant-customizable label. Shows the label the merchant has customized in the BigCommerce control panel. If not customized, defaults to the same value as system_label.
    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",
      "system_label": "Incomplete",
      "custom_label": "Incomplete",
      "system_description": "An incomplete order happens when a shopper reached the payment page, but did not complete the transaction.",
      "order": 0
     },
     {
      "id": 1,
      "name": "Pending",
      "system_label": "Pending",
      "custom_label": "Pending",
      "system_description": "Customer started the checkout process, but did not complete it.",
      "order": 1
     },
     {
      "id": 2,
      "name": "Shipped",
      "system_label": "Shipped",
      "custom_label": "Shipped",
      "system_description": "Order has been shipped, but receipt has not been confirmed; seller has used the Ship Items action.",
      "order": 8
     },
     {
      "id": 3,
      "name": "Partially Shipped",
      "system_label": "Partially Shipped",
      "custom_label": "Partially Shipped",
      "system_description": "Only some items in the order have been shipped, due to some products being pre-order only or other reasons.",
      "order": 6
     },
     {
      "id": 4,
      "name": "Refunded",
      "system_label": "Refunded",
      "custom_label": "Refunded",
      "system_description": "Seller has used the Refund action.",
      "order": 11
     },
     {
      "id": 5,
      "name": "Cancelled",
      "system_label": "Cancelled",
      "custom_label": "Cancelled",
      "system_description": "Seller has cancelled an order, due to a stock inconsistency or other reasons.",
      "order": 9
     },
      {
      "id": 6,
      "name": "Declined",
      "system_label": "Declined",
      "custom_label": "Declined",
      "system_description": "Seller has marked the order as declined for lack of manual payment, or other reasons.",
      "order": 10
     },
      {
      "id": 7,
      "name": "Awaiting Payment",
      "system_label": "Awaiting Payment",
      "custom_label": "Awaiting Payment",
      "system_description": "Customer has completed checkout process, but payment has yet to be confirmed.",
      "order": 2
     },
      {
      "id": 8,
      "name": "Awaiting Pickup",
      "system_label": "Awaiting Pickup",
      "custom_label": "Awaiting Pickup",
      "system_description": "Order has been pulled, and is awaiting customer pickup from a seller-specified location.",
      "order": 5
     },
     {
      "id": 9,
      "name": "Awaiting Shipment",
      "system_label": "Awaiting Shipment",
      "custom_label": "Awaiting Shipment",
      "system_description": "Order has been pulled and packaged, and is awaiting collection from a shipping provider.",
      "order": 4
     },
     {
      "id": 10,
      "name": "Completed",
      "system_label": "Completed",
      "custom_label": "Completed",
      "system_description": "Client has paid for their digital product and their file(s) are available for download.",
      "order": 7
     },
     {
      "id": 11,
      "name": "Awaiting Fulfillment",
      "system_label": "Awaiting Fulfillment",
      "custom_label": "Awaiting Fulfillment",
      "system_description": "Customer has completed the checkout process and payment has been confirmed.",
      "order": 3
     },
     {
      "id": 12,
      "name": "Manual Verification Required",
      "system_label": "Manual Verification Required",
      "custom_label": "Manual Verification Required",
      "system_description": "Order on hold while some aspect needs to be manually confirmed.",
      "order": 13
     },
     {
      "id": 13,
      "name": "Disputed",
      "system_label": "Disputed",
      "custom_label": "Disputed",
      "system_description": "Customer has initiated a dispute resolution process for the PayPal transaction that paid for the order.",
      "order": 12
     },
     {
      "id": 14,
      "name": "Partially Refunded",
      "system_label": "Partially Refunded",
      "custom_label": "Partially Refunded",
      "system_description": "Seller has partially refunded the order.",
      "order": 14
     }
    ]
    

    Get an Order Status

    Gets a single order status.

    Response

    Example JSON returned in the response:

    {
      "id": 0,
      "name": "Incomplete",
      "system_label": "Incomplete",
      "custom_label": "Incomplete",
      "system_description": "An incomplete order happens when a shopper reached the payment page, but did not complete the transaction.",
      "order": 0
    }
    

    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; limited to 250 characters
    text string value; limited to 250 characters
    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 WebDAV 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"
    }
    

    Example Payload

    {
    "iss": "abc123",
    "iat": 123456789,
    "jti": "This is a completely unique string, ideally a UUID",
    "operation": "customer_login",
    "store_hash": "abc123",
    "customer_id": 12345,
    "redirect_to": "/account.php",
    "request_ip": "111.222.333.444"
    }
    

    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 Zones Reference

    The Shipping Zone object and endpoints manage shipping zones within countries.

    Shipping Zone Object – Properties

    Name Type Description
    id int Zone ID.
    name string Zone name.
    type enum The type of shipping zone. Possible string values are:
    zip: a list of ZIP/postal codes;
    country: one or more countries;
    state: a list of states;
    global: this value is treated as "rest of the world". (If the type value is global, then name and locations are not mandatory.)
    locations array Array of zone locations, each of which contains the following elements:
    id: location's ID (integer);
    zip: location's ZIP/postal code (string);
    country_iso2: 2-letter ISO Alpha-2 code for the country (string, see Notes below);
    state_iso2: ISO Alpha-2 code for the state (string, see Notes below).
    free_shipping object You can limit free shipping to orders exceeding a certain subtotal value. You can make products with fixed-price shipping ineligible for free shipping, but such products' prices will still count toward the minimum order threshold. This object contains the following elements:
    enabled: whether free shipping is enabled for this zone (boolean);
    minimum_subtotal: order subtotal that establishes threshold for free shipping (number);
    exclude_fixed_shipping_products: whether products with a fixed shipping cost are ineligible for free shipping (boolean).
    handling_fees object Handling-fee information for this zone. Contains the following elements:
    fixed_surcharge: the handling fee (number);
    display_separately: whether to display the handling fee separately at checkout (boolean).
    enabled boolean Whether this shipping zone is enabled.

    Notes

    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
    

    List Shipping Zones

    Gets all shipping zones.

    Response

    Example JSON returned in the response:

    [
      {
        "id": 1,
        "name": "United States",
        "type": "country",
        "locations": [
          {
            "id": 2,
            "country_iso2": "US"
          }
        ],
        "free_shipping": {
          "enabled": true,
          "minimum_subtotal": "10.0000",
          "exclude_fixed_shipping_products": false
        },
        "handling_fees": {
          "fixed_surcharge": "0.0000",
          "display_separately": true
        },
        "enabled": true
      },
      {
        "id": 2,
        "name": "Australia",
        "type": "country",
        "locations": [
          {
            "id": 3,
            "country_iso2": "AU"
          }
        ],
        "free_shipping": {
          "enabled": false,
          "minimum_subtotal": "0.0000",
          "exclude_fixed_shipping_products": false
        },
        "handling_fees": {
          "fixed_surcharge": "0.0000",
          "display_separately": true
        },
        "enabled": true
      }
    ]
    

    Get a Shipping Zone

    Retrieves a specified shipping zone by zone ID.

    Requirements

    The following properties of the shipping zone are required. The request won't be fulfilled unless these properties are valid.

    Response

    Example JSON returned in the response:

    {
      "id": 1,
      "name": "United States",
      "type": "country",
      "locations": [
        {
          "id": 2,
          "country_iso2": "US"
        }
      ],
      "free_shipping": {
        "enabled": true,
        "minimum_subtotal": "10.0000",
        "exclude_fixed_shipping_products": false
      },
      "handling_fees": {
        "fixed_surcharge": "0.0000",
        "display_separately": true
      },
      "enabled": true
    }
    

    Create a Shipping Zone

    Creates a new shipping zone.

    Request

    Example request object:

    {
     "name": "UnitedStates-NM",
     "type" : "state",
     "locations": [
       {
         "country_iso2": "US",
         "state_iso2": "NM"
       }
       ],
     "handling_fees": {
       "fixed_surcharge" : 12.00,
       "display_separately" : true
     }
    }
    

    Response

    Example JSON returned in the response:

    {
      "id": 2,
      "name": "UnitedStates-NM",
      "type": "state",
      "locations": [
        {
          "id": 2,
          "country_iso2": "US",
          "state_iso2": "NM"
        }
      ],
      "free_shipping": {
        "enabled": false,
        "minimum_subtotal": "0.0000",
        "exclude_fixed_shipping_products": false
      },
      "handling_fees": {
        "fixed_surcharge": "12.0000",
        "display_separately": true
      },
      "enabled": true
    }
    

    Update a Shipping Zone

    Updates an existing shipping zone.

    Requirements

    The following properties of the shipping zone are required. The request won't be fulfilled unless these properties are valid.

    Request

    Example request object:

    {
      "id": 2,
      "name": "UnitedStates-Samoa",
      "type": "state",
      "locations": [
        {
          "id": 5,
          "country_iso2": "US",
          "state_iso2": "AS"
        }
      ],
      "free_shipping": {
        "enabled": false,
        "minimum_subtotal": "0.0000",
        "exclude_fixed_shipping_products": false
      },
      "handling_fees": {
        "fixed_surcharge": "6.0000",
        "display_separately": true
      },
      "enabled": true
    }
    

    Response

    Example JSON returned in the response:

    {
      "id": 2,
      "name": "UnitedStates-Samoa",
      "type": "state",
      "locations": [
        {
          "id": 3,
          "country_iso2": "US",
          "state_iso2": "AS"
        }
      ],
      "free_shipping": {
        "enabled": false,
        "minimum_subtotal": "0.0000",
        "exclude_fixed_shipping_products": false
      },
      "handling_fees": {
        "fixed_surcharge": "6.0000",
        "display_separately": true
      },
      "enabled": true
    }
    

    Delete a Shipping Zone

    Deletes a specified shipping zone. (If successful, this will typically return a "204 No Content".)

    Requirements

    The following properties of the shipping zone are required. The request won't be fulfilled unless these properties are valid.

    Shipping Methods Reference

    The Shipping Methods object and endpoints manage shipping rules within Shipping Zones. These rules determine the shipping rates displayed at checkout, and related parts of the control panel, such as the shipping of manual orders.

    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.
    type string Shipping-method type. The currently supported static/fixed shipping-quote types are perorder, peritem, weight, or total. We plan to later add support for these dynamic/real-time shipping-quote types: auspost, canadapost, endicia, usps, fedex, royalmail, ups, upsready, or upsonline.
    settings object Depends on the shipping-method type. See the supported settings object models here.
    enabled boolean Whether or not this shipping-zone method is enabled.
    handling_fees object Handling-fee information for this method. This object currently contains the following element:
    fixed_surcharge: the handling fee.

    Settings Objects

    A shipping method's type and settings properties can match one of the following models:

    perorder Object – Properties

    Object model for flat-rate shipping quotes per order.

    Name Type Description
    rate number Flat rate per order.

    JSON Example

        {
        "name": "Flat Rate per Order",
        "type": "perorder",
        "settings": {
          "rate": 7
        },
    

    peritem Object – Properties

    Object model for flat-rate shipping quotes per item ordered.

    Name Type Description
    rate number Flat rate per item.

    JSON Example

        {
        "name": "Flat Rate per Item",
        "type": "peritem",
        "settings": {
          "rate": 8
        },
    

    weight Object – Properties

    Object model for shipping quotes by weight.

    Name Type Description
    default_cost number Default shipping cost, applied either as a percentage of the order's total value or as a fixed amount.
    default_cost_type string How the default shipping cost is calculated. One of: percentage_of_total or fixed_amount.
    range number Array of range objects. The units for these ranges' lower_limit and upper_limit properties depend on the default units set in the store's control panel.

    JSON Example

    {
    "name": "Rate per Weight",
    "type": "weight",
    "settings": {
         "default_cost": 12,
         "default_cost_type": "fixed_amount",
         "range": [
           {
             "lower_limit": 0,
             "upper_limit": 20,
             "shipping_cost": 8
           },
           {
             "lower_limit": 20,
             "upper_limit": 40,
             "shipping_cost": 12
           }
         ]
       }
    }
    

    total Object – Properties

    Object model for shipping quotes by order's total value.

    Name Type Description
    default_cost number Default shipping cost, applied either as a percentage of the order's total value or as a fixed amount.
    default_cost_type string How the default shipping cost is calculated. One of: percentage_of_total or fixed_amount.
    include_order_total_taxes boolean Whether or not to include taxes on the order's total value in the shipping-cost calculation.
    range number Array of range objects. The units for these ranges' lower_limit and upper_limit properties are values in the store's currency.

    JSON Example

    This example sets free shipping above a certain order total:

    {
    "name": "Per Total or Free",
    "type": "total",
    "settings": {
         "default_cost": 12,
         "default_cost_type": "fixed_amount",
         "include_order_total_taxes": 0,
         "range": [
           {
             "lower_limit": 0,
             "upper_limit": 5,
             "shipping_cost": 5
           },
           {
             "lower_limit": 5,
             "upper_limit": 10,
             "shipping_cost": 8
           },
           {
             "lower_limit": 10,
             "upper_limit": 20,
             "shipping_cost": 10
           },
           {
             "lower_limit": 20,
             "upper_limit": 49.99,
             "shipping_cost": 15
           },
           {
             "lower_limit": 50,
             "upper_limit": 100000,
             "shipping_cost": 0
           }       
         ]
       }
    }
    

    Range Object – Properties

    Object model to define ranges for shipping quotes. Units are defined in the parent object.

    Name Type Description
    lower_limit number Lower limit for order total.
    upper_limit number Upper limit for order total.
    shipping_cost number Shipping cost for orders whose total falls between the lower and upper limits.

    JSON Example

           {
             "lower_limit": 0,
             "upper_limit": 20,
             "shipping_cost": 8
           }
    

    List Shipping Methods

    Gets all configured shipping methods, by zone_id. (Default sorting is by shipping-method id, from lowest to highest.)

    Requirements

    The following properties of the shipping zone are required. The request won't be fulfilled unless these properties are valid.

    Response

    Example JSON returned in the response:

    [
      {
        "id": 3,
        "name": "Flat Rate",
        "type": "peritem",
        "settings": {
          "rate": 9
        },
        "enabled": true,
        "handling_fees": {
          "fixed_surcharge": 0
        }
      },
      {
        "id": 4,
        "name": "Ship by Weight",
        "type": "weight",
        "settings": {
          "default_cost": 12,
          "default_cost_type": "fixed_amount",
          "range": [
            {
              "lower_limit": 0,
              "upper_limit": 20,
              "shipping_cost": 8
            },
            {
              "lower_limit": 20,
              "upper_limit": 40,
              "shipping_cost": 12
            }
          ]
        },
        "enabled": true,
        "handling_fees": {
          "fixed_surcharge": 0
        }
      }
    ]
    

    Get a Shipping Method

    Gets a shipping method, specified by zone_id and method_id.

    Requirements

    The following properties of the shipping zone are required. The request won't be fulfilled unless these properties are valid.

    Response

    Example JSON returned in the response:

    {
      "id": 3,
      "name": "Flat Rate",
      "type": "peritem",
      "settings": {
        "rate": 9
      },
      "enabled": true,
      "handling_fees": {
        "fixed_surcharge": 0
      }
    }
    

    Create a Shipping Method

    Creates a new method in the specificed shipping zone.

    Requirements

    The following properties of the shipping zone are required. The request won't be fulfilled unless these properties are valid.

    Request

    Example request object:

    {
      "name": "Per Order",
      "type": "perorder",
      "settings": {
        "rate": 8
      },
      "enabled": true,
      "handling_fees": {
        "fixed_surcharge": 3
      }
    }
    

    Response

    Example JSON returned in the response:

    {
      "id": 5,
      "name": "Per Order",
      "type": "perorder",
      "settings": {
        "rate": 8
      },
      "enabled": true,
      "handling_fees": {
        "fixed_surcharge": 3
      }
    }
    

    Update a Shipping Method

    Updates an existing shipping method.

    Requirements

    The following properties of the shipping zone are required. The request won't be fulfilled unless these properties are valid.

    Request

    Example request object:

    {
      "settings": {
        "rate": 11
      },
      "handling_fees": {
        "fixed_surcharge": 0
      }
    }  
    

    Response

    Example JSON returned in the response:

    {
      "id": 5,
      "name": "Per Order",
      "type": "perorder",
      "settings": {
        "rate": 11
      },
      "enabled": true,
      "handling_fees": {
        "fixed_surcharge": 0
      }
    }
    

    Delete a Shipping Method

    Deletes a specified shipping method. (If successful, this will typically return a "204 No Content".)

    Requirements

    The following properties of the shipping zone are required. The request won't be fulfilled unless these properties are valid.

    Shipping Carrier Connections

    Carrier connections refer to specific settings required to connect to a specific shipping carrier. Each carrier requires your app to supply a unique set of properties/fields to establish a connection with that carrier.

    This section lists the endpoints, properties, and values supported per carrier, with sample requests.

    Endpoints Supported

    The Shipping Carrier Connections resource provides the following endpoints:

    Create a Carrier Connection

    Update a Carrier Connection

    Delete a Carrier Connection

    Australia Post

    Sample Request – PUT or POST

    {
        "carrier_id" : "auspost",
        "connection" : {
            "auth_key" : "yourAusPostAuthKey",
            "test_mode" : false
        }
    }
    

    Sample Request – DELETE

    {
        "carrier_id" : "auspost"
    }
    

    Australia Post Connection Object – Properties

    Australia Post PUT or POST requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) DELETE requests require only a carrier_id.

    Property Type Description
    auth_key string Australia Post authorization key.
    test_mode boolean Whether or not to use Australia Post test-mode settings. Acceptable values are true or false.

    Endicia

    Sample Request – PUT or POST

    {   "carrier_id" : "endicia",
        "connection": {
            "account_id" : "yourEndiciaAccountId",
            "pass_phrase" : "yourEndiciaPassphrase"
        }
    }
    

    Sample Request – DELETE

    {
        "carrier_id" : "endicia"
    }
    

    Endicia Connection Object – Properties

    Endicia PUT or POST requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) DELETE requests require only a carrier_id.

    Property Type Description
    account_id string Endicia account ID.
    passphrase string Endicia passphrase.

    FedEx

    Sample Request – PUT or POST

    {
        "carrier_id" : "fedex",
        "connection" : {
            "key" : "yourFedexKey",
            "password" : "yourFedexPassword",
            "account_number" : "yourFedexAccountNumber",
            "meter_number" : "yourFedexMeterNumber"
        }
    }
    

    Sample Request – DELETE

    {
        "carrier_id" : "fedex"
    }
    

    FedEx Connection Object – Properties

    FedEx PUT or POST requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) DELETE requests require only a carrier_id.

    Property Type Description
    key string FedEx account ID.
    password string FedEx passphrase.
    account_number string FedEx account number.
    meter_number string FedEx meter number.

    UPS Online (Legacy)

    Sample Request – PUT or POST

    {
        "carrier_id" : "upsonline",
        "connection" : {
            "license_number" : "yourUpsOnlineLicenseNumber",
            "user_id" : "yourUpsOnlineUserId",
            "password" : "yourUpsOnlinePassword",
            "account_number" : "yourUpsOnlinePassword",
            "test_mode" : false
        }
    }
    

    UPS Online (Legacy) Connection Object – Properties

    UPS PUT or POST requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) DELETE requests require only a carrier_id.

    Property Type Description
    license_number string UPS Online license number.
    user_id string UPS Online user ID.
    password string UPS Online password.
    account_number string UPS Online account number.
    test_mode boolean Whether or not to use UPS Online test-mode settings. Acceptable values are true or false.

    USPS (Legacy)

    Sample Request – PUT or POST

    {
        "carrier_id" : "usps",
        "connection" : {
            "username" : "yourUspsUserName",
            "test_mode" : false
        }
    }
    

    Sample Request – DELETE

    {
        "carrier_id" : "usps"
    }
    

    USPS (Legacy) Connection Object – Properties

    USPS PUT or POST requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) DELETE requests require only a carrier_id.

    Property Type Description
    username string USPS user name.
    test_mode boolean Whether or not to use USPS test-mode settings. Acceptable values are true or false.

    Zoom2U

    Sample Request – PUT or POST

    {
        "carrier_id" : "zoom2u",
        "connection" : {
            "auth_key" : "yourZoom2uAuthKey",
            "test_mode" : false
        }
    }
    

    Sample Request – DELETE

    {
        "carrier_id" : "zoom2u"
    }
    

    Zoom2U Connection Object – Properties

    Zoom2U PUT or POST requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) DELETE requests require only a carrier_id.

    Property Type Description
    auth_key string Zoom2U authorization key.
    test_mode boolean Whether or not to use Zoom2U test-mode settings. Acceptable values are true or false.

    Real-Time Carrier Configuration

    This section outlines the configuration of real-time carrier shipping methods, with sample requests and supported properties/values per carrier. This API provides a separate object per supported carrier.

    About Real-Time Configuration

    Real-time shipping methods rely on third-party carriers to retrieve shipping quotes during a shopper's checkout on a BigCommerce Store.

    This real-time carrier configuration API allows a merchant or agency to programatically configure shipping methods per zone.

    Applications for Real-Time Configuration

    Store owners, technology partners, and agencies can use this API to:

    Endpoint Support for Real-Time Configuration

    The following v2 endpoints support real-time carrier configuration:

    Get a Shipping Method:

    GET /stores/{store_hash}/api/v2/shipping/zones/{zone_id}/methods/{method_id}

    Create a Shipping Method:

    POST /stores/{store_hash}/api/v2/shipping/zones/{zone_id}/methods

    Update a Shipping Method:

    PUT /stores/{store_hash}/api/v2/shipping/zones/{zone_id}/methods/{method_id}

    Delete a Shipping Method:

    DELETE /stores/{store_hash}/api/v2/shipping/zones/{zone_id}/methods/{method_id}

    Carrier Configurations – Current

    This section provides a sample request, and a carrier-specific object/property model, for each supported carrier.

    USPS by Endicia

    Sample Request
    {
        "name": "USPS by Endicia",
        "type": "endicia",
        "settings": {
            "carrier_options": {
                "delivery_services" : ["PriorityExpress","Priority", "PriorityMailExpressInternational"],
                "packaging" : ["LargeFlatRateBox","FlatRateLegalEnvelope"],
                "show_transit_time" : true
            }
        },
        "enabled": true
    }
    
    USPS by Endicia Object Properties
    Property Type Values
    delivery_services array PriorityExpress
    PriorityMailExpressInternational
    FirstClassPackageInternationalService
    Priority
    PriorityMailInternational
    First
    ParcelSelect
    MediaMail
    packaging array FlatRateLegalEnvelope
    FlatRatePaddedEnvelope
    Parcel
    SmallFlatRateBox
    MediumFlatRateBox
    LargeFlatRateBox
    FlatRateEnvelope
    RegionalRateBoxA
    RegionalRateBoxB
    show_transit_time boolean true
    false

    FedEx

    Sample Request
    {
        "name": "FEDEX",
        "type": "fedex",
        "settings": {
            "carrier_options": {
                "delivery_services": [
                    "PRIORITY_OVERNIGHT",
                    "FEDEX_2_DAY"
                ],
                "dropoff_type": "REGULAR_PICKUP",
                "packaging_type": "FEDEX_ENVELOPE",
                "packing_method": "SEPARATE",
                "rate_type": "NONE",
                "include_package_value": true,
                "destination_type": "residential"
            }
        },
        "enabled": true
    }
    
    FedEx Object Properties
    Property Type Values
    delivery_services array PRIORITY_OVERNIGHT
    STANDARD_OVERNIGHT
    FIRST_OVERNIGHT
    FEDEX_2_DAY
    FEDEX_EXPRESS_SAVER
    INTERNATIONAL_PRIORITY
    INTERNATIONAL_ECONOMY
    INTERNATIONAL_FIRST
    FEDEX_1_DAY_FREIGHT
    FEDEX_2_DAY_FREIGHT
    FEDEX_3_DAY_FREIGHT
    FEDEX_GROUND
    GROUND_HOME_DELIVERY
    INTERNATIONAL_PRIORITY_FREIGHT
    INTERNATIONAL_ECONOMY_FREIGHT
    EUROPE_FIRST_INTERNATIONAL_PRIORITY
    dropoff_type string REGULAR_PICKUP
    REQUEST_COURIER
    DROP_BOX
    BUSINESS_SERVICE_CENTER
    STATION
    packaging_type string FEDEX_ENVELOPE
    FEDEX_PAK
    FEDEX_BOX
    FEDEX_TUBE
    FEDEX_10KG_BOX
    FEDEX_25KG_BOX
    YOUR_PACKAGING
    packing_method string SEPARATE
    COMBINED
    rate_type string NONE
    LIST
    include_package_value boolean true
    false
    destination_type string residential
    business

    UPS Ready

    Sample Request
    {
        "name": "UPS ready",
        "type": "upsready",
        "settings": {
            "carrier_options": {
                "delivery_services": [
                    "2nd_Day_Air","Standard"
                ],
                "packaging_type": "21",
                "packing_method": "separate",
                "include_package_value": true,
                "destination_type": "residential",
                "show_transit_time" : true
            }
        },
        "enabled": true
    }
    
    UPS Ready Object Properties
    Property Type Values
    delivery_services array 2nd_Day_Air
    2nd_Day_Air_AM
    3_Day_Select
    Expedited
    Express
    Express_Plus
    Express_Saver
    Express_Early_AM
    Ground
    Next_Day_Air
    Next_Day_Air_Early_AM
    Next_Day_Air_Saver
    Saver
    Standard
    Today_Dedicated_Courier
    Today_Express
    Today_Express_Saver
    Today_Intercity
    Today_Standard
    Worldwide_Expedited
    Worldwide_Express
    Worldwide_Express_Plus
    Worldwide_Express_Saver
    Worldwide_Saver
    destination_type string residential
    business
    packing_method string separate
    combined
    packaging_type string (only codes allowed) 21: UPS® Express Box
    24: UPS® 25 KG Box
    25: UPS® 10 KG Box
    30: Pallet
    01: UPS® Letter
    02: Customer Supplied Package
    03: Tube
    04: PAK
    2a: Small Express Box
    2b: Medium Express Box
    2c: Large Express Box
    include_package_value boolean true
    false
    show_transit_time boolean true
    false

    Canada Post

    Sample Request
    {
        "name": "Canada Post",
        "type": "canadapost",
        "settings": {
            "carrier_options": {
                "delivery_services": [
                    "DOM.RP","DOM.EP"
                ]
            }
        },
        "enabled": true
    }
    
    Canada Post Object Properties
    Property Type Values
    delivery_services array DOM.RP
    DOM.EP
    DOM.XP
    DOM.XP.CERT
    DOM.PC DOM.LIB
    USA.EP
    USA.PW.ENV
    USA.PW.PAK
    USA.PW.PARCEL
    USA.SP.AIR
    USA.TP
    USA.TP.LVM
    USA.XP
    INT.XP
    INT.IP.AIR
    INT.IP.SURF
    INT.PW.ENV
    INT.PW.PAK
    INT.PW.PARCEL
    INT.SP.AIR
    INT.SP.SURF
    INT.TP

    Australia Post

    {
        "name": "Australia Post",
        "type": "auspost",
        "settings": {
            "carrier_options": {
                "delivery_services": [
                    "AUS_PARCEL_REGULAR",
                    "AUS_PARCEL_EXPRESS"
                ]
            }
        },
        "enabled": true
    }
    
    Australia Post Object Properties
    Property Type Values
    delivery_services array AUS_LETTER_REGULAR_SMALL
    AUS_LETTER_REGULAR_Large
    AUS_LETTER_EXPRESS_SMALL
    AUS_LETTER_EXPRESS_MEDIUM
    AUS_LETTER_EXPRESS_LARGE
    AUS_PARCEL_REGULAR
    AUS_PARCEL_REGULAR_SATCHEL_500G
    AUS_PARCEL_REGULAR_SATCHEL_3KG
    AUS_PARCEL_REGULAR_SATCHEL_5KG
    AUS_PARCEL_EXPRESS
    AUS_PARCEL_EXPRESS_SATCHEL_500G
    AUS_PARCEL_EXPRESS_SATCHEL_3KG
    AUS_PARCEL_EXPRESS_SATCHEL_5KG
    AUS_PARCEL_COURIER
    AUS_PARCEL_COURIER_SATCHEL_MEDIUM
    INT_PARCEL_COR_OWN_PACKAGING
    INT_PARCEL_EXP_OWN_PACKAGING
    INT_PARCEL_STD_OWN_PACKAGING
    INT_PARCEL_AIR_OWN_PACKAGING
    INT_PARCEL_SEA_OWN_PACKAGING

    Royal Mail

    Sample Request
    {
        "name": "Royal Mail",
        "type": "royalmail",
        "settings": {
            "carrier_options": {
                "delivery_services": [
                    "StandardFirstClass",
                    "StandardSecondClass"
                ]
            }
        },
        "enabled": true
    }
    
    Royal Mail Object Properties
    Property Type Values
    delivery_services array SpecialDelivery1pm
    SpecialDelivery9am
    SpecialDelivery1pmSaturday
    SpecialDelivery9amSaturday
    SignedForFirstClass
    SignedForSecondClass
    Express9
    Express10
    ExpressAM
    Express24
    Express48
    StandardFirstClass
    StandardSecondClass
    InternationalStandard
    InternationalTracked
    InternationalEconomy

    Zoom2U

    Sample Request
    {
        "name": "Zoom2U",
        "type": "zoom2u",
        "settings": {
            "carrier_options": {
                "delivery_services": [
                    "3_hour",
                    "Same_day",
                    "VIP"
                ]
            }
        },
        "enabled": true
    }
    
    Zoom2U Object Properties
    Property Type Values
    delivery_services array 3_hour
    Same_day
    VIP

    Carrier Configurations – Legacy

    BigCommerce no longer supports the carrier implementations below. We have replaced them with the newer integrations listed above.

    USPS (Legacy)

    Sample Request
    {
        "name": "USPS (Legacy)",
        "type": "usps",
        "settings": {
            "carrier_options": {
                "express_mail_package_size": "REGULAR",
                "express_mail_container_type" : "AUTO",
                "first_class_package_size" : "REGULAR",
                "priority_mail_package_size" : "REGULAR",
                "priority_mail_container_type" : "AUTO",
                "parcel_post_package_size" : "REGULAR",
                "library_package_size" : "REGULAR",
                "media_package_size" : "REGULAR",
                "international_package_size" : "REGULAR",
                "international_services" : ["1","2","4"]
            }
        },
        "enabled": true
    }
    
    USPS (Legacy) Object Properties
    Property Type Values
    express_mail_package_size string REGULAR
    LARGE
    express_mail_container_type string AUTO
    FLAT RATE ENVELOPE
    first_class_package_size string REGULAR
    LARGE
    priority_mail_package_size string REGULAR
    LARGE
    priority_mail_container_type string AUTO
    FLAT RATE ENVELOPE
    FLAT RATE BOX
    parcel_post_package_size string REGULAR
    LARGE
    OVERSIZE
    library_package_size string REGULAR
    LARGE
    media_package_size string REGULAR
    LARGE
    international_package_size string REGULAR
    LARGE
    international_services string (multiple selection) 1: Express Mail International
    2: Priority Mail International
    4: Global Express Guaranteed Document and Non-document
    5: Global Express Guaranteed Document
    6: Global Express Guaranteed Rectangular
    7: Global Express Guaranteed Non-Rectangular
    8: Priority Mail Flat Rate Envelope
    9: Priority Mail Flat Rate Box
    10: Express Mail International Flat Rate Envelope
    11: Priority Mail Large Flat Rate Box
    12: Global Express Guaranteed Envelope
    13: First Class Mail International Letters
    14: First Class Mail International Flats
    15: First Class Mail International Parcels

    UPS

    Sample Request
    {
        "name": "UPS (Legacy)",
        "type": "ups",
        "settings": {
            "carrier_options": {
                "packaging_type": "21",
                "shipping_rate" : "Regular Daily Pickup",
                "destination_type" : "RES",
                "delivery_services" : ["1DM", "1DP", "1DA","XPR"]
            }
        },
        "enabled": true
    }
    
    UPS Object Properties
    Property Type Values
    packaging_type string
    (only code values allowed)
    21: UPS Express Box
    24: UPS Worldwide 25 kilo
    25: UPS Worldwide 10 kilo
    00: Customer Packaging
    01: UPS Letter Envelope
    03: UPS Tube
    shipping_rate string AUTO
    FLAT RATE ENVELOPE
    destination_type string
    (only code values allowed)
    RES: Residential
    COM: Commercial
    delivery_services array
    (only code values allowed)
    1DM: Next Day Air Early AM
    1DA: Next Day Air
    1DP: Next Day Air Saver
    2DM: 2nd Day Air Early AM
    2DA: 2nd Day Air
    3DS: 3 Day Select
    GND: Ground
    STD: Canada Standard
    XPR: Worldwide Express
    XDM: Worldwide Express Plus
    XPD: Worldwide Expedited

    UPSONLINE

    Sample Request
    {
        "name": "UPSONLINE (Legacy)",
        "type": "upsonline",
        "settings": {
            "carrier_options": {
                "destination_type": "0",
                "customer_classification_code" : "01",
                "pickup_type" : "11",
                "packaging_type": "21",
                "dimension_type" : "Separate",
                "delivery_services" : ["11", "12", "07","08"]
            }
        },
        "enabled": true
    }
    
    UPSONLINE Object Properties
    Property Type Values
    destination_type string
    (only code values allowed)
    0: Commercial
    1: Residential
    customer_classification_code string
    (only code values allowed)
    01: Wholesale
    03: Occasional
    04: Retail
    pickup_type string
    (only code values allowed)
    11: Suggested Retail Rates
    19: Letter Center
    20: Air Service Center
    01: Daily Pickup
    03: Customer Counter
    06: One Time Pickup
    07: On Call Air
    packaging_type string
    (only code values allowed)
    21: Express Box
    24: 25KG Box
    25: 10KG Box
    30: Pallet
    00: Unknown 01: UPS Letter
    02: Package
    03: Tube
    04: Pak
    2A: Small Express Box
    2B: Medium Express Box
    2C: Large Express Box
    dimension_type string Combined
    Separate
    None
    delivery_services array
    (only code values allowed)
    11:Worldwide Standard
    12:3 Day Select
    13:Next Day Air Saver
    14:Next Day Air (Early AM)
    54:Worldwide Express Plus
    59:2nd Day Air (AM)
    65:Worldwide Express Saver
    01:Next Day Air
    02:2nd Day Air
    03:Ground
    07:Worldwide Express
    08:Worldwide Expedited

    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.