Skip to main content
Documentation Powered by Redocly

Platform Connector: Event Notifications (1.0.0)

Download OpenAPI specification:Download

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

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

bearerAuth

The API access token created in Bold Account Center.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Customer Event Notifications

These are event notifications that are sent 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:
bearerAuth
    path Parameters
    shop_identifier
    required
    string

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

    Request Body schema: application/json
    object (customerSavedRequestData)
    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
    string <date-time>

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

    platform_id
    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:
    bearerAuth
      path Parameters
      shop_identifier
      required
      string

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

      Request Body schema: application/json
      object (customerDeletedRequestData)
      object (deletedCustomer)
      platform_id
      string

      Unique identifier for the customer. Assigned by the platform.

      platform_deleted_at
      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

      These are event notifications that are sent to Bold when a change occurs to orders on the platform.

      Order Saved

      Trigger this API call when the order data has been modified on the platform, including if an order is created or updated.

      Bold then queues the order — in the case of an update, identified in the request body by the platform_id — for saving. The request should contain the complete order object at the time the change occurred. The platform_updated_at field must be accurate to mitigate the risk incurred by out-of-sequence requests.

      Authorizations:
      bearerAuth
        path Parameters
        shop_identifier
        required
        string

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

        Request Body schema: application/json
        object (orderSavedRequestData)
        object (order)
        platform_id
        string

        Unique identifier for the order. Assigned by the platform.

        platform_updated_at
        string <date-time>

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

        Array of objects (address) [ items ]

        List of shipping addresses for the order.

        object

        Billing address for the order.

        Array of objects (lineItem) [ items ]

        List of line items included in the order.

        Array of objects (payment) [ items ]

        List of payments for the order.

        order_number
        string

        Human-readable identifier for the order.

        platform_customer_id
        string

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

        shipping_method
        string

        Method of shipping for the order.

        browser_ip
        string

        Browser IP under which the order was placed by the customer.

        source
        string

        Label noting the mechanism which placed this order.

        created_via
        string

        Label noting which app created the order (if applicable).

        locale
        string

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

        test
        boolean

        Indicator of whether this is a test order.

        notes
        string

        Internal notes about the order.

        public_notes
        string

        Customer-facing notes about the order.

        object

        Key-value pairs of metadata relevant to the order.

        shipping_subtotal
        required
        string <money>

        Cost of the shipping for the ordered items, in the order's given currency.

        shipping_tax
        required
        string <money>

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

        Array of objects (tax) [ items ]

        List of all individual shipping taxes for each line item on the order.

        discount
        string <money>

        Total amount discounted from this order, in the order's given currency.

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

        subtotal
        required
        string <money>

        Subtotal of all line items on the order, in the order's given currency.

        Note: Subtotals should be calculated before taxes and discounts (if those values are not included in the line item prices).

        subtotal_tax
        required
        string <money>

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

        total_tax
        required
        string <money>

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

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

        Note: Includes taxes and reduced by discount.

        refunded_amount
        string <money>

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

        currency
        string

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

        order_status
        string
        Enum: "active" "cancelled"

        Current status of the order. Indicates whether the order has been cancelled.

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

        Fulfillment status of the order.

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

        Status of payments associated with the order. This field can only be set when the order is created.

        placed_at
        string <date-time>

        Date (in RFC3339 format) that this order was placed on the platform. 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 then queues the order - 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:
        bearerAuth
          path Parameters
          shop_identifier
          required
          string

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

          Request Body schema: application/json
          object (orderDeletedRequestData)
          object (deletedOrder)
          platform_id
          string

          Unique identifier for the order. Assigned by the platform.

          platform_deleted_at
          string <date-time>

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

          Responses

          Request samples

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

          Response samples

          Content type
          application/json
          { }

          Product Event Notifications

          These are event notifications that are sent to Bold when a change occurs to products on the platform.

          Product Saved

          Trigger this API call when product data changes. This includes product creation and updates.

          Bold then queues the product — in the case of an update, identified in the request body by the platform_id — for saving. The request contains 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. Fields omitted from the request body are ignored in the Product object. The platform_updated_at field must be accurate to mitigate the risk incurred by out-of-sequence requests.

          Authorizations:
          bearerAuth
            path Parameters
            shop_identifier
            required
            string

            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

            Unique identifier for the product. Defined by the platform.

            platform_updated_at
            required
            string <date-time>

            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 ]
            Array of objects (deepImage) [ items ]
            description
            string

            Description for the product.

            handle
            string

            A unique, human-readable string for the product.

            inventory_quantity
            integer <int64>

            Current inventory level of the product.

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

            The entity on which inventory is tracked.

            inventory_tracking_service
            string

            Service that tracks inventory.

            object

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

            object

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

            name
            string

            Product name.

            published
            boolean <boolean>

            Indicates if the product is published on the storefront.

            tags
            string

            String with comma separated values.

            tax_code
            string

            Tax code for the product.

            type
            string

            Product type. Used for searching.

            url
            string

            URL to the product on the storefront.

            vendor
            string

            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 then queues the product — 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:
            bearerAuth
              path Parameters
              shop_identifier
              required
              string

              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

              Platform ID of the product

              platform_deleted_at
              required
              string <date-time>

              Date this product was deleted on 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 then queues the product category — identified in the request body by the platform_id — 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:
              bearerAuth
                path Parameters
                shop_identifier
                required
                string

                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

                Unique identifier for the category. Defined by the platform.

                platform_updated_at
                required
                string <date-time>

                Date the category was last updated on the platform.

                image_url
                string

                Specifies the URL location of the category image.

                name
                string

                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 then queues the product category — 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:
                bearerAuth
                  path Parameters
                  shop_identifier
                  required
                  string

                  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

                  Platform ID of the category

                  platform_deleted_at
                  required
                  string <date-time>

                  Date this category was deleted on the platform

                  Responses

                  Request samples

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

                  Response samples

                  Content type
                  application/json
                  { }