General concepts

The commercetools Checkout APIs offer an interface for programmatic access to the data stored and associated functionality. While you can use the API directly for experimentation or custom integration solutions, we recommend you look at the available client libraries and SDKs, which provide a more comfortable development experience.

Regions

These Regions are completely isolated from each other, and no data is transferred between them.

User accounts

Hosts

The commercetools Checkout APIs are hosted at the following URLs:

Prepend all requests to endpoints with these URLs.

Authorization

UTF-8

All text content storage, processing, and API interaction use UTF-8 encoding.

JSON

When consuming a JSON response, ignore any unrecognized fields in JSON objects of responses, or deal with them such that it does not cause the client application to crash. The API assumes clients behave properly and considers the addition of new fields to be backward-compatible for existing clients. In addition, client applications should not rely on the presence of undocumented fields. Fields returned by an undocumented endpoint can be renamed or removed at any time without prior notice.

Identifier

Resource updates

Partial updates

To update a resource, use one or more update actions with the update endpoint of the target resource. Each resource has a list of applicable update actions.

You can combine multiple update actions in a single request, provided they modify the same resource. Update actions must be ordered based on the sequence in which they should be processed. For example, if you are making changes to an Application and want to activate an application only after setting agreements, you must add the setStatus update action at the end of the update action list.

The request representation (patch format) of an update request is as follows:

Some resource updates or state transitions might not be compatible with each other within a single request. In these cases, dedicated endpoints might be provided to handle specific updates or state transitions individually.

The following example shows a request that contains two update actions:

{
  "version": 1,
  "actions": [
    {
      "action": "setTitle",
      "title": "My title"
    },
    {
      "action": "setText",
      "text": "My text"
    }
  ]
}

Update guarantees

The API provides different update guarantees for different kinds of requests.

Optimistic concurrency control

After making an update, the HTTP response body contains the new version of the resource. An API client must wait for the latest version before sending follow-up requests.

Background processes and other events can also change a resource's version without any requests sent from an API client directly to the resource. Do not rely on a consistently incremented version number.

Security

It is not necessary to support the full set of SSL/TLS features listed here (or stop supporting other features), especially the cipher suites, as long as one valid combination exists. The TLS handshake includes a "negotiation phase" that chooses the best combination that both client and server support.

• Cipher suites: TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305
• Minimum accepted TLS Version: v1.2

Query features

Single resource query response

Query responses for single resources only return a single, top-level JSON object.

PagedQueryResult

Sorting

For sorting based on values of standard fields of resources the provided parameter value must be a valid sort expression of the form:

<field name> <sort direction>

<field name>.<locale> <sort direction>

Find below some examples of sort expressions:

key asc
name.en asc
custom.fields.trackingNumber desc

Pagination

Resource timestamps

Correlation ID

A single user interaction can trigger a cascade of events across multiple services, databases, and third-party integrations. Without a correlation ID, tracing the events can be difficult and debugging a failure or performance issue becomes a time-consuming task.

Purpose

A correlation ID is a unique, immutable identifier tied to a specific request or business transaction such as checking out a cart. It serves as a persistent anchor, allowing you to follow the complete lifecycle of an action from its inception to its final state.

Format

Correlation IDs are strings that may only contain alphanumeric characters, underscores, and hyphens. They can have a length of 8 to 256 characters. Include UUIDs to ensure uniqueness.

Where:

• Origin: A short, human-readable identifier for the system that initiated the entire chain, for example, BFF, SPA, iOS-App, Syncer-Job.
• Root-ID: A unique identifier for the end-to-end transaction, generated once at the Origin and remains constant across all subsequent service calls for that single user action.
• Span-ID: A unique identifier for a single unit of work or a single request-response hop within the transaction. Each service generates a new Span-ID when it receives a request and makes a new downstream call.

Usage

If you don't provide a correlation ID for an HTTP request, commercetools Checkout generates one returned with the response.

Client logging

Events tracked

Information in the fields