Getting Started With Your API

This page will help you get started with Kibo's APIs.

Implementing Kibo Composable Commerce REST APIs allows merchants to take advantage of efficient ecommerce, order management, and fulfillment strategies to bridge the gap between online and in-store shopping.

The Kibo knowledge base includes additional documentation to help developers become more familiar with the REST APIs or other development tools. A Postman collection is also available.

How to Use Interactive API Docs

This API documentation allows you to try calls to a tenant without having to configure any applications or secrets.

  1. Click the Log In button in the top right of the screen. This will take you to the Kibo Dev Center.
  2. Click a sandbox or production tenant. You will be redirected back to this site.
  3. Go to the documentation page of any API call.
  4. The Try it! button will now be operational. Fill in any required parameters or add values with the provided text fields to alter the request, and the response of the call will be displayed.

Making API Calls

This section explains how to determine API base URLs, perform authentication, and define headers when you make API calls outside of the interactive documentation.

Base URLs

Base URLs reference either a production or sandbox environment, and can optionally include a Site ID (s00000) in addition to your required Tenant ID (t00000). The tp0 is your tenant's assigned production pod for making calls to production environments.

Example US Sandbox Tenant: https://t00000.sandbox.mozu.com/api

Example US Production Tenant: https://t00000.tp0.mozu.com/api

Example EU Sandbox Tenant: https://t00000.sb.euw0.kibocommerce.com/api

Example EU Production Tenant: https://t00000.tp0.euw1.kibocommerce.com/api

How to Authenticate

Any user that calls into the Kibo APIs must authenticate by including an OAuth 2.0 access token in the request header. To obtain this token, you must provide the prerequisite Application (Client) ID and shared Client Secret.

This ID and secret may be found in the Dev Center under the Application Core details if needed.

curl --request POST \
     --url 'https://t00000.sandbox.mozu.com/api/platform/applications/authtickets/oauth' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "client_id": "string",
  "client_secret": "string",
  "grant_type": "client"
}
'

Response 200

{
  "access_token": "{jwt}",
  "token_type": "bearer",
  "expires_in": 600000,
  "refresh_token": "{refreshtoken}"
}

Additional Headers

The request headers may include additional context which often identifies the site and catalog you are referencing. If you use the hostname format that includes the Site ID, then the master catalog, catalog, site, locale, and currency context are inferred by the site and do not need to be explicitly provided.

The following is an example explicitly defining that context:

x-vol-master-catalog: 1
x-vol-catalog: 1
x-vol-site: 11111

The following table describes all headers supported by Kibo, though most are not required for every API operation.

HeaderTypeValue
x-vol-catalogrequest and responseThe identifier of the catalog. Your first catalog is 1, the second catalog is 2, and so on.
x-vol-master-catalogrequest and responseThe identifier of the master catalog. Your first master catalog is 1, the second catalog is 2, and so on.
x-vol-siterequest and responseThe unique identifier of the site. When you log in to Admin, this number appears in the URL for the Site Builder module, preceded by an "s-".
x-vol-localerequest and responseThe code of the content locale. For example: en-US
x-vol-versionrequest and responseThe version of the API to use in the request. If the version is not specified, the request uses the latest available version.
x-vol-currencyrequest and responseThe three-letter ISO 4217 standard global currency code. For example: USD
x-vol-purchase-locationrequestThe location code of the store that you want to restrict your call to, such as for querying products only at that particular location.
x-vol-pricelistrequestThe code of the pricelist that you want to restrict your call to, such as when querying for products.
x-vol-correlationrequestAn optional GUID used to associate multiple log entries in a cascading chain of API requests.
x-vol-dataview-moderequestThe mode in which to view runtime data, which is Live or Pending.

Putting it All Together

curl --request GET \
     --url 'https://t123.sandbox.mozu.com/api/commerce/catalog/admin/attributedefinition/producttypes?pageSize=10' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {jwt}'\
     --header 'x-vol-master-catalog: 1' 

Further Documentation

To learn how to use Postman, see the Getting Started with Postman guide.

For information on how to filter and sort API queries, see the Filtering and Sorting documentation.

After you have submitted your request, refer to the Status Codes documentation for the HTTP statuses and other API response codes you can expect.

Kibo APIs

Kibo's APIs are organized under the following services: