When ShipperHQ is enabled on a store, additional fields become available on the product level:

  • Shipping Origins
  • Origin Locations
  • Dimensional Rules are accessible.

These field values can be set in the Control Panel by the merchant as well as using the Product Metafields Endpoint or the Variant Metafields Endpoint.


ShipperHQ Object Properties

Property Type Values
permission_set string This must be set to write. Setting to any other field will cause unintended behavior. required
key enum Members: shipping-groups, shipping-origins, shipping-dimensional-rules required
value JSON encoded string This will be the name of the attribute type in ShipperHQ. This needs to be input exactly how it is listed within ShipperHQ. To pass in more than one Shipping Origin, Origin Location or Dimensional Rule use an array with a comma-separated list. White spaces and special characters need to be escaped. Must be a JSON encoded string "[\"Origin Name from SHQ-1\",\" Origin Name from SHQ-2\"]" required
namespace string This will always be shipping.shipperhq required
resource_type string Either product or variant
resource_id string Id of the product or variant read-only
description string ShipperHQ shipping origins associated with this product/sku. read-only
date_created string Date and time of the metafield’s creation. read-only
date_modified string Date and time when the metafield was last updated. read-only
id number Id of the Metafield. read-only

The metafields must be entered exactly, otherwise they will not work. Since metafields can also be used to store information against a product, if the namespace for example is set to shipping and not shipping.shipperhq, it will not update the shipping information.


Control Panel Behavior

When Shipping Origins are set using the API, the fields cannot be deleted using the Control Panel. A /DELETE request must be sent to the metafields resource.

/DELETE https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/{{product_id}}/metafields


Add ShipperHQ Metafield

/POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/{{product_id}}/metafields

SHQ Add Metafield Request
{
  "permission_set": "write",
  "key": "shipping-origins",
  "value": "[\"Alaska\",\"California\"]",
  "namespace": "shipping.shipperhq"
}
SHQ Add Metafield Response
{
  "data": [
    {
      "id": 51,
      "key": "shipping-origins",
      "value": "[\"Alaska\",\"California\"]",
      "namespace": "shipping.shipperhq",
      "permission_set": "write",
      "resource_type": "product",
      "resource_id": 214,
      "description": "ShipperHQ shipping origins associated with this product/sku",
      "date_created": "2018-07-19T17:56:08+00:00",
      "date_modified": "2018-07-24T14:51:43+00:00"
    },
    {
      "id": 52,
      "key": "shipping-groups",
      "value": "[\"SHIPPING GROUP NAME\"]",
      "namespace": "shipping.shipperhq",
      "permission_set": "write",
      "resource_type": "product",
      "resource_id": 214,
      "description": "ShipperHQ shipping group rules associated with this product/sku",
      "date_created": "2018-07-24T14:51:43+00:00",
      "date_modified": "2018-07-24T14:51:43+00:00"
    },
    {
      "id": 53,
      "key": "shipping-dimensional-rules",
      "value": "[\"DIMENSIONAL RULES NAME\"]",
      "namespace": "shipping.shipperhq",
      "permission_set": "write",
      "resource_type": "product",
      "resource_id": 214,
      "description": "ShipperHQ dimensional rules associated with this product/sku",
      "date_created": "2018-07-24T14:51:43+00:00",
      "date_modified": "2018-07-24T14:51:43+00:00"
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 3,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}