Provides an API to construct a URI for the HTTP API endpoints in a declarative way. Useful for building request uri for requests.



npm install --save @commercetools/api-request-builder


<script src="https://unpkg.com/@commercetools/api-request-builder/dist/commercetools-api-request-builder.umd.min.js"></script>
<script>// global: CommercetoolsApiRequestBuilder</script>


Creates a request builder that allows to declaratively build a HTTP API request URI for the commercetools platform.


The options argument must be an object with a projectKey property, and optionally a customServices property

    options -> { projectKey, customServices }
  1. projectKey (String): A required string specifying the project key to use for the request. Even though this is required, the project key can be omitted from the URI by passing {withProjectKey: false} to .build()
  2. customServices (Object): A map of custom services that are not provided by default. This might be useful to build a request for a different API with similar query parameters.

A service is created by defining its features. Features give a service specific characteristics to correctly build URIs. For example, if a service can query a resource by ID you would include queryOne. Available features types are:

  • query: allows to use standard query capabilities (page, perPage, sort, where, whereOperator)
  • queryOne: allows to query a single resource (byId, byKey, byCustomerId, byCartId)
  • queryLocation: allows to query resources by location (byCountry, byCurrency, byState)
  • queryExpand: allows to use reference expansion (expand)
  • search: allows to use search capabilities (text, fuzzy, fuzzyLevel, facet, markMatchingVariants, filter, filterByQuery, filterByFacets)
  • projection: allows to use projections capabilities (staged, priceCurrency, priceCountry, priceCustomerGroup, priceChannel)
  • suggest: allows to use suggest capabilities (searchKeywords)
import {
} from '@commercetools/api-request-builder'
const options = {
  projectKey: 'my-project',
  customServices: {
    users: {
      type: 'users',
      endpoint: '/users',
      features: [features.query, features.queryOne],
const requestBuilder = createRequestBuilder(options)

Note that markMatchingVariants is set by default to false which turns off this feature on the API.


It is also possible to append the version of a resource to the uri when making a request that requires this (for example a DELETE request). This can be done by passing the required version to the .withVersion() method.

const service = createRequestBuilder(options)
const uri = service.channels.withVersion(2).build()

Usage example

import { createRequestBuilder } from '@commercetools/api-request-builder'
import { createClient } from '@commercetools/sdk-client'

const requestBuilder = createRequestBuilder({ projectKey: 'my-project-key' })
const client = createClient({
  middlewares: [...],
const channelsUri = requestBuilder.channels
  .where('key = "foo"')
const channelsRequest = {
  uri: channelsUri,
  method: 'GET',

.then(result => ...)
.catch(error => ...)

Declarative Usage

A declarative API exists as an alternative to the imperative API (shown in the example above).

// same imports and instantiation as above
const channelsUri = requestBuilder.channels
    where: ['key = "foo"'],
    perPage: 1,
    version: 3,

Type of Params This declarative parse API accepts an object of the following shape:

  // query-expand
  expand?: Array<string>;

  // query-id
  id?: ?string;
  key?: ?string;
  customerId?: ?string;
  cartId?: ?string;

  // query-location
  country?: ?string;
  currency?: ?string;
  state?: ?string;

  // query-page
  sort: Array<{ by: string, direction: 'asc' | 'desc' }>;
  page: ?number;
  perPage: ?number;

  // query-projection
  staged?: boolean;
  priceCurrency?: string;
  priceCountry?: string;
  priceCustomerGroup?: string;
  priceChannel?: string;

  // query-search
  text?: ?{
    language?: string;
    value?: string;
  fuzzy?: boolean;
  fuzzyLevel?: number;
  markMatchingVariants?: boolean;
  facet?: Array<string>;
  filter?: Array<string>;
  filterByQuery?: Array<string>;
  filterByFacets?: Array<string>;

  // query-suggest
  searchKeywords?: Array<{language: string; value: string;}>;

  // query
  where?: Array<string>;
  whereOperator?: 'and' | 'or';

  // version
  version?: string;

Mixed usage

The imperative API can be mixed with the declarative one.

// these both lead to the same result
  .parse({ page: 5 })
  .parse({ page: 5 })

results matching ""

    No results matching ""