Skip to main content

API Versioning

Bold uses date-based versioning to safely make improvements and updates to the APIs. This page contains instructions for implementing date-based versioning when calling the Bold APIs.

For a list of the most recent changes to the Bold APIs, refer to the changelog.

Date-based versioning​

Bold APIs are versioned as a single set of APIs (i.e. changes to one API trigger the creation of a new version of all APIs, even if those APIs did not change).

Indicate the version you would like to use via an HTTP request header. The header, named Bold-API-Version-Date, must have a dated value in YYYY-MM-DD format. This value identifies the version of API that your call uses.

The following snippet shows how to use this header in an API call:

curl --request GET 'https://api.boldcommerce.com/shops/v1/info' \
     --header 'Authorization: Bearer {api_token}' \
     --header 'Bold-API-Version-Date: 2022-05-01'

If you provide a Bold-API-Version-Date date that falls between two versions, Bold chooses the earlier version. For example, imagine that Bold released two API versions with dates 2022-06-01 and 2022-07-01 respectively. If you send a request with the header Bold-API-Version-Date: 2022-06-15, Bold fulfills the request according to the 2022-06-01 API version.

caution

Bold occasionally releases changelog entries that have a Bold-API-Version-Date in the future.

When working on a production store, never use a Bold-API-Version-Date that is in the future. Doing so may cause you to inadvertently opt-in to undocumented changes. Use a future Bold-API-Version-Date in non-production and development stores only.

Upgrading your integration​

In order to upgrade your integration, change the Bold-API-Version-Date across your application. If the new version includes breaking changes, you must adapt your integration to take these into account.

note

You can call more than one version of the Bold APIs within a single integration. For example, you can use the 2022-05-01 version in one call and the 2022-05-15 version in another.

This enables users to selectively use new features where needed without having to upgrade the whole integration.

Fallback version​

If you do not send the version header with your API request, or send a value that is not valid, Bold uses the fallback version.

The fallback version is currently 2022-05-01. Bold reserves the right to change the fallback version if necessary.

Breaking and non-breaking changes​

A non-breaking change is a change that does not require action for an API consumer to adopt. In contrast, breaking changes require action for an API consumer to adopt.

The following list includes some examples of what Bold considers non-breaking changes. These changes can be made and applied without requiring you to change API versions.

  • Critical security fixes.
  • A new endpoint.
  • A new optional parameter to a request.
  • A new required parameter to a request with a default value that preserves the original behavior.
  • A new field in a response.
  • Changes to the error message of a response.
  • Changes to the order of existing response fields.
note

Any change to correct an API that is not working as documented is also considered a non-breaking change. This means that if our API is not working as documented, then that discrepancy is considered a bug, and a change to address that bug would be considered a non-breaking change. We reserve the right to make these changes at any time.

Beta endpoints​

Occasionally, Bold releases one or multiple endpoints that are labeled [Beta]. Endpoints labeled [Beta] are live, but Bold reserves the right to change them without a changelog entry or other notification.

Exercise caution when using [Beta] endpoints in production. Bold recommends using them only if you are a partner in active conversations with the Bold team.

Changes to endpoints without a [Beta] label are documented in the Changelog.