Skip to main content

Build Public Integrations

If you are creating a public integration (which may be installed on multiple stores and can optionally be published in Bold Account Center), use these steps to set up OAuth authentication and make your first request to a Bold API.


Private integrations (which are for a single store and do not require OAuth) are covered in the Quick Start guide.

In this document, you will complete these steps:


Before beginning these steps, ensure you have installed one or more Bold apps on your platform of choice. Detailed installation guides for integrations on Shopify and BigCommerce can be found on the Bold Help Center.

If you are using another platform, contact us for help with your integration.

Create accounts

You need two accounts to build a public integration:

Bold Account Center account

The Bold Account Center enables you to develop using Bold APIs.

To create an account, use these steps:

  1. On the Bold Account Center login page, select Get started.
  2. Select Create a new organization of your own.
  3. Complete the Name, Organization, Username, and Password fields.
    1. In this case, Organization usually refers to your company's name. This value is used to identify the stores associated with your account.
    2. Select Create Account.
  4. Select the Platform your store is on, and enter the Store URL. Select Add store.
  5. The Bold Account Center detects whether you have any apps installed on the store.
    1. If you have apps installed, you are prompted to verify your store.
    2. If you do not have apps installed, you are prompted to install them at this time.

If the store you want to customize is already registered in the Bold Account Center, reach out to the administrator of that store and request an invitation. You will receive an email with instructions on how to join the store.

Bold Developer Dashboard account

The Bold Developer Dashboard enables you to generate a client ID and specify your redirect URI.

Create a Bold Developer Dashboard account

Complete authentication

To work with Bold APIs, you need to request and be granted access scopes from each store your integration is installed on and generate an API access token for that store. Once generated, API access tokens do not expire, and refresh tokens are not required.

Create client credentials

Begin the authentication process by generating client credentials in the Bold Developer Dashboard:

  1. Navigate to your developer dashboard.
  2. Click Create API Credential.
  3. Specify your application's name and redirect URI (e.g.,
  4. Take note of the generated client_id.

Ask for permission

To prompt a merchant to install your integration, direct them to an install page within Bold Account Center where they can authorize your request for the access scopes your application requires. For example:{client_id}&scope=read_products&redirect_uri=
client_idClient ID generated by creating credentials on your developer dashboard.
scopeComma-separated list of access scopes your application requires.
redirect_uriURL to redirect the merchant to after they accept scopes

Accept granted permission

Once the merchant accepts the scopes you’ve requested, their browser redirects them to the specified redirect_uri.

Your application receives a request with a query parameter named code that you can exchange for an API access token:

Exchange code for an API access token

You can now exchange that code for an API access token that is associated with the merchant's store.

For example, using cURL to exchange the code for a token, the command looks like this:

curl --request POST '' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'client_id={client_id}&grant_type=authorization_code&client_secret={client_secret}&code={code}'
client_idClient ID retrieved from creating credentials within your developer dashboard.
grant_typeMust be set to the exact value authorization_code.
client_secretClient secret retrieved from creating credentials within your developer dashboard.
codeYour authorization code from the query parameters of the redirect request to your application.

Store the API access token from the response

The JSON response you receive contains an access_token field that you can then save for future API requests for that store.

If an error occurs, look in the response for the error and error_description fields.

Make your first request

Each Bold API request accesses and has a few common parameters. For a breakdown of these parameters, take the following example:

curl --request GET '{api}/{version}/shops/{shop_identifier}/resource' \
--header 'Authorization: Bearer {access_token}' \
--header 'Bold-API-Version-Date: 2022-05-01'

Request Parts

curl --request GET '{api}/{version}/shops/{shop_identifier}/resource' \
--header 'Authorization: Bearer {access_token}' \
--header 'Bold-API-Version-Date: 2022-05-01'
apiURL parameterYesThe API you are accessing. Full list of Bold APIs.
versionURL parameterSometimesOnly required for versioned APIs. More about API versioning.
shop_identifierURL parameterYesShop GUID retrieved from making a request to the Get Shop Info endpoint.
AuthorizationHeaderSometimesOnly required for authenticated APIs. {access_token} should be replaced with the API access token you created above.

You can make most API calls using this format. To test it out, copy and paste the following commands into your command line interface.


Don't forget to replace {access_token} with your unique token.

Get your shop identifier

Use the Get Shop Info endpoint to get your shop_identifier and other basic shop info.

curl --request GET '' \
--header 'Authorization: Bearer {access_token}' \
--header 'Bold-API-Version-Date: 2022-05-01'

If everything is working as expected, your CLI returns a JSON response containing the details of your store. Make a note of the shop_identifier for the next call.

Confirm your products are synced to Bold

Using the List Products endpoint, check that your products are synced to Bold.

curl --request GET '{shop_identifier}/products' \
--header 'Authorization: Bearer {access_token}' \
--header 'Bold-API-Version-Date: 2022-05-01'

If everything is working as expected, your CLI returns a JSON response with the details of the products in your store, if there are any.

If either of these steps fails, reach out to the Bold Commerce Partners Team.

Explore Bold APIs

You can now access and use any of Bold's APIs to customize your public integration.

Try getting started with these:

  • Bold Checkout is a flexible checkout solution that offers APIs to create a custom high-converting transaction experience.
  • Bold Subscriptions allows you to generate recurring revenue for your merchants.
  • Bold Price Rules is a robust and flexible pricing and promotions engine that allows you to achieve complex pricing scenarios and rules to create customizable pricing structures and promotions.

Launch your integration

Public integrations can be either published or unpublished:

  • Published integrations are available in the Integration Marketplace for anyone with an account in Bold Account Center.
  • Unpublished integrations are available in the Integration Marketplace, but only for select stores. By default, public integrations are unpublished.

When you are ready to launch your integration, reach out to the Bold Partners team. Provide the following information in the details of your request:

  1. Whether you want the integration to be published for public access or unpublished and available only to specific stores. If you choose to leave the store unpublished, please include the store names or shop identifier values of the shops you want to access the integration.

  2. The client ID of your API credential in the Developer Dashboard, which was obtained in the Create client credentials section.

  3. The name of the integration.

  4. The name of the publisher (which shows up on the integration’s card in the Integration Marketplace).

  5. The logo.


    We accept JPEG or PNG images only, with a maximum file size of 800 kB. The logo is displayed at 120 px by 120 px on the integration detail page and 50 px by 50 px on integration listing cards.

  6. The short description of the integration.


    The short description must not exceed 130 characters. This text appears on the integration listing card in the Integration Marketplace.

  7. The long description of the integration.


    The long description must not exceed 65535 characters. This text appears on the integration detail page.

  8. The URL of the integration that is used to supply scopes when the integration redirects back to the Bold Account Center to accept scopes.

  9. Whether or not the integration has an admin interface that can be opened from the Integration Marketplace. If so, provide the URL of the admin that will open.

  10. The Bold applications that must be installed on a store before the merchant can install the integration.

Once Bold receives your request, we review your integration and launch it when ready.

Uninstall your integration (optional)

You can uninstall integrations in the Bold Account Center.

  1. Navigate to the Bold Account Center Launchpad page.
  2. Select the Integrations tab.
  3. Select the ... menu on the unwanted integration. Select Remove integration.
  4. Review the information in the pop-up. Once you're sure you want to proceed, select Remove integration.

Handling the uninstall request (optional)

Pressing "Remove integration" prompts Bold to send a request to the integration's configured admin webhook. As a user, handling this request is optional. Bold will continue retrying this request until we receive a successful HTTP response (e.g. 2xx), or until we've received 10 failed response codes.

The uninstall request has the following headers and fields:

curl --request POST '' \
--header 'X-BoldPlatform-Topic: integration/uninstalled' \
--header 'X-BoldPlatform-HMAC: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' \
--header 'X-BoldPlatform-Webhook-Version: v1' \
--header 'User-Agent: BoldPlatform-Webhook-Forwarder/1.0' \
--header 'Content-Type: application/json' \
--data '{
"shop_identifier": "shop_identifier",
"topic": "integration/uninstalled",
"data": {
"type": "integration_id",
"id": "bold_generated_integration_id",
"metadata": null
"occurred_at": "current_time"
X-BoldPlatform-TopicHeaderThe type of webhook request performed. When uninstalling, topic will always be integration/uninstalled.
X-BoldPlatform-HMACHeaderAn HMAC signature calculated with the SHA256 algorithm, using the entire request body and shared secret. To verify the HMAC signature, refer to Verify the uninstall request signature.
X-BoldPlatform-Webhook-VersionHeaderThe current version of the Bold webhook service.
User-AgentHeaderThe Bold webhook service.
shop_identifierPOST body dataClient ID generated by creating credentials on your developer dashboard.
topicPOST body dataThe type of webhook request performed. When uninstalling, topic is always integration/uninstalled.
data[type]POST body dataIntegration ID.
data[id]POST body dataBold-generated Integration ID.
data[metadata]POST body dataAny metadata associated with the integration.
occurred_atPOST body dataThe time the request was sent, in UTC format.

Verify the uninstall request signature

Each call from Bold is accompanied by an HMAC (hash-based message authentication code) signature. Bold constructs this signature by Base64 encoding a SHA256 hash of the entire request body and the shared secret.

Upon receiving the uninstall request, confirm that the request came from Bold by verifying the signature. The following PHP code sample includes an example of creating an HMAC signature, which you can verify against the signature in the request.

$secret = env('BOLD_SECRET');
$body = $request->getContent();
$passedHMAC = $request->header('X-Boldplatform-Hmac');

$calculatedHMAC = base64_encode(hash_hmac('sha256', $body, $secret, true));

if (hash_equals($passedHMAC, $calculatedHMAC)) {
// authenticated