Skip to main content

Platform Connector: Event Notifications (1.0.0)

Download OpenAPI specification:Download

This API allows platform connectors to push events to Bold when there are changes to a customer, order, or product resource. These events must trigger any time data changes on the platform (and Bold did not make this change). This ensures Bold applications are in sync with the platform and have access to the complete data set.

All successful responses from Bold contain an empty response body and return an HTTP 202 response code.

Note: This specification is only for use with a Bold Platform Connector.

Authentication

OAuthToken

Authenticates an API request from a public integration. Generate this token in the Developer Dashboard. Refer to Build Public Integrations for more information.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://apps.boldapps.net/accounts/dashboard/authorize
Token URL: https://api.boldcommerce.com/auth/oauth2/token

APIAccessToken

Authenticates an API request from a private integration.

Generate this token in the Bold Account Center. Refer to the Quickstart guide for more information.

Security Scheme Type API Key
Header parameter name: API Access Token

Customer Event Notifications

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

Customer Saved

Trigger this API call when customer data changes. This includes customer creation, customer updates, and any changes to a customer's associated addresses.

Bold then queues the customer — in the case of an update, identified in the request body by the platform_id — for saving. The request contains the complete customer object and its addresses at the time the change occurred. Bold replaces all fields of the existing customer object with the values provided in the request body. Fields omitted from the request body are ignored in the Customer object. The platform_updated_at field must be accurate to mitigate the risk incurred by out-of-sequence requests.

Authorizations:
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
object (customerSavedRequestData)
required
object (customer)
Array of objects (customerAddress) [ items ]

List of customer addresses.

platform_created_at
string <date-time>

Date (in RFC3339 format) that this customer was created on the platform. Assigned by the platform.

platform_updated_at
required
string <date-time>

Date (in RFC3339 format) that this customer was last modified on the platform. Assigned by the platform.

platform_id
required
string

Unique identifier for the customer. Assigned by the platform.

email
string <email>

Email address for the customer

first_name
string

First name of the customer

last_name
string

Last name of the customer

phone
string <phone>

Phone number for the customer

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Customer Deleted

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

Bold then queues the customer — identified in the request body by the platform_id — for deletion. The platform_deleted_at field must be accurate to mitigate the risk incurred by out-of-sequence requests.

Authorizations:
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
object (customerDeletedRequestData)
required
object (deletedCustomer)
platform_id
required
string

Unique identifier for the customer. Assigned by the platform.

platform_deleted_at
required
string <date-time>

Date (in RFC3339 format) that this customer was deleted on the platform. Assigned by the platform.

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Order Event Notifications

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

Order Saved

Trigger this API call when order data changes on the platform, including order creation and updates.

Bold queues the order for saving. The request must contain the complete order object at the time the change occurred. Bold replaces all fields of the existing order 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.

Authorizations:
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
object (orderSavedRequestData)
required
object (order)
platform_id
required
string

A unique identifier for the order. Assigned by the platform.

platform_updated_at
required
string <date-time>

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

Array of objects (address) [ items ]

A list of shipping addresses for the order.

object

The billing address for the order.

Array of objects (lineItem) [ items ]

A list of line items included in the order.

Array of objects (payment) [ items ]

A list of payments for the order.

order_number
string

A human-readable identifier for the order.

platform_customer_id
string

A unique identifier for the customer associated to this order. Assigned by the platform.

shipping_method
string

The shipping method for the order.

shipping_code
string

The code for the shipping method for the order. Each store defines its own shipping codes.

browser_ip
string

The browser IP under which the customer placed the order.

source
string

A label identifying the mechanism which placed the order.

created_via
string

A label identifying the app that created the order (if applicable).

locale
string

The locale code of the order (either in ISO-639 language code format or in ISO/IEC-15897 regional language format).

test
boolean

Indicates whether the order is a test order.

notes
string

Any internal notes about the order.

public_notes
string

Any customer-facing notes about the order.

object

A series of key-value pairs of metadata relevant to the order.

shipping_subtotal
required
string <double>

The cost of shipping the order, in the order's given currency.

shipping_tax
required
string <double>

The sum of shipping taxes for the ordered items, in the order's given currency.

Array of objects (tax) [ items ]

A list of the individual shipping taxes for the line items on the order.

discount
string <double>

The total amount discounted from the order, in the order's given currency. If there is no discount, set this field to "0".

Note: If discount is included in the payload, the total and total_tax values are required.

subtotal
required
string <double>

The subtotal of the line items on the order, in the order's given currency.

Note: Calculate the subtotal before taxes and discounts (if those values are not included in the line item prices).

subtotal_tax
required
string <double>

The tax to be charged on all line items, in the order's given currency.

total_tax
required
string <double>

The total tax on the full order, in the order's given currency, including: subtotal_tax, shipping_tax, and any other special taxes pending for the order.

total
required
string <double>

The total of order cost, in the order's given currency.

Note: This number includes taxes and is reduced by the discount.

refunded_amount
string <double>

The refunded amount of the order, if any, in the order's given currency.

currency
string

The base currency used for the order (in ISO-4217 currency code format).

order_status
string
Enum: "active" "cancelled"

The current status of the order. The status indicates whether the order is active or cancelled.

fulfillment_status
string
Enum: "pending" "partial" "delivered" "fulfilled"

The fulfillment status of the order.

financial_status
string
Enum: "held_for_review" "disputed" "cancelled" "pending" "preauthed" "refunded" "partially_paid" "partially_refunded" "paid"

The status of payments associated with the order. This field can only be set when the order is created and cannot be changed if the order is updated.

placed_at
string <date-time>

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

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Order Deleted

Trigger this API call when an order is deleted on the platform.

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

Authorizations:
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
object (orderDeletedRequestData)
required
object (deletedOrder)
platform_id
required
string

A unique identifier for the order. Assigned by the platform.

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 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.

Authorizations:
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
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) [ items ]
required
Array of objects (deepVariant) [ items ]

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) [ items ]

An array of product options.

Array of objects (deepImage) [ items ]

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.

Authorizations:
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
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.

Authorizations:
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
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.

Authorizations:
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
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
{ }