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.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)
  • 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: [
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 = {
  url: channelsUri,
  method: 'GET',

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

results matching ""

    No results matching ""