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.

note

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:

• Create accounts
• Complete authentication
• Make your first request
• Explore Bold APIs
• Launch your integration

Prerequisites

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, BigCommerce, and WooCommerce 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.

note

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., https://myapp.example.com/complete_install).
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:

https://apps.boldapps.net/accounts/dashboard/authorize?client_id={client_id}&scope=read_products&redirect_uri=https://myapp.example.com/complete_install

Field	Description
client_id	Client ID generated by creating credentials on your developer dashboard.
scope	Comma-separated list of access scopes your application requires.
redirect_uri	URL 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:

https://myapp.example.com/complete_install?code=OoChaiphaiLoWohgh2hae3ahchiy9iu9

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 'https://api.boldcommerce.com/auth/oauth2/token' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data 'client_id={client_id}&grant_type=authorization_code&client_secret={client_secret}&code={code}'

Field	Description
client_id	Client ID retrieved from creating credentials within your developer dashboard.
grant_type	Must be set to the exact value authorization_code.
client_secret	Client secret retrieved from creating credentials within your developer dashboard.
code	Your 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 https://api.boldcommerce.com and has a few common parameters. For a breakdown of these parameters, take the following example:

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

Request Parts

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

Field	Type	Required	Description
api	URL parameter	Yes	The API you are accessing. Full list of Bold APIs.
version	URL parameter	Sometimes	Only required for versioned APIs. More about API versioning.
shop_identifier	URL parameter	Yes	Shop GUID retrieved from making a request to the Get Shop Info endpoint.
Authorization	Header	Sometimes	Only 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.

note

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 'https://api.boldcommerce.com/shops/v1/info' \
     --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 'https://api.boldcommerce.com/products/v2/shops/{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.

   note

   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.

   note

   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.

   note

   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.