openapi: 3.0.0 info: title: Platform Connector API Specification description: |- The Platform Connector API allows Bold to interact with your platform's customers, orders, and products. This specification file defines the expected server behavior of the Platform Connector Server. Bold applications require the endpoints listed here to be implemented in order to function properly. Refer to the changelog for the latest updates to this API. > **Note:** This specification is only for use with a [Bold Platform Connector](/guides/platform-connector). termsOfService: https://boldcommerce.com/terms-of-service contact: name: Contact Us url: https://developer-dashboard.boldcommerce.com/default/contactus version: 1.0.0 servers: - url: https://your-platform-connector.example security: - HMAC: [] tags: - name: Verification description: Use these endpoints to verify your platform connector destination. - name: Customers description: Contains information about a customer, including name, contact info, and addresses. Bold calls these endpoints to manage customers on your platform. - name: Addresses description: A child of the Customer resource. Contains information about a billing or shipping address associated with a given customer. Bold calls these endpoints to manage addresses on your platform. - name: Orders description: Contains information about an order, including addresses, line items, payments, and additional order details. Bold calls these endpoints to manage orders on your platform. - name: Products description: Contains information about a product, including names, descriptions, applicable options and variants, and other details. Bold calls these endpoints to retrieve information about the products on your platform. - name: Categories description: Contains information about product categories, including names, image, and platform information. Bold calls these endpoints to retrieve information about the categories on your platform. externalDocs: description: For more information about Platform Connectors, refer to the Overview. url: https://developer.boldcommerce.com/guides/platform-connector paths: /v1/shops/{shop_identifier}/verification: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' get: tags: - Verification summary: Verify Platform Connector Destination operationId: VerifyPlatformConnectorDestination description: |- Confirms that you own a given Platform Connector destination. Bold calls this endpoint on your Platform Connector when you attempt to [Create](/api/platform-connector-destinations#operation/CreateDestination) or [Update](/api/platform-connector-destinations#operation/UpdateDestination) a destination. Responds with a calculated X-HMAC header containing the content of the sent X-HMAC-Timestamp header encoded with the shared secret. responses: '200': description: Response indicating successful calculation of the included X-HMAC header. headers: X-HMAC: schema: type: string description: |- An HMAC signature calculated from the current shared secret (created in the Bold Account Center) and the value of the X-HMAC-Timestamp header. Bold verifies this signature before registering your platform connector destinations. For more information about verifying this signature, refer to [Implement Platform Connector APIs](/guides/platform-connector/create-server#verify-the-signature). content: application/json: schema: $ref: '#/components/schemas/verifyPlatformConnectorDestinationBody' /v1/shops/{shop_identifier}/customers: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' post: tags: - Customers summary: Create Customer operationId: CreateCustomer description: |- Create a customer in your platform. The request body contains a complete customer entity, you must persistently store on your platform. A successful response contains the same customer, with its associated `platform_id` and timestamps populated. The `platform_id` is unique, because Bold applications use it to identify the customer and its fields. The returned `platform_id` can be used in requests to other endpoints in this API. requestBody: content: application/json: schema: $ref: '#/components/schemas/createCustomerRequestBody' required: true responses: '201': description: Returned upon successful creation of the customer. content: application/json: schema: $ref: '#/components/schemas/customerResponseBody' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: internalError: $ref: '#/components/examples/internalError' get: tags: - Customers summary: List Customers operationId: ListCustomers description: |- List customers that have made a purchase from your store. Include the `email` parameter to retrieve a certain customer. Returns a page of customers for your store, with `limit` as the maximum number of results and paginated by `cursor`. Return customers in ascending order of `platform_id`. If the request does not supply a limit (or supplies an invalid one), then use the default limit (250). Each `cursor` points to a location in the dataset. Cursors can be supplied to subsequent calls for additional data in the dataset. If no `cursor` is applied, return the first page of results. parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/cursor' - name: email in: query description: An email used to filter the results. schema: type: string example: john.doe@example.com responses: '200': description: Response containing a list of customers when a successful request is made. content: application/json: schema: $ref: '#/components/schemas/listCustomersResponseBody' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: internalError: $ref: '#/components/examples/internalError' /v1/shops/{shop_identifier}/customers/{platform_id}: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/customerId' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' patch: tags: - Customers summary: Update Customer operationId: UpdateCustomer description: |- Update a customer specified by `platform_id`. Replace all fields of the customer object with the values provided in the request body. Ignore and do not update any fields omitted from the request body. requestBody: content: application/json: schema: $ref: '#/components/schemas/updateCustomerRequestBody' required: true responses: '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/customerResponseBody' '404': description: The customer specified by `platform_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: customerNotFound: $ref: '#/components/examples/customerNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: internalError: $ref: '#/components/examples/internalError' delete: tags: - Customers summary: Delete Customer operationId: DeleteCustomer description: Delete a customer specified by `platform_id`. Mark the customer as deleted within the platform. responses: '204': description: Returned upon successful deletion of the customer. content: application/json: schema: type: object '404': description: The customer specified by `platform_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: customerNotFound: $ref: '#/components/examples/customerNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: internalError: $ref: '#/components/examples/internalError' /v1/shops/{shop_identifier}/customers/{platform_id}/validate: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/customerId' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' post: tags: - Customers summary: Validate Customer JWT operationId: ValidateCustomerJWT description: Validate the JWT to determine if it is a valid token and corresponds to the provided customer. The JWT is used to authorize the frontend code to perform various actions on behalf of the customer. For more information, refer to the [Initialize Order](orders#tag/Orders/operation/InitializeOrder) endpoint. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/customerValidateRequestBody' responses: '200': description: Token information. content: application/json: schema: $ref: '#/components/schemas/customerValidateResponseBody' '404': description: The customer specified by `platform_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: customerNotFound: $ref: '#/components/examples/customerNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: internalError: $ref: '#/components/examples/internalError' /v1/shops/{shop_identifier}/customers/{platform_customer_id}/addresses: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/platformCustomerId' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' post: tags: - Addresses summary: Create Address operationId: CreateAddress description: |- Create an address for a customer, specified by `platform_customer_id`. The request body contains a complete address entity, which you must persistently store on the platform. A successful response contains the same address, including its associated `platform_id` and `platform_customer_id`. These IDs must be unique among addresses, because Bold applications use them to identify the address for the customer. Bold can use the returned `platform_id` to make requests to other address endpoints in this API. requestBody: content: application/json: schema: $ref: '#/components/schemas/createAddressRequestBody' required: true responses: '201': description: Returned upon successful creation of the address. content: application/json: schema: $ref: '#/components/schemas/addressResponseBody' '404': description: The customer specified by `platform_customer_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: customerNotFound: $ref: '#/components/examples/customerNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: internalError: $ref: '#/components/examples/internalError' patch: tags: - Addresses summary: Update Address operationId: UpdateAddress description: |- Update an address. Bold indicates the address by the `platform_id` and the customer by the `platform_customer_id`. Replace all fields of an address object with the values provided in the request body. Ignore and do not change any fields omitted from the request body. requestBody: content: application/json: schema: $ref: '#/components/schemas/updateAddressRequestBody' required: true responses: '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/addressResponseBody' '404': description: The customer specified by `platform_customer_id` or the address specified by `platform_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: customerNotFound: $ref: '#/components/examples/customerNotFound' addressNotFound: $ref: '#/components/examples/addressNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: internalError: $ref: '#/components/examples/internalError' /v1/shops/{shop_identifier}/customers/{platform_customer_id}/addresses/{platform_id}: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/platformCustomerId' - $ref: '#/components/parameters/addressId' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' delete: tags: - Addresses summary: Delete Address operationId: DeleteAddress description: Delete an address. Bold indicates the address by the `platform_id` and the customer by the `platform_customer_id`. Mark the address as deleted on the platform. responses: '204': description: Returned upon successful deletion of the address. content: application/json: schema: type: object '404': description: The customer specified by `platform_customer_id` or the address specified by `platform_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: customerNotFound: $ref: '#/components/examples/customerNotFound' addressNotFound: $ref: '#/components/examples/addressNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorCustomer' examples: internalError: $ref: '#/components/examples/internalError' /v1/shops/{shop_identifier}/orders: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' post: tags: - Orders summary: Create Order operationId: CreateOrder description: |- Create an order on the platform. The request body contains a complete order entity, which you must persistently store on your platform. A successful response contains the same order, with its associated `platform_id` and timestamps populated. The `platform_id` is unique, because Bold applications use it to identify the order and its fields. Bold uses the returned `platform_id` to make requests to other endpoints in this API. parameters: - $ref: '#/components/parameters/idempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/createOrderRequestBody' required: true responses: '201': description: Returned upon successful creation of the order. content: application/json: schema: $ref: '#/components/schemas/orderResponseBody' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: internalError: $ref: '#/components/examples/internalError' get: tags: - Orders summary: List Orders operationId: ListOrders description: |- List all orders made on a store. Return a page of orders from your store, with `limit` as the maximum number of results and paginated by `cursor`. Return orders in ascending order of `platform_id`. If the request does not supply a limit (or supplies an invalid one), then use the default limit (250). Each `cursor` points to a location in the dataset. Cursors can be supplied to subsequent calls for additional data in the dataset. If no `cursor` is supplied, return the first page of results. parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/cursor' responses: '200': description: A successful response content: application/json: schema: $ref: '#/components/schemas/listOrdersResponseBody' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: internalError: $ref: '#/components/examples/internalError' /v1/shops/{shop_identifier}/orders/{platform_id}: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/orderId' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' get: tags: - Orders summary: Get Order operationId: GetOrder description: Retrieve an order placed on your store by the specified `platform_id`. responses: '200': description: Response containing the specified order. content: application/json: schema: $ref: '#/components/schemas/orderResponseBody' '404': description: The order specified by `platform_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: orderNotFound: $ref: '#/components/examples/orderNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: internalError: $ref: '#/components/examples/internalError' patch: tags: - Orders summary: Update Order operationId: UpdateOrder description: |- Update an order specified by `platform_id`. Replace all fields of the order object with the values provided in the request body. Ignore and do not update any fields omitted from the request body. requestBody: content: application/json: schema: $ref: '#/components/schemas/updateOrderRequestBody' required: true responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/orderResponseBody' '404': description: The order specified by `platform_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: orderNotFound: $ref: '#/components/examples/orderNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: internalError: $ref: '#/components/examples/internalError' /v1/shops/{shop_identifier}/orders/{platform_id}/payments: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/orderId' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' post: tags: - Orders summary: Create Payment operationId: CreatePayment description: |- Create a payment associated with a given order. The request body contains a complete order entity, which you must persistently store on your platform. A successful response contains the same payment, with its associated `platform_id` and timestamps populated. The `platform_id` must be unique, because Bold applications use it to identify the payment and its fields. The returned `platform_id` can be used in requests to other endpoints in this API. requestBody: content: application/json: schema: $ref: '#/components/schemas/createPaymentRequestBody' required: true responses: '201': description: Returned upon successful creation of the payment. content: application/json: schema: $ref: '#/components/schemas/paymentResponseBody' '404': description: The order specified by `platform_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: orderNotFound: $ref: '#/components/examples/orderNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: internalError: $ref: '#/components/examples/internalError' /v1/shops/{shop_identifier}/orders/{order_platform_id}/payments/{platform_id}: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/orderPlatformId' - $ref: '#/components/parameters/paymentId' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/userAgent' patch: tags: - Orders summary: Update Payment operationId: UpdatePayment description: |- Update a payment associated with a specific order. Specify the payment by `platform_id` and the order by `order_platform_id`. Replace all fields of the payment object with the values provided in the request body. Ignore and do not update any fields omitted from the request body. requestBody: content: application/json: schema: $ref: '#/components/schemas/updatePaymentRequestBody' required: true responses: '200': description: Returned upon successful updating of the payment. content: application/json: schema: $ref: '#/components/schemas/paymentResponseBody' '404': description: The payment specified by `platform_id` was not found. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: orderNotFound: $ref: '#/components/examples/orderNotFound' paymentNotFound: $ref: '#/components/examples/paymentNotFound' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorOrder' examples: internalError: $ref: '#/components/examples/internalError' /v1/shops/{shop_identifier}/products: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/userAgent' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/cursor' get: tags: - Products summary: List Products operationId: ListProducts description: |- List all products that exist in your store. Return a page of products for your store, with `limit` as the maximum number of results and paginated by `cursor`. Return products in ascending order of `platform_id`. If the request does not supply a limit (or supplies an invalid one), use the default limit (250). Each `cursor` points to a location in the dataset. Cursors can be supplied to subsequent calls for additional data in the dataset. If no `cursor` is supplied, return the first page of results. responses: '200': description: Response containing a list of products when a successful request is made. content: application/json: schema: $ref: '#/components/schemas/listProductsResponseBody' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorProduct' /v1/shops/{shop_identifier}/categories: parameters: - $ref: '#/components/parameters/shopIdentifier' - $ref: '#/components/parameters/userAgent' - $ref: '#/components/parameters/timestamp' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/cursor' get: tags: - Categories summary: List Categories operationId: ListCategories description: |- Lists all product categories in a given store. Return a page of product categories for your store, with `limit` as the maximum number of results and paginated by `cursor`. Return categories in ascending order of `platform_id`. If the request does not supply a limit (or supplies an invalid one), use the default limit (250). Each cursor points to a location in the dataset. Cursors can be supplied to subsequent calls for additional data in the dataset. If no `cursor` is supplied, return the first page of results. responses: '200': description: Response containing a list of categories when a successful request is made. content: application/json: schema: $ref: '#/components/schemas/listCategoriesResponseBody' '500': description: An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/runtimeErrorProduct' components: securitySchemes: HMAC: type: apiKey name: X-HMAC in: header description: |- An HMAC signature calculated from the current shared secret (created in Bold Account Center) and the value of the X-HMAC-Timestamp header. For more information about verifying this signature, refer to [Implement Platform Connector APIs](/guides/platform-connector/create-server#verify-the-signature). schemas: verifyPlatformConnectorDestinationBody: type: object customer: type: object allOf: - $ref: '#/components/schemas/customerBase' properties: addresses: description: A list of customer addresses. type: array items: $ref: '#/components/schemas/customerAddress' platform_created_at: description: The date (in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) that this customer was created on the platform. Assigned by the platform. type: string format: date-time example: '2021-03-11T17:16:51Z' platform_updated_at: description: The date this customer was last modified on the platform, (in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339)). Assigned by the platform. type: string format: date-time example: '2021-03-11T17:16:51Z' platform_id: description: A unique identifier for the customer. Assigned by the platform. type: string example: customer-123456 customerBase: type: object properties: email: description: The email address for the customer. type: string format: email example: john.doe@example.com first_name: description: The first name of the customer. type: string example: John last_name: description: The last name of the customer. type: string example: Doe phone: description: The phone number for the customer. type: string format: phone example: 555-555-5555 customerNew: type: object allOf: - $ref: '#/components/schemas/customerBase' - required: - email properties: addresses: description: A list of customer addresses. type: array items: $ref: '#/components/schemas/addressNew' customerUpdate: type: object allOf: - $ref: '#/components/schemas/customerBase' properties: addresses: description: A list of customer addresses. type: array items: $ref: '#/components/schemas/addressNew' address: type: object allOf: - $ref: '#/components/schemas/addressBaseOrder' properties: platform_id: description: Unique identifier for the address. Assigned by the platform. type: string example: address-123456 platform_customer_id: description: Unique identifier for the customer. Assigned by the platform. type: string example: customer-123456 addressBaseCustomer: type: object properties: address_type: description: The type of the address (i.e., residential, commercial). type: string example: commercial address_use: description: The usage of the address. Possible values are `"billing"` or `"shipping"`. type: string enum: - billing - shipping example: billing company: description: The name of the company operating at the specified address, if applicable. type: string example: Acme Corp. city: description: The name of the city associated with the address. type: string example: Winnipeg country: description: The name of the country associated with the address. type: string example: Canada country_code: description: The country code (in [ISO 3166-1 alpha-2 format](https://www.iso.org/iso-3166-country-codes.html)) of the address. type: string example: CA is_default: description: Indicates whether this is the default address for the customer. There can only be one default address for a customer. If this modifies any other resources, ensure the [appropriate event notifications](platform-event-notifications#tag/Customer-Event-Notifications/operation/CustomerSavedEventNotification) are triggered for those affected by this change. type: boolean format: boolean example: true first_name: description: The first name of the customer with the address. type: string example: John last_name: description: The last name of the customer with the address. type: string example: Doe phone: description: The phone number of the address. type: string format: phone example: 555-555-5555 postal_code: description: The postal code or zip code for the address. type: string example: H0H 0H0 province: description: The province or state for the address. type: string example: Manitoba province_code: description: The province or state abbreviation for the address. type: string example: MB street_1: description: The primary street information for the address. type: string example: 123 North Road street_2: description: Any additional street information for the address. type: string example: '' addressNew: type: object allOf: - $ref: '#/components/schemas/addressBaseCustomer' customerAddress: type: object allOf: - $ref: '#/components/schemas/addressBaseCustomer' properties: platform_id: description: A unique identifier for the address. Assigned by the platform. type: string example: address-123456 createCustomerRequestBody: type: object properties: data: $ref: '#/components/schemas/createCustomerRequestData' createCustomerRequestData: type: object properties: customer: $ref: '#/components/schemas/customerNew' updateCustomerRequestBody: type: object properties: data: $ref: '#/components/schemas/updateCustomerRequestData' updateCustomerRequestData: type: object properties: customer: $ref: '#/components/schemas/customerUpdate' customerResponseBody: type: object properties: data: $ref: '#/components/schemas/customerResponseData' customerResponseData: type: object properties: customer: $ref: '#/components/schemas/customer' createAddressRequestBody: type: object properties: data: $ref: '#/components/schemas/createAddressRequestData' createAddressRequestData: type: object properties: address: $ref: '#/components/schemas/addressNew' updateAddressRequestBody: type: object properties: data: $ref: '#/components/schemas/updateAddressRequestData' updateAddressRequestData: type: object properties: address: $ref: '#/components/schemas/addressNew' addressResponseBody: type: object properties: data: $ref: '#/components/schemas/addressResponseData' addressResponseData: type: object properties: address: $ref: '#/components/schemas/address' runtimeErrorCustomer: type: object properties: errors: type: array items: type: object properties: code: type: string description: A code used to identify the error. message: type: string description: A long description of the error. type: type: string description: A short description of the error. customerValidateRequestBody: type: object properties: data: $ref: '#/components/schemas/customerValidateRequestData' customerValidateRequestData: type: object properties: token_info: $ref: '#/components/schemas/tokenInfo' tokenInfo: type: object required: - token properties: token: type: string description: The token to inspect. example: 98qf34jwe0rwfhjqop4wa98af customerValidateResponseBody: type: object properties: data: $ref: '#/components/schemas/customerValidateResponseData' customerValidateResponseData: type: object properties: token_status: $ref: '#/components/schemas/tokenStatus' listCustomersResponseBody: type: object properties: data: $ref: '#/components/schemas/listCustomersResponseData' pagination: $ref: '#/components/schemas/paginationResponse' listCustomersResponseData: type: object properties: customers: type: array items: $ref: '#/components/schemas/customer' tokenStatus: type: object required: - active properties: active: type: boolean description: Indicates whether the presented token is active and belongs to the provided `customer_platform_id`. createOrderRequestBody: type: object properties: data: $ref: '#/components/schemas/createOrderRequestData' createOrderRequestData: type: object properties: order: $ref: '#/components/schemas/orderRequest' updateOrderRequestBody: type: object properties: data: $ref: '#/components/schemas/updateOrderRequestData' updateOrderRequestData: type: object properties: order: $ref: '#/components/schemas/orderUpdateRequest' createPaymentRequestBody: type: object properties: data: $ref: '#/components/schemas/createPaymentRequestData' createPaymentRequestData: type: object properties: payment: $ref: '#/components/schemas/paymentRequest' updatePaymentRequestBody: type: object properties: data: $ref: '#/components/schemas/updatePaymentRequestData' updatePaymentRequestData: type: object properties: payment: $ref: '#/components/schemas/updatePaymentRequest' orderResponseBody: type: object properties: data: $ref: '#/components/schemas/orderResponseData' orderResponseData: type: object properties: order: $ref: '#/components/schemas/order' listOrdersResponseBody: type: object properties: data: $ref: '#/components/schemas/listOrdersResponseData' pagination: $ref: '#/components/schemas/paginationResponse' listOrdersResponseData: type: object properties: orders: type: array items: $ref: '#/components/schemas/order' paymentResponseBody: type: object properties: data: $ref: '#/components/schemas/paymentResponseData' paymentResponseData: type: object properties: payment: $ref: '#/components/schemas/payment' orderRequest: type: object allOf: - $ref: '#/components/schemas/orderBase' properties: shipping_addresses: description: A list of shipping addresses for the order. type: array items: $ref: '#/components/schemas/addressRequest' billing_address: description: The billing address for the order. allOf: - $ref: '#/components/schemas/addressRequest' line_items: description: A list of line items for the order. type: array items: $ref: '#/components/schemas/lineItemRequest' payments: description: A list of payments for this order. type: array items: $ref: '#/components/schemas/paymentRequest' orderUpdateRequest: type: object properties: fulfillment_status: description: The fulfillment status of each line item on the order. type: string enum: - pending - partial - delivered - fulfilled example: partial financial_status: description: 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. type: string enum: - held_for_review - disputed - cancelled - pending - preauthed - refunded - partially_paid - partially_refunded - paid example: pending refunded_amount: description: The total refunded amount, if any, applied to the order. Measured in units of the order currency. type: string format: double example: '0' notes: description: Any internal notes about the order. type: string example: Handle with care. custom_attributes: description: A series of key-value pairs of additional metadata relevant to the order. type: object additionalProperties: $ref: '#/components/schemas/customAttribute' shipping_addresses: description: List of shipping addresses for the order. type: array items: $ref: '#/components/schemas/addressRequest' subtotal: description: | 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). type: string format: double subtotal_tax: description: The tax to be charged on all line items, in the order's given currency. type: string format: double example: '0.7' order: type: object allOf: - $ref: '#/components/schemas/orderBase' properties: platform_id: description: A unique identifier for the order. Assigned by the platform. type: string example: order-123456 platform_updated_at: description: The date this order was last modified on the platform, in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339). Assigned by the platform. type: string format: date-time example: '2019-08-24T14:15:22Z' shipping_addresses: description: A list of shipping addresses for the order. type: array items: $ref: '#/components/schemas/addressOrder' billing_address: description: The billing address for the order. allOf: - $ref: '#/components/schemas/addressOrder' line_items: description: A list of line items included in the order. type: array items: $ref: '#/components/schemas/lineItem' payments: description: A list of payments for the order. type: array items: $ref: '#/components/schemas/payment' placed_at: description: The date this order was placed on the platform, in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339). Assigned by the platform. type: string format: date-time example: '2019-08-24T14:15:22Z' required: - total - total_tax - subtotal - subtotal_tax - shipping_subtotal - shipping_tax orderBase: type: object properties: order_number: description: A human-readable identifier for the order. type: string example: ORDER_XXYY1122 platform_customer_id: description: A unique identifier for the customer associated to this order. Assigned by the platform. type: string example: customer-123456 platform_friendly_id: description: 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. type: string example: PT-0065 shipping_method: description: The shipping method for the order. type: string example: freight shipping_code: description: The shipping method code for the order. Each store defines its own shipping codes. type: string example: S001 browser_ip: description: The browser IP under which the order was placed by the customer. type: string example: 127.0.0.1 source: description: A label noting the mechanism which placed this order. type: string example: POS created_via: description: A label noting which app created the order (if applicable). type: string example: Bold Checkout locale: description: The locale code of the order (either in [ISO-639 language code format](https://www.iso.org/iso-639-language-codes.html) or in [ISO/IEC-15897 regional language format](https://www.iso.org/standard/50707.html)). type: string example: en_US test: description: Indicates whether this is a test order. type: boolean example: false notes: description: Any internal notes about the order. type: string example: High priority public_notes: description: Any customer-facing notes about the order. type: string example: Handle with care. custom_attributes: description: Any key-value pairs of metadata relevant to the order. type: object additionalProperties: $ref: '#/components/schemas/customAttribute' shipping_subtotal: description: The shipping cost for the ordered items, in the order's given currency. Calculated before taxes. type: string format: double example: '5.00' shipping_tax: description: The sum of all shipping taxes for the ordered items, in the order's given currency. type: string format: double example: '1.00' shipping_taxes: description: A list of individual shipping taxes for each line item on the order. type: array items: $ref: '#/components/schemas/tax' discount: description: |- 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. type: string format: double example: '0' discounts: description: The list of discounts applied to the order. type: object additionalProperties: $ref: '#/components/schemas/orderDiscount' subtotal: description: |- 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). type: string format: double example: '10.00' subtotal_tax: description: The tax to be charged on all line items, in the order's given currency. type: string format: double example: '0.7' total_tax: description: '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.' type: string format: double example: '0.7' total: description: |- The total order cost, in the order's given currency. **Note:** This number includes taxes and is reduced by the discount. type: string format: double example: '16.07' refunded_amount: description: The refunded amount of the order, if any, in the order's given currency. type: string format: double example: '0' currency: description: The base currency used for the order (in [ISO-4217 currency code format](https://www.iso.org/iso-4217-currency-codes.html)). type: string example: CAD order_status: description: The current status of the order. Indicates whether the order is `active` or has been `cancelled`. type: string enum: - active - cancelled example: active fulfillment_status: description: The fulfillment status of the order. type: string enum: - pending - partial - delivered - fulfilled example: fulfilled financial_status: description: 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. type: string enum: - held_for_review - disputed - cancelled - pending - preauthed - refunded - partially_paid - partially_refunded - paid example: pending lineItem: type: object allOf: - $ref: '#/components/schemas/lineItemBase' properties: platform_id: description: Unique identifier for the line item. Assigned by the platform. type: string example: line-item-123456 lineItemRequest: type: object allOf: - $ref: '#/components/schemas/lineItemBase' lineItemBase: type: object properties: platform_product_id: description: Unique identifier for the product referenced in this line item. Assigned by the platform. type: string example: product-123456 platform_variant_id: description: Unique identifier for the variant referenced in this line item. Assigned by the platform. type: string example: variant-123456 cart_line_item_platform_id: description: Unique identifier for the cart line item. Assigned by the platform. type: string example: cart-line-item-123456 custom_attributes: description: Key-value pairs of metadata relevant to the line item. type: object additionalProperties: $ref: '#/components/schemas/customAttribute' title: description: Title of the line item. type: string example: Shoes (long-laced classic) sku: description: SKU of the line item. type: string url: description: Link to the line item in the store. type: string image: description: Image of the line item. type: string quantity: description: Quantity ordered for this line item. type: integer format: int64 grams: description: Weight in grams of the line item. type: number format: double weight: description: Weight of the line item (measured in terms of `weight_unit`). type: number format: double weight_unit: description: Unit which weight is measured in. type: string taxable: description: Indicator of whether the line item is taxable. type: boolean taxes: description: List of taxes for the line item. type: array items: $ref: '#/components/schemas/tax' requires_shipping: description: Indicator of whether the line item requires shipping. type: boolean price_per_item: description: | Price per unit of the line item, in the order's given currency. **Note**: This price should be calculated before taxes and discounts (if taxes are not included in price). type: string format: double discount_per_item: description: Discount of the line item, in the order's given currency. type: string format: double total: description: | Grand total price of the line item, in the order's given currency. **Note**: This price includes taxes and discounts. type: string format: double subtotal: description: | Total price of the line item, measured in the order's currency. **Note**: This value is calculated using price multiplied by quantity, excluding tax. type: string format: double total_tax: description: Total tax of the line item, in the order's given currency. type: string format: double example: '0.7' discounted_subtotal: description: | Discounted total price of the line item, in the order's given currency. **Note**: This value is calculated using discounted price multiplied by quantity, excluding tax. type: string format: double tax: type: object properties: amount: description: Total tax amount pending, measured in the order's given currency. type: string format: double example: '0.7' name: description: Human-readable name for this tax. type: string example: Provincial Sales Tax rate: description: Percent tax (value between 0 to 1) type: string example: '0.07' tag: description: Reference tag for the tax type: string example: PST orderDiscount: type: object properties: platform_id: type: string description: A unique identifier for the discount. Defined by the platform. example: discount-123456 amount: description: The discounted amount applied to the order, measured in the order's given currency. type: string format: double example: '5.00' discount_code: type: string description: The code used to apply the discount. example: 20OFF paymentRequest: type: object allOf: - $ref: '#/components/schemas/paymentBase' properties: transactions: description: A list of transactions for the payment. Multiple transactions can be associated with a single payment type: array items: $ref: '#/components/schemas/transactionRequest' description: description: A human-readable description of the payment. type: string example: credit_card provider: description: A label indicating the organization handling the payment and transactions. type: string example: stripe payment_method: description: The payment method used. type: string example: credit card currency: description: The currency used for the payment, in [ISO-4217 currency code format](https://www.iso.org/iso-4217-currency-codes.html). type: string example: CAD amount_planned: description: The amount that the payment provider plans to charge for the payment, in the payment's given currency. If the payment has been completed, this amount reflects the amount charged. This value typically matches the order `total`. type: string format: double example: '16.07' custom_attributes: description: A series of key-value pairs of metadata relevant to the payment. type: object additionalProperties: $ref: '#/components/schemas/customAttribute' updatePaymentRequest: type: object allOf: - $ref: '#/components/schemas/paymentBase' properties: transactions: description: A list of transactions for the payment. type: array items: $ref: '#/components/schemas/transactionRequest' payment: type: object allOf: - $ref: '#/components/schemas/paymentBase' properties: platform_id: description: A unique identifier for the payment. Assigned by the platform. type: string example: payment-123456 transactions: description: A list of transactions for the payment. type: array items: $ref: '#/components/schemas/transaction' description: description: A human-readable description of the payment. type: string example: Credit card payment provider: description: The organization handling the payment and transactions. type: string example: stripe payment_method: description: The payment method used. type: string example: credit card currency: description: The currency used for the payment, in [ISO-4217 currency code format](https://www.iso.org/iso-4217-currency-codes.html). type: string example: CAD amount_planned: description: The amount that the payment provider plans to charge for the payment, in the payment's given currency. If the payment has been completed, this amount reflects the amount charged. This value typically matches the order `total`. type: string format: double example: '16.07' custom_attributes: description: A series of key-value pairs of metadata relevant to the payment. type: object additionalProperties: $ref: '#/components/schemas/customAttribute' paymentBase: type: object properties: status: description: The status of the payment. Values are dependent on the payment provider used and should be passed through as-is. type: string example: paid transaction: type: object allOf: - $ref: '#/components/schemas/transactionBase' properties: platform_id: description: A unique identifier for the transaction. Assigned by the platform. type: string example: transaction-123456 transactionRequest: type: object allOf: - $ref: '#/components/schemas/transactionBase' properties: platform_id: description: A unique identifier for the transaction. Assigned by the platform. type: string example: transaction-123456 transactionBase: type: object properties: provider_transaction_id: description: A unique identifier for the transaction. Assigned by the payment provider. type: string example: provider-transaction-123456 amount: description: |- The amount captured in this transaction, in the transaction's given currency. **Note:** If the transaction is a refund, this amount is negative. type: string currency: description: The currency used for the transaction (in [ISO-4217 currency code format](https://www.iso.org/iso-4217-currency-codes.html)). type: string example: CAD status: description: The status of the transaction. type: string enum: - initial - pending - failure - success example: pending type: description: The type of transaction. type: string enum: - authorization - charge - refund example: charge customAttribute: type: object properties: description: description: The description of the attribute. type: string example: key-1 value: description: The value of the attribute. type: string example: value-1 addressOrder: type: object allOf: - $ref: '#/components/schemas/addressBaseOrder' properties: platform_id: description: A unique identifier for the address. Assigned by the platform. type: string example: address-123456 addressRequest: type: object allOf: - $ref: '#/components/schemas/addressBaseOrder' addressBaseOrder: type: object properties: address_type: description: The usage of the address. Possible values are `"billing"` or `"shipping"`. type: string enum: - billing - shipping example: billing first_name: description: The addressee's first name. type: string example: John last_name: description: The addressee's last name. type: string example: Doe street_1: description: The primary street information. type: string example: 123 North Road street_2: description: Any additional street information. type: string example: Suite 200 city: description: The city name. type: string example: Winnipeg province: description: The name of the province or state. type: string example: Manitoba country: description: The country name. type: string example: Canada country_code: description: The country code of the address, in [ISO 3166-1 alpha-2 format](https://www.iso.org/iso-3166-country-codes.html). type: string example: CA phone: description: The phone number. type: string example: 555-555-5555 postal_code: description: The postal code or zip code. type: string example: H0H 0H0 email: description: An email address. type: string format: email example: john.doe@example.com province_code: description: The province or state abbreviation. type: string example: MB company: description: The name of the company operating at the specified address, if applicable. type: string example: Acme Corp. runtimeErrorOrder: type: object properties: errors: type: array items: required: - code type: object properties: code: type: string description: The error code. example: 09-1 message: type: string description: A message describing the error. example: The order with the provided platform_id does not exist type: type: string description: The type of error. example: orders.does_not_exist product: type: object allOf: - $ref: '#/components/schemas/productBase' properties: platform_id: type: string description: A unique identifier for the product. Defined by the platform. example: product-123456 platform_updated_at: description: The date the product was last updated on the platform. type: string format: date-time example: '2021-03-11T17:16:51Z' categories: type: array description: An array of product categories. items: $ref: '#/components/schemas/category' variants: type: array description: An array of `variant` objects. At least one variant is required. If the product has no variants, the variant can reuse the product information. items: $ref: '#/components/schemas/deepVariant' options: type: array description: An array of `option` objects. A more granular level of customization for variants. These are not required, but can be used to provide more options for your same variant. items: $ref: '#/components/schemas/deepOption' images: type: array description: An array of images associated with the products. items: $ref: '#/components/schemas/deepImage' productBase: type: object properties: description: type: string description: A description for the product. example: A hat for the beach handle: type: string description: A unique, human-readable string for the product. example: beach-hat inventory_quantity: type: integer description: The current inventory level of the product. format: int64 example: 4 inventory_tracking_entity: type: string description: The entity on which inventory is tracked. enum: - variant - product - none example: product inventory_tracking_service: type: string description: The service that tracks inventory. example: platform localized_descriptions: type: object description: A map of localized descriptions for the product. The field is the [ISO-639](https://www.iso.org/iso-639-language-codes.html) two character language code. The value is the product description in the given language. additionalProperties: type: string example: en: A hat for the beach fr: Un chapeau pour la plage localized_names: type: object description: A map of localized names for the product. The field is the [ISO-639](https://www.iso.org/iso-639-language-codes.html) two character language code. The value is the product name in the given language. additionalProperties: type: string example: en: Beach Hat fr: Chapeau de Plage name: type: string description: The name of the product. example: Beach hat published: type: boolean format: boolean description: Indicates whether the product is published on the storefront. example: true tags: type: string description: A string with comma separated values that describe the product. example: clothing, unisex, pants tax_code: type: string description: The tax code for the product. example: non-taxable type: type: string description: The product type. Used for searching. example: physical url: type: string description: The URL to the product on the storefront. example: /hats/beach-hat vendor: type: string description: The product vendor. example: OFS listProductsResponseBody: type: object properties: data: $ref: '#/components/schemas/listProductsResponseData' pagination: $ref: '#/components/schemas/paginationResponse' listProductsResponseData: type: object properties: products: type: array items: $ref: '#/components/schemas/product' paginationResponse: type: object properties: next: type: string description: A cursor to fetch the next page of results. Cursors have no requirements on how they are encoded, since they are opaque to the consumer. example: dGVzdGluZ3Rlc3Rpbmd0ZXN0aW5n prev: type: string description: A cursor to fetch the previous page of results. Cursors have no requirements on how they are encoded, since they are opaque to the consumer. Leave empty if there is no following dataset. example: dW50ZXN0dW50ZXN0dW50ZXN0 runtimeErrorProduct: type: object properties: errors: type: array items: required: - code type: object properties: code: type: string message: type: string type: type: string example: code: 07-1 message: Request failed due to an internal server error. type: server.internal_error deepVariant: type: object allOf: - $ref: '#/components/schemas/variantBase' properties: platform_id: type: string description: A unique identifier for the variant. Defined by the platform. example: variant-123456 option_values: type: array items: $ref: '#/components/schemas/variantOptionValue' variantBase: type: object description: An array of `variant` objects. At least one variant is required. If the product has no variants, the variant can reuse the product information. properties: allow_backorder: description: If backorders of the variant are allowed. type: boolean format: boolean example: true compare_at_price: description: The original price of the item before an adjustment or a sale. type: string example: '30.00' cost: description: The cost of the product variant. type: string example: '30.00' grams: description: The weight of the product variant in grams. type: integer format: int64 image_url: description: URL of the image. type: string example: your_platform_connector.com/files/products/hats/purple-beach-hat.jpg inventory_quantity: description: Current inventory level of the product. type: integer format: int64 inventory_tracking_entity: type: string description: Entity on which inventory is tracked. enum: - variant - product - none inventory_tracking_service: type: string description: Service that tracks inventory. example: platform localized_names: type: object additionalProperties: type: string description: Map of localized names for the variant. The field is the https://www.iso.org/iso-639-language-codes.html two character language code. The value is the product name in the given language. example: en: Purple fr: Violette name: description: The name of the variant. If there is only one variant, the `name` must be "Default Title" in order to avoid displaying the same `name` twice. type: string example: Default Title price: description: The price of the variant type: string example: '30.00' require_shipping: description: True if the item needs to be shipped, false otherwise. type: boolean format: boolean sku: description: Variant SKU. type: string example: BEACH-HAT-PURPLE tax_code: description: Tax code for the variant. type: string example: non-taxable tax_exempt: description: Indicates whether the variant is tax-exempt. If `true`, the variant is tax-exempt. type: boolean format: boolean nullable: true weight: type: string description: The weight of the product variant, calculated with weight unit specified. example: '1.0' weight_unit: type: string description: The unit of measurement that applies to the product variant's weight. example: kg variantOptionValue: type: object description: A more granular level of customization for variants. These are not required, but can be used to provide more options for your same variant. properties: platform_id: type: string description: A unique identifier for the variant option value. Defined by the platform. example: variant-option-value-123456 platform_product_option_id: type: string description: A unique identifier for the product option this value belongs to. Defined by the platform. example: product-option-123456 label: type: string description: Label of the option value. example: small name: type: string description: Name of the option. example: Small category: type: object allOf: - $ref: '#/components/schemas/categoryBase' properties: platform_id: type: string description: A unique identifier for the category. Defined by the platform. example: category-123456 platform_updated_at: description: The date the category was last updated on the platform. type: string format: date-time example: '2021-03-11T17:16:51Z' categoryBase: type: object properties: image_url: description: Specifies the URL location of the category image. type: string example: your_platform_connector.com/files/categories/hats.jpg name: description: The name of the category. type: string example: Hats listCategoriesResponseBody: type: object properties: data: $ref: '#/components/schemas/listCategoriesResponseData' pagination: $ref: '#/components/schemas/paginationResponse' listCategoriesResponseData: type: object properties: categories: type: array items: $ref: '#/components/schemas/category' deepImage: type: object allOf: - $ref: '#/components/schemas/imageBase' properties: platform_id: type: string description: A unique identifier for the image. Defined by the platform. example: image-123456 imageBase: type: object properties: name: description: The image name. type: string example: Beach hat src: description: The image URL. type: string example: your_platform_connector.com/files/images/beach-hat.jpg position: description: The position on the list. type: integer format: int64 example: 2 deepOption: type: object allOf: - $ref: '#/components/schemas/optionBase' properties: platform_id: type: string description: A unique identifier for the product option. Defined by the platform. example: product-option-123456 option_values: type: array items: $ref: '#/components/schemas/deepOptionValue' optionBase: type: object properties: name: description: The option name. type: string example: Small position: description: The position on the list. type: integer format: int64 example: 2 deepOptionValue: type: object allOf: - $ref: '#/components/schemas/optionValueBase' properties: platform_id: type: string description: A unique identifier for the option value. Defined by the platform. example: option-value-123456 optionValueBase: type: object properties: is_default: type: boolean description: Indicates whether this is the default option. format: boolean example: true label: description: The label of the option value. type: string example: Small position: description: The position on the list. type: integer format: int64 example: 1 parameters: timestamp: name: X-HMAC-Timestamp in: header schema: type: string format: date-time required: true description: The UTC server time (in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339)) at the moment the request was sent, signed as a part of calculating X-HMAC and X-Compatible-HMAC values. example: '2021-03-11T17:16:51Z' userAgent: name: User-Agent in: header schema: type: string required: true description: A value to help filter traffic from Bold through any firewall system. Bold sends requests to your Platform Connector with the value `Bold-API`. You can adjust your firewall system to allow calls with this value to reach your Platform Connector. example: Bold-API shopIdentifier: name: shop_identifier in: path description: A unique identifier of the store. This can be retrieved by calling the [Get Shop Info](/shops#operation/GetShopInfo) endpoint. required: true schema: type: string example: zp3oafdor9 customerId: name: platform_id in: path description: A unique identifier for the customer. Assigned by the platform. required: true schema: type: string example: customer-123456 platformCustomerId: name: platform_customer_id in: path description: Unique identifier for the customer. Assigned by the platform. required: true schema: type: string example: customer-123456 addressId: name: platform_id in: path description: Unique identifier for the address. Assigned by the platform. required: true schema: type: string example: address-123456 orderId: name: platform_id in: path description: Unique identifier for the order. Assigned by the platform. required: true schema: type: string example: order-123456 orderPlatformId: name: order_platform_id in: path description: Unique identifier for the order. Assigned by the platform. required: true schema: type: string example: order-123456 paymentId: name: platform_id in: path description: Unique identifier for the payment. Assigned by the platform. required: true schema: type: string example: payment-123456 idempotencyKey: name: Idempotency-Key in: header schema: type: string required: false description: Use the HTTP idempotency request header field to carry an idempotency key in order to make non-idempotent HTTP methods, such as POST or PATCH, fault-tolerant. example: qaasc934qfj9aerf limit: name: limit in: query description: The maximum number of results to return per page. schema: type: integer format: int32 minimum: 1 maximum: 250 default: 250 example: 100 cursor: name: cursor in: query description: A cursor to obtain the next page of results. Bold takes the value of the cursor directly from the `next` value in the response without any modifications. schema: type: string example: dW50ZXN0dW50ZXN0dW50ZXN0 examples: customerNotFound: value: code: 404-1 message: Customer not found. type: customer.not_found addressNotFound: value: code: 404-2 message: Address not found. type: address.not_found internalError: value: code: 500 message: Request failed due to an internal server error. type: server.internal_error orderNotFound: value: code: 404-1 message: Order not found. type: order.not_found paymentNotFound: value: code: 404-2 message: Payment not found. type: payment.not_found