# @commercetools/ts-client

> commercetools TypeScript SDK client.

Latest version **5.1.1** (published 2026-10-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install @commercetools/ts-client
pnpm add @commercetools/ts-client
yarn add @commercetools/ts-client
bun add @commercetools/ts-client
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.1.1 |
| Published | 2026-10-09 |
| First published | 2022-12-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 1 |
| Unpacked size | 359.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 65 |
| Author | Chukwuemeka Ajima |
| Maintainers | commercetools-admin, emmenko, hajoeichler, tdeekens, jenschude, chukwuemeka |
| Keywords | commercetools, sdk, typescript, client, middleware, http, oauth, auth |

## Links

- npm: https://www.npmjs.com/package/@commercetools/ts-client
- Repository: https://github.com/commercetools/commercetools-sdk-typescript
- Issues: https://github.com/commercetools/commercetools-sdk-typescript/issues
- npm.io page: https://npm.io/package/@commercetools/ts-client

## Dependencies (1)

- [buffer](https://npm.io/package/buffer.md) ^6.0.3

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 5.1.1 (latest) — 2026-10-09
- 2.1.0-alpha.1 (next) — 2024-10-03
- 5.1.0 — 2026-10-05
- 5.0.3 — 2026-09-15
- 5.0.2 — 2026-08-07
- 5.0.1 — 2026-08-05
- 5.0.0 — 2026-06-15
- 4.10.0 — 2026-06-01
- 4.9.3 — 2026-05-21
- 4.9.2 — 2026-05-12
- 4.9.1 — 2026-03-03
- 4.9.0 — 2026-02-09
- 4.8.0 — 2025-12-30
- 4.7.0 — 2025-12-13
- 4.3.0 — 2025-10-07
- … 52 more at https://npm.io/package/@commercetools/ts-client/versions

## README

# commercetools (Improved) TypeScript SDK client

This is the new and improved Typescript SDK client.

## Usage examples

```bash
npm install --save @commercetools/ts-client
npm install --save @commercetools/platform-sdk

or

yarn add @commercetools/ts-client
yarn add @commercetools/platform-sdk
```

```ts
import {
  type Next,
  type HttpMiddlewareOptions,
  type AuthMiddlewareBaseOptions,
  type ClientRequest,
  type MiddlewareRequest,
  type MiddlewareResponse,
  type Client,
  createHttpMiddleware,
  createConcurrentModificationMiddleware,
  createAuthMiddlewareForClientCredentialsFlow,
  ClientBuilder,
} from '@commercetools/ts-client'
import { createApiBuilderFromCtpClient } from '@commercetools/platform-sdk'

const projectKey = 'mc-project-key'
const authMiddlewareOptions = {
  host: 'https://auth.europe-west1.gcp.commercetools.com',
  projectKey,
  credentials: {
    clientId: 'mc-client-id',
    clientSecret: 'mc-client-secrets',
  },
  oauthUri: '/oauth/token', // - optional: custom oauthUri
  scopes: [`manage_project:${projectKey}`],
  httpClient: fetch,
}

const httpMiddlewareOptions = {
  host: 'https://api.europe-west1.gcp.commercetools.com',
  httpClient: fetch,
}

const retryOptions = {
  maxRetries: 3,
  retryDelay: 200,
  backoff: true,
  retryCodes: [503],
}

const loggerFn = (response) => {
  // log response object
  console.log(response)
}

// custom middleware
function middleware(options) {
  return (next: Next) =>
    async (request: MiddlewareRequest): Promise<MiddlewareResponse> => {
      const { response, ...rest } = request

      // other actions can also be carried out here e.g logging,
      // error handling, injecting custom headers to http requests etc.
      console.log({ response, rest })
      return next({ ...request })
    }
}

const client: Client = new ClientBuilder()
  .withPasswordFlow(authMiddlewareOptions)
  .withLoggerMiddleware({ loggerFn })
  .withCorrelationIdMiddleware({
    generate: () => 'fake-correlation-id' + Math.floor(Math.random() + 2),
  })
  .withHttpMiddleware(httpMiddlewareOptions)
  .withMiddleware(middleware({})) // <<<------------------- add the custom middleware here
  .build()

const apiRoot = createApiBuilderFromCtpClient(client)

// calling the commercetools `api` functions
// get project details
apiRoot
  .withProjectKey({ projectKey })
  .get()
  .execute()
  .then((x) => {
    /*...*/
  })

// create a productType
apiRoot
  .withProjectKey({ projectKey })
  .productTypes()
  .post({
    body: { name: 'product-type-name', description: 'some description' },
  })
  .execute()
  .then((x) => {
    /*...*/
  })

// create a product
apiRoot
  .withProjectKey({ projectKey })
  .products()
  .post({
    body: {
      name: { en: 'our-great-product-name' },
      productType: {
        typeId: 'product-type',
        id: 'some-product-type-id',
      },
      slug: { en: 'some-slug' },
    },
  })
  .execute()
  .then((x) => {
    /*...*/
  })
```

## Create a client

To create a client, use the `ClientBuilder` class. The `ClientBuilder` class provides a fluent API to configure the client.

```ts
const authMiddlewareOptions = {
  credentials: {
    clientId: 'xxx',
    clientSecret: 'xxx',
  },
  host: 'https://auth.europe-west1.gcp.commercetools.com',
  projectKey: 'xxx',
}

const httpMiddlewareOptions = {
  host: 'https://api.europe-west1.gcp.commercetools.com',
  httpClient: fetch,
}

const client = new ClientBuilder()
  .withHttpMiddleware(httpMiddlewareOptions)
  .withConcurrentModificationMiddleware()
  .withClientCredentialsFlow(authMiddlewareOptions)
  .build()
```

<!-- > [!WARNING]
> Do not add the built-in middlewares using `withMiddleware` method. Adding by this method does not respect the ordering of the middlewares and could lead to unexpected behavior. -->

The `withMiddleware` method can be used to add middleware functions (both built-in and custom middleware) in an ordered fashion.

```ts
// Example
const authMiddlewareOptions = {
  credentials: {
    clientId: 'xxx',
    clientSecret: 'xxx',
  },
  host: 'https://auth.europe-west1.gcp.commercetools.com',
  projectKey: 'xxx',
}

const httpMiddlewareOptions = {
  host: 'https://api.europe-west1.gcp.commercetools.com',
  httpClient: fetch,
}

const logger = () => {
  return (next) => async (request) => {
    // log request object
    console.log('Request:', request)
    const response = await next(request)

    // log response object
    console.log('Response', response)
    return response
  }
}

const client = new ClientBuilder()
  .withMiddleware(
    createAuthMiddlewareForClientCredentialsFlow(authMiddlewareOptions)
  )
  .withMiddleware(createHttpMiddleware(httpMiddlewareOptions))
  .withMiddleware(createConcurrentModificationMiddleware())
  .withMiddleware(logger())
  .build()
```

This will add the middleware in an ordered fashion starting with the:

1. createAuthMiddlewareForClientCredentialsFlow
2. createHttpMiddleware
3. createConcurrentModificationMiddleware
4. logger

Note that when using the `withMiddleware` function to add a custom middleware along side other in built middleware functions, it will add the custom middleware to the start of the execution chain.

```ts
// Example
const authMiddlewareOptions = {
  credentials: {
    clientId: 'xxx',
    clientSecret: 'xxx',
  },
  host: 'https://auth.europe-west1.gcp.commercetools.com',
  projectKey: 'xxx',
}

const httpMiddlewareOptions = {
  host: 'https://api.europe-west1.gcp.commercetools.com',
  httpClient: fetch,
}

const logger = () => {
  return (next) => async (request) => {
    // log request object
    console.log('Request:', request)
    const response = await next(request)

    // log response object
    console.log('Response', response)
    return response
  }
}

const client = new ClientBuilder()
  .withClientCredentialsFlow(authMiddlewareOptions)
  .withHttpMiddleware(httpMiddlewareOptions)
  .withConcurrentModificationMiddleware()
  .withMiddleware(logger())
  .build()
```

The order of execution is as follows:

1. withMiddleware <------ the custom middleware
2. withClientCredentialsFlow
3. withHttpMiddleware
4. withConcurrentModificationMiddleware

---
_Source: https://npm.io/package/@commercetools/ts-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._