Skip to main content
API docs by Redocly

Internal products service (2.0.0)

Download OpenAPI specification:Download

URL: https://developer-dashboard.boldcommerce.com/default/contactus

This API allows you to find information about your products, variants and categories.

Refer to the changelog for the latest updates to this API.

Customer Event Notifications

Event notifications you send to Bold when a change occurs to customers on the platform.

Order Event Notifications

Event notifications you send to Bold when a change occurs to orders on the platform.

Product Event Notifications

Event notifications you send to Bold when a change occurs to products on the platform.

Product Saved

Trigger this API call when product data changes, including product creation and updates.

Bold queues the product for saving. The request must contain the complete product object at the time the change occurred. Bold replaces all fields of the existing product object with the values provided in the request body. Bold ignores and does not update fields omitted from the request body.

The platform_updated_at field must be accurate to mitigate the risk incurred by out-of-sequence requests.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. This can be retrieved by calling the Get Shop Info endpoint.

Request Body schema: application/json
required
required
object (productSavedRequestData)
required
object (product)
platform_id
required
string

A unique identifier for the product. Defined by the platform.

platform_updated_at
required
string <date-time>

The date the product was last updated on the platform.

Array of objects (category)
required
Array of objects (deepVariant)

An array of variant objects. At least one variant is required. If the product has no variants, the variant can reuse the product information.

Array of objects (deepOption)

An array of product options.

Array of objects (deepImage)

An array of images depicting the product.

description
string

The description for the product.

handle
string

A unique, human-readable string for the product.

inventory_quantity
integer <int64>

The current inventory amount of the product.

inventory_tracking_entity
string
Enum: "variant" "product" "none"

The entity on which inventory is tracked.

inventory_tracking_service
string

The service that tracks inventory.

object

A map of localized descriptions for the product. The key is the ISO-639 two character language code. The value is the product description in the given language.

object

A map of localized names for the product. The key is the ISO-639 two character language code. The value is the product name in the given language.

name
string

The product name.

published
boolean

Indicates if the product is published on the storefront.

tags
string

A string with comma separated values describing the product.

tax_code
string

The tax code for the product.

type
string

A representation of platform-specific product data. The role of this field depends on the platform:

  • BigCommerce: The product type, either physical or digital.
  • commercetools: A merchant or partner-defined data set, valid as per options set in the platform.
  • Shopify: A product categorization, used for filtering and searching products.
  • Custom: Defined by the platform.
url
string

A URL to the product on the storefront.

vendor
string

The product vendor.

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{ }

Product Deleted

Trigger this API call when a product is deleted on the platform.

Bold queues the product for deletion. The platform_deleted_at field must be accurate to mitigate the risk incurred by out-of-sequence requests.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. This can be retrieved by calling the Get Shop Info endpoint.

Request Body schema: application/json
required
required
object (productDeletedRequestData)
required
object (deletedProduct)
platform_id
required
string

The platform ID of the product to be deleted.

platform_deleted_at
required
string <date-time>

The date the order was deleted on the platform, (in RFC3339 format). Assigned by the platform.

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{ }

Product Category Saved

Trigger this API call when a product category is saved on the platform.

Bold queues the product category for saving. The request contains the complete product category object at the time the change occurred. Bold replaces all fields of the existing product category object with the values provided in the request body. Fields omitted from the request body are ignored in the category object.

The platform_updated_at field must be accurate to mitigate the risk incurred by out-of-sequence requests.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. This can be retrieved by calling the Get Shop Info endpoint.

Request Body schema: application/json
required
required
object (categorySavedRequestData)
required
object (category)
platform_id
required
string

A unique identifier for the category. Defined by the platform.

platform_updated_at
required
string <date-time>

The date and time the category was last updated on the platform, in RFC 3339, section 5.6 format. If never updated, defaults to the platform_created_at value.

image_url
string

The URL location of the category image.

name
string

The name of the category.

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{ }

Product Category Deleted

Trigger this API call when a product category is deleted on the platform.

Bold queues the product category for deletion. The platform_deleted_at field must be accurate to mitigate the risk incurred by out-of-sequence requests.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. This can be retrieved by calling the Get Shop Info endpoint.

Request Body schema: application/json
required
required
object (categoryDeletedRequestData)
required
object (deletedCategory)
platform_id
required
string

The platform ID of the category to be deleted.

platform_deleted_at
required
string <date-time>

The date and time this category was deleted on the platform, in RFC 3339, section 5.6 format.

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{ }

Products

Contains information about the products associated with a given store. Use these endpoints to retrieve information about one or all products on a store.

List Products

Lists all products in the shop.

For more information on result pagination, refer to the Query & Pagination page.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

query Parameters
deep
boolean <boolean>
Example: deep=true

Indicates whether to perform a deep search. When set to true, this endpoint fetches and populates related child entities for the product in the response payload, including:

  • options
  • variants and their option_values
  • images
  • categories
  • localized_names
  • localized_descriptions
limit
integer <int32>
Example: limit=50

The maximum number of results to return per page.

page
integer <int32>
Example: page=1

The desired page number for the paginated results.

filter
Array of strings
Example: filter=eq(target:order)

A filter for returned results.

Accepts filtering options as described in the Query & Pagination page.

categoryid
integer <int64>
Example: categoryid=100

The category identifier to search within. Assigned by Bold.

filtercolumn
string
Example: filtercolumn=type

The column name by which to perform a fuzzy search with the filtervalue.

filtervalue
string
Example: filtervalue=%27hat%27

A search term used to perform a fuzzy search on the filtercolumn.

ordercolumn
string
Example: ordercolumn=type

The method of ordering the returned results. Must be paired with the orderdirection query parameter.

orderdirection
string
Example: orderdirection=asc

The direction of ordering returned results. Must be paired with the ordercolumn query parameter. Possible values include asc and desc.

updated_at_min
string <date-time>
Example: updated_at_min=2020-01-01T00:00:00Z

The earliest date (in RFC3339 format) the customer was updated.

updated_at_max
string <date-time>
Example: updated_at_max=2020-01-02T00:00:00Z

The latest date (in RFC3339 format) the product was updated.

include_deleted
boolean <boolean>
Example: include_deleted=true

Indicates whether to include deleted products in search results.

es_optimize
boolean <boolean>
Example: es_optimize=true

Indicates whether to optimize the results for Elasticsearch.

Responses

Response samples

Content type
application/json
{
  • "pagination": {},
  • "data": [
    ]
}

Get Product by Platform ID

Retrieves a product by its platform-specific identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

pid
required
string
Example: 110

The unique identifier for this category. Assigned by the shop platform.

query Parameters
deep
boolean <boolean>
Example: deep=true

Indicates whether to perform a deep search. When set to true, this endpoint fetches and populates related child entities for the product in the response payload, including:

  • options
  • variants and their option_values
  • images
  • categories
  • localized_names
  • localized_descriptions

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Product by ID

Retrieves a product by its Bold-specific identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

id
required
integer <int64>
Example: 100

The unique identifier for this product. Assigned by Bold.

query Parameters
deep
boolean <boolean>
Example: deep=true

Indicates whether to perform a deep search. When set to true, this endpoint fetches and populates related child entities for the product in the response payload, including:

  • options
  • variants and their option_values
  • images
  • categories
  • localized_names
  • localized_descriptions

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Product Types

Lists the product types for all products in the shop.

For more information on result pagination, refer to the Query & Pagination page.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "type": "Hat",
  • "data": [
    ]
}

List Product Vendors

Lists the vendors for all products in the shop.

For more information on result pagination, refer to the Query & Pagination page.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

Responses

Response samples

Content type
application/json
{
  • "type": "string",
  • "data": [
    ]
}

Variants

A child of the Product resource. Contains information about the variants of a product, which are derived from different combinations of options. Use these endpoints to retrieve information about a single variant, the variants of a single product, or all variants on a store.

List Product Variants

Lists the variants for a product by its Bold-specific product identifier.

For more information on result pagination, refer to the Query & Pagination page.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

bold_product_id
required
integer <int64>
Example: 123

A unique identifier for the product. Assigned by Bold.

query Parameters
limit
integer <int32>
Example: limit=50

The maximum number of results to return per page.

page
integer <int32>
Example: page=1

The desired page number for the paginated results.

Responses

Response samples

Content type
application/json
{
  • "pagination": {},
  • "data": [
    ]
}

Get Product Variant by Platform ID

Retrieves a product variant by its platform-specific identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

bold_product_id
required
integer <int64>
Example: 123

A unique identifier for the product. Assigned by Bold.

pid
required
string
Example: 110

The unique identifier for this product variant. Assigned by the shop platform.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Product Variant by ID

Retrieves a product variant by its Bold-specific identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

bold_product_id
required
integer <int64>
Example: 123

A unique identifier for the product. Assigned by Bold.

id
required
integer <int64>
Example: 100

The unique identifier for this product variant. Assigned by Bold.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Variants for Shop

Lists all product variants in the shop.

For more information on result pagination, refer to the Query & Pagination page.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

query Parameters
filter
Array of strings
Example: filter=eq(target:order)

A filter for returned results.

Accepts filtering options as described in the Query & Pagination page.

limit
integer <int32>
Example: limit=50

The maximum number of results to return per page.

page
integer <int32>
Example: page=1

The desired page number for the paginated results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {}
}

Categories

Contains information about the product categories applicable on a given store. Use these endpoints to retrieve information about one or all product categories on a store.

List Categories

Lists product categories for the shop.

For more information on result pagination, refer to the Query & Pagination page.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

query Parameters
limit
integer <int32>
Example: limit=50

The maximum number of results to return per page.

page
integer <int32>
Example: page=1

The desired page number for the paginated results.

ids
string
Example: ids=123,456,789

A comma-separated list of category identifiers, defining which categories to return.

Responses

Response samples

Content type
application/json
{}

Get Category by Platform ID

Retrieves a product category by its platform-assigned identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

pid
required
string
Example: 110

The unique identifier for the category. Assigned by the shop platform.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Category by ID

Retrieves a product category by its Bold-assigned identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

id
required
integer <int64>
Example: 100

The unique identifier for this category. Assigned by Bold.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Product Categories

Lists product categories for the shop.

For more information on result pagination, refer to the Query & Pagination page.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

query Parameters
limit
integer <int32>
Example: limit=50

The maximum number of results to return per page.

page
integer <int32>
Example: page=1

The desired page number for the paginated results.

filter
Array of strings
Example: filter=eq(target:order)

A filter for returned results.

Accepts filtering options as described in the Query & Pagination page.

Responses

Response samples

Content type
application/json
{}

Images

Contains information about the product images associated with a given store. Use these endpoints to retrieve information about one or all product images on a store.

List Product Images

Lists images for a product by its Bold-specific identifier.

For more information on result pagination, refer to the Query & Pagination page.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

bold_product_id
required
integer <int64>
Example: 123

A unique identifier for the product. Assigned by Bold.

query Parameters
limit
integer <int32>
Example: limit=50

The maximum number of results to return per page.

page
integer <int32>
Example: page=1

The desired page number for the paginated results.

Responses

Response samples

Content type
application/json
{}

Get Product Image by Platform ID

Retrieves a product image by its platform-assigned identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

bold_product_id
required
integer <int64>
Example: 123

A unique identifier for the product. Assigned by Bold.

pid
required
string
Example: 456

A unique identifier for the product. Assigned by the shop platform.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Product Image by ID

Retrieves a product image by its Bold-assigned identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

bold_product_id
required
integer <int64>
Example: 123

A unique identifier for the product. Assigned by Bold.

id
required
integer <int64>
Example: 456

A unique identifier for the product image. Assigned by Bold.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Options

A child of the Product resource. Contains information about the options associated with a given product, such as colors, sizes, weights, etc. Use these endpoints to retrieve information about one or all product options for a product.

List Product Options

Lists the options for a product by its Bold-specific identifier.

For more information on result pagination, refer to the Query & Pagination page.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

bold_product_id
required
integer <int64>
Example: 123

A unique identifier for the product. Assigned by Bold.

query Parameters
limit
integer <int32>
Example: limit=50

The maximum number of results to return per page.

page
integer <int32>
Example: page=1

The desired page number for the paginated results.

Responses

Response samples

Content type
application/json
{
  • "pagination": {},
  • "data": [
    ]
}

Get Product Option by Platform ID

Retrieves a product option by the platform-specific option identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

bold_product_id
required
integer <int64>
Example: 123

A unique identifier for the product. Assigned by Bold.

pid
required
string
Example: 110

A unique identifier for this product option. Assigned by the shop platform.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Product Option by ID

Retrieves a product option by the Bold-specific option identifier.

path Parameters
shop_identifier
required
string
Example: zp3oafdor9

A unique identifier of the store. Retrieve this information by calling the Get Shop Info endpoint.

bold_product_id
required
integer <int64>
Example: 123

A unique identifier for the product. Assigned by Bold.

id
required
integer <int64>
Example: 100

The unique identifier for the product option. Assigned by Bold.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}