Skip to main content

Making API Calls

Bold provides several methods for authenticating calls to the APIs. This guide covers the various methods of authenticating and outlines the instructions for doing so.

Prerequisites

Complete the steps outlined in this product's Getting Started guide.

Generate a token

First, you must identify which type of token is appropriate for your project. Use the following table to determine which type is right for you:

Token typeUse casesMethod of creationInstructions
API Access TokenSelf-hosted checkout flows and private integrationsVia Bold Account CenterRead the instructions
OAuth 2.0 TokenPublic integrationsVia the Developer DashboardRead the instructions

Generate an API access token

To request a unique API access token, use the following steps:

  1. Log in to Bold Account Center, or sign up for an account if you don't have one yet.
  2. In the Bold Account Center, click API access tokens in the left-hand menu.
  3. Click Create API access token.
  4. Enter the API access token name and select the scopes you need. When prompted to specify the scopes of your API access token, select the following scopes:
CategoryScopePermissions
CoreCustomersRead & Write
CoreOrdersRead & Write
CoreShop SettingsRead & Write
CoreShopsRead
CheckoutPaymentsWrite
  1. Select Create. A dialog box provides you with a shared secret and API access token. Be sure to save both in a secure location, as they disappear when you close the dialog.
  2. Click Done when you are finished.

Generate an OAuth token

Follow the instructions in the Build Public Integrations guide to create a Developer Dashboard account and authenticate your integration.

These steps are also included below for your convenience:

OAuth 2.0 Authentication flow

Create a Bold Developer Dashboard account

The Bold Developer Dashboard enables you to make requests to Bold APIs. With this account, you can generate a client ID and specify your redirect URI for OAuth authentication.

To create an account and prepare your integration for install, complete the following steps.

  1. Create a Bold Developer Dashboard account here.

Screenshot of the developer dashboard account creation page.

  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. Note the generated client_id.

Exchange client ID

For each store your integration is installed on, you must request (and receive) access scopes from the store administrator, and generate an API access token.

To avoid re-use of API access tokens, each store requires a unique token. Once generated, API access tokens do not expire, and refresh tokens are not required.

Request permissions

When a merchant installs your integration, you must prompt them to authorize your request for the access scopes your integration requires. The following code sample shows an example of directing the merchant to an install page in Bold Account Center:

https://apps.boldapps.net/accounts/dashboard/authorize?client_id={client_id}&scope=read_products&redirect_uri=https://myapp.example.com/complete_install
FieldDescription
client_idThe client ID generated by creating credentials on your developer dashboard.
scopeThe comma-separated list of access scopes your application requires.
redirect_uriThe URL to redirect the merchant to after they accept scopes.

The following screenshot shows the install page in Bold Account Center.

Screenshot of the integration install page.

Accept granted permissions

Once the merchant grants the required access scopes, their browser redirects them to your defined redirect_uri.

Your application receives a request with a query parameter named code.

https://myapp.example.com/complete_install?code=OoChaiphaiLoWohgh2hae3ahchiy9iu9
FieldDescription
codeThe authorization code from the redirect request to your application.
Exchange code for an API access token

Exchange the code value for an API access token associated with the merchant's store. The following shows an example using cURL to exchange the code for a token:

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}'
FieldDescription
client_idThe client ID retrieved from creating credentials within your developer dashboard.
grant_typeMust be set to the string value of authorization_code.
client_secretThe client secret retrieved from creating credentials within your developer dashboard.
codeThe authorization code from the redirect request to your application.
Store the API access token from the response

The JSON response you receive from the merchant contains an access_token field, which you must save for future API requests to that store.

The following is an example JSON response:

{
"token_type": "bearer",
"access_token": "2YotnFZFEjr1zCsicMWpAA"
}

If an error occurs, contact the Bold support team.

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 {api_token}' \
--header 'Bold-API-Version-Date: 2022-05-01'

Request Parts

FieldTypeRequiredDescription
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. {api_token} should be replaced with your unique API access token.

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 {api_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 {api_token}' \
--header 'Bold-API-Version-Date: 2022-05-01'

If everything is working as expected, you will receive 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 {api_token}' \
--header 'Bold-API-Version-Date: 2022-05-01'

If everything is working as expected, you will receive 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.

Keep building

You now have everything you need to start customizing your private integration. Here are some ideas for where to go next: