Platform Connector: Event Notifications (1.0.0)

Download OpenAPI specification:Download

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

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.

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

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

For more information about Platform Connectors, refer to the Overview.

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 on the platform. This includes customer creation, customer updates, and any changes to a customer's associated addresses.

Bold queues the customer for saving. The request must contain 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. Bold ignores and does not update the 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:

OAuthTokenAPIAccessToken

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 (customerSavedRequestData)

required

object (customer)

	Array of objects (customerAddress) A list of customer addresses.
platform_created_at	string <date-time> The date (in RFC3339 format) that this customer was created on the platform. Assigned by the platform.
platform_updated_at required	string <date-time> The date (in RFC3339 format) that this customer was last modified on the platform. Assigned by the platform.
platform_id required	string A unique identifier for the customer. Assigned by the platform.
email	string <email> The email address for the customer.
first_name	string The first name of the customer.
last_name	string The last name of the customer.
phone	string <phone> A phone number for the customer.

Responses

Request samples

Payload

Content type

application/json

{"data": {"customer": {"addresses": [{"platform_id": "Address_456",
"address_type": "commercial",
"address_use": "shipping",
"company": "Acme Corp.",
"city": "Winnipeg",
"country": "Canada",
"country_code": "CA",
"is_default": true,
"first_name": "John",
"last_name": "Doe",
"phone": "555-555-5555",
"postal_code": "H0H 0H0",
"province": "Manitoba",
"province_code": "MB",
"street_1": "123 North Road",
"street_2": "Unit 5"
}
],
"platform_created_at": "2023-01-09T15:35:57",
"platform_updated_at": "2023-01-09T15:35:57",
"platform_id": "Customer_123",
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"phone": "555-555-5555"
}
}
}

Response samples

202
400
500

Content type

application/json

{ }

Customer Deleted

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

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

Authorizations:

OAuthTokenAPIAccessToken

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 (customerDeletedRequestData)

required

object (deletedCustomer)

platform_id required	string A unique identifier for the customer. Assigned by the platform.
platform_deleted_at required	string <date-time> The date (in RFC3339 format) that this customer was deleted on the platform. Assigned by the platform.

Responses

Request samples

Payload

Content type

application/json

{"data": {"customer": {"platform_id": "Customer_123",
"platform_deleted_at": "2023-04-09T12:33:44"
}
}
}

Response samples

202
400
500

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:

OAuthTokenAPIAccessToken

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 (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) A list of shipping addresses for the order.
	object (address) The billing address for the order.
	Array of objects (lineItem) A list of line items included in the order.
	Array of objects (payment) 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.
platform_friendly_id	string A unique identifier for the order on the platform. This field is used to identify the order on the platform and is used by the Bold Checkout Admin to link the order to 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) 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.
	object The list of discounts applied to the order.
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

Payload

Content type

application/json

{"data": {"order": {"platform_id": "order-123456",
"platform_updated_at": "2019-08-24T14:15:22Z",
"shipping_addresses": [{"platform_id": "address-123456",
"address_type": "commercial",
"first_name": "John",
"last_name": "Doe",
"street_1": "123 North Road",
"street_2": "Suite 200",
"city": "Winnipeg",
"province": "Manitoba",
"country": "Canada",
"country_code": "CA",
"phone": "555-555-5555",
"postal_code": "H0H 0H0",
"email": "[email protected]",
"province_code": "MB",
"company": "Acme Corp."
}
],
"billing_address": {"platform_id": "address-123456",
"address_type": "commercial",
"first_name": "John",
"last_name": "Doe",
"street_1": "123 North Road",
"street_2": "Suite 200",
"city": "Winnipeg",
"province": "Manitoba",
"country": "Canada",
"country_code": "CA",
"phone": "555-555-5555",
"postal_code": "H0H 0H0",
"email": "[email protected]",
"province_code": "MB",
"company": "Acme Corp."
},
"line_items": [{"platform_id": "line-item-123456",
"platform_product_id": "product-123456",
"platform_variant_id": "variant-123456",
"cart_line_item_platform_id": "cart-line-item-123456",
"custom_attributes": {"property1": {"description": "field-1",
"value": "value-1"
},
"property2": {"description": "field-1",
"value": "value-1"
}
},
"title": "Shoes (long-laced classic)",
"sku": "TSH-FF0000-L",
"url": "https://example.com/shoes",
"image": "http://shop.images/shoes",
"quantity": 1,
"grams": 10,
"weight": 10,
"weight_unit": "grams",
"taxable": true,
"taxes": [{"amount": "5.00",
"name": "Provincial Sales Tax",
"rate": "0.07",
"tag": "tag-1"
}
],
"requires_shipping": true,
"price_per_item": "10.00",
"discount_per_item": "0",
"total": "15.00",
"subtotal": "10.00",
"total_tax": "5.00",
"discounted_subtotal": "10.00"
}
],
"payments": [{"platform_id": "payment-123456",
"transactions": [{"platform_id": "transaction-123456",
"provider_transaction_id": "provider-transaction-123456",
"amount": "15.00",
"currency": "CAD",
"status": "success",
"type": "charge"
}
],
"description": "Credit card payment",
"provider": "stripe",
"payment_method": "credit card",
"currency": "CAD",
"amount_planned": "15.00",
"custom_attributes": {"property1": {"description": "field-1",
"value": "value-1"
},
"property2": {"description": "field-1",
"value": "value-1"
}
},
"status": "paid"
}
],
"order_number": "ORDER_XXYY1122",
"platform_customer_id": "customer-123456",
"platform_friendly_id": "PT-0065",
"shipping_method": "freight",
"shipping_code": "S001",
"browser_ip": "127.0.0.1",
"source": "POS",
"created_via": "Bold Checkout",
"locale": "en_US",
"test": false,
"notes": "Handle with care.",
"public_notes": "Order contains fragile items.",
"custom_attributes": {"property1": {"description": "field-1",
"value": "value-1"
},
"property2": {"description": "field-1",
"value": "value-1"
}
},
"shipping_subtotal": "5.00",
"shipping_tax": "1.00",
"shipping_taxes": [{"amount": "5.00",
"name": "Provincial Sales Tax",
"rate": "0.07",
"tag": "tag-1"
}
],
"discount": "0",
"discounts": {"property1": {"platform_id": "discount-123456",
"amount": "5.00",
"discount_code": "20OFF"
},
"property2": {"platform_id": "discount-123456",
"amount": "5.00",
"discount_code": "20OFF"
}
},
"subtotal": "10.00",
"subtotal_tax": "5.00",
"total_tax": "5.00",
"total": "20.00",
"refunded_amount": "0",
"currency": "CAD",
"order_status": "active",
"fulfillment_status": "partial",
"financial_status": "pending",
"placed_at": "2019-08-24T14:15:22Z"
}
}
}

Response samples

202
400
500

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:

OAuthTokenAPIAccessToken

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

Payload

Content type

application/json

{"data": {"order": {"platform_id": "order-123456",
"platform_deleted_at": "2020-08-24T14:15:22Z"
}
}
}

Response samples

202
400
500

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:

OAuthTokenAPIAccessToken

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

Payload

Content type

application/json

{"data": {"product": {"platform_id": "product-123456",
"platform_updated_at": "2019-08-24T14:15:22Z",
"categories": [{"platform_id": "category-123456",
"platform_updated_at": "2019-08-24T14:15:22Z",
"image_url": "your_platform_connector.com/files/categories/hats.jpg",
"name": "Hats"
}
],
"variants": [{"platform_id": "variant-123456",
"option_values": [{"platform_id": "abc123456",
"platform_product_option_id": "VAR-10001-SM",
"label": "small",
"name": "Small"
}
],
"allow_backorder": true,
"compare_at_price": "30.00",
"cost": "30.00",
"grams": 0,
"image_url": "your_platform_connector.com/files/products/hats/purple-beach-hat.jpg",
"inventory_quantity": 0,
"inventory_tracking_entity": "variant",
"inventory_tracking_service": "platform",
"localized_names": {"en": "Purple",
"fr": "Violette"
},
"name": "Default Title",
"price": "30.00",
"require_shipping": true,
"sku": "BEACH-HAT-PURPLE",
"tax_code": "non-taxable",
"tax_exempt": true,
"weight": "1.0",
"weight_unit": "kg"
}
],
"options": [{"platform_id": "product-option-123456",
"option_values": [{"platform_id": "option-value-123456",
"is_default": true,
"label": "Small",
"position": 1
}
],
"name": "Small",
"position": 1
}
],
"images": [{"platform_id": "image-123456",
"name": "Beach hat",
"src": "https://example.com/images/beach-hat.jpg",
"position": 1
}
],
"description": "A hat for the beach",
"handle": "beach-hat",
"inventory_quantity": 2,
"inventory_tracking_entity": "product",
"inventory_tracking_service": "platform",
"localized_descriptions": {"en": "A hat for the beach",
"fr": "Un chapeau pour la plage"
},
"localized_names": {"en": "Beach Hat",
"fr": "Chapeau de Plage"
},
"name": "Beach hat",
"published": true,
"tags": "clothing, unisex, headwear",
"tax_code": "non-taxable",
"type": "physical",
"url": "/hats/beach-hat",
"vendor": "OFS"
}
}
}

Response samples

202
400
500

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:

OAuthTokenAPIAccessToken

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

Payload

Content type

application/json

{"data": {"product": {"platform_id": "product-123456",
"platform_deleted_at": "2020-08-24T14:15:22Z"
}
}
}

Response samples

202
400
500

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:

OAuthTokenAPIAccessToken

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

Payload

Content type

application/json

{"data": {"category": {"platform_id": "category-123456",
"platform_updated_at": "2019-08-24T14:15:22Z",
"image_url": "your_platform_connector.com/files/categories/hats.jpg",
"name": "Hats"
}
}
}

Response samples

202
400
500

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:

OAuthTokenAPIAccessToken

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

Payload

Content type

application/json

{"data": {"category": {"platform_id": "category-123456",
"platform_deleted_at": "2019-09-24T14:15:22Z"
}
}
}

Response samples

202
400
500

Content type

application/json

{ }

Platform Connector: Event Notifications (1.0.0)

Customer Event Notifications

Customer Saved

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Customer Deleted

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Order Event Notifications

Order Saved

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Order Deleted

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Product Event Notifications

Product Saved

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Product Deleted

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Product Category Saved

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Product Category Deleted

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required