General concepts

This document gives an overview of the characteristics and common features of the Checkout APIs.

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

To provide the best possible Service Level Agreement (SLA) and minimal latency, the commercetools Checkout APIs are provided in the following Regions: North America (Google Cloud, Iowa), Europe (Google Cloud, Belgium), and Australia (Google Cloud, Sydney).

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

User accounts

User accounts created for one Region are not valid for other Regions. A signup is required for each individual Region.

If you need help choosing a Region to locate your Project in, contact the commercetools support team.

Hosts

The commercetools Checkout APIs are hosted at the following URLs:

Region	API URL
North America (Google Cloud, Iowa)	`https://checkout.us-central1.gcp.commercetools.com/`
Europe (Google Cloud, Belgium)	`https://checkout.europe-west1.gcp.commercetools.com/`
Australia (Google Cloud, Sydney)	`https://checkout.australia-southeast1.gcp.commercetools.com/`

Prepend all requests to endpoints with these URLs.

If the documentation refers to https://checkout.{region}.commercetools.com, replace the {region} placeholder with the actual value.

Authorization

The Checkout APIs require a valid authorization token for all requests. For more information, see Authorization.

Some endpoints provide alternative scopes for each API operation. For more information, see Scopes. In addition to these, the manage_project:{projectKey} scope is always implicitly valid. This scope grants full API access for all the operations within a project.

UTF-8

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

JSON

The majority of the Checkout API endpoints consume and produce standard application/json payloads. To ensure that payloads are encoded correctly, use Content-type: application/json in your HTTP header when sending POST requests.

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

Some resources contain an id field that uniquely identifies a resource. The ID is generated by commercetools Checkout API when creating a resource.

Some resources have a string field key, which also uniquely identifies a resource. The key identifier is always assigned to a resource by the client.

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.

For example, to update an application, use the Update Application endpoint with one or more Application 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:

Field	Type	Required/Optional	Description
`id`	String	Required, to be part of the URL	ID of the target resource.
`version`	Number	Required if the target resource is versioned	Expected current version of the resource on which to apply the changes.
`actions`	Array	Required	One or more resource-specific update actions.

Misspelled optional fields within the actions array are treated as additional fields and ignored by the APIs. In particular, no error is sent back.

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.

Strong consistency

Each resource offers read-after-write consistency. The read-after-write consistency implies that when you update an entity, wait for the success response, and then read the same entity for your changes to be visible.

If a server-side problem occurs, indicated by a 500 Internal Server Error HTTP response, the requested action may still successfully complete after the error is returned. If you receive this error, you should verify the status of the requested resource.

Optimistic concurrency control

Many API resources use optimistic concurrency control to prevent lost updates when making changes to existing data concurrently. These resources have a version attribute. When sending (partial updates) to these resources, send the expected version of a resource as a part of the request.

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.

The API does not use ETag and If-Match HTTP headers for the purpose of optimistic concurrency control.

If a version mismatch occurs, the API returns a ConcurrentModification error.

Security

All API access is over HTTPS. API authorization uses OAuth 2.0 bearer tokens. For more information, see Authorization.

All HTTPS traffic is secured through Transport Layer Security (TLS). The relevant certificates are signed by trusted authorities. At any point in time, we will rely on a trusted root certificate. It is the API user's obligation to keep their systems updated regarding SSL/TLS capabilities as well as trusted root certificates. The server certificate, as well as intermediary certificates of the certificate chain, are transmitted as part of the TLS handshake. The API user is responsible for checking the expiration dates of all certificates in the chain and renewing them whenever necessary.

It is possible to connect to the API via HTTP (without SSL/TLS). You will, however, receive a 404 error, including an HTML body response on every attempt.

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.

Be aware that the certificates may at times support more features in transition periods. However, only the specifications listed below are reliable. You must not rely on other SSL/TLS features even if they currently work.

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

Common query features include sorting, pagination, and Reference Expansion. Certain aspects of these features are standardized across all parts of the API, as described in the following sections.

To filter results, Query Predicates allow you to express complex queries on many resources.

Single resource query response

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

PagedQueryResult

Each query endpoint returns a paged query response containing the actual resources matching the query predicate plus information about pagination. This documents the fields all query responses have in common, for specific response types, see the respective API reference pages.

`limit` Int	Number of results requested. Default: `20`Minimum: `0`Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0`Minimum: `0`Maximum: `10000`
`count` Int	Actual number of results returned.
`total` Int	Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter `withTotal=false`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`results` Array of BaseResource	The resources matching the query predicate. Each query endpoint returns resources of its specific type.
`meta` Object	Object containing supplementary information about the results.

Sorting

A query endpoint that supports sorting does so through the sort query parameter.

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>

For sorting based on values of LocalizedString fields, use the field name followed by the Locale:

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

The default sort direction is ASC. The allowed sort paths are typically listed on the specific query endpoints.

Find below some examples of sort expressions:

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

The sorting is case-sensitive. For a list of allowed fields resources can be sorted by, refer to the allowedSortList section of each API resource.

Pagination

Queries on collections of resources can optionally provide pagination functionality through limit and offset query parameters, allowing clients to request a certain page of the query result.

Limit

You can set the maximum number of results to return from a query using the limit query parameter. Allowed is a value between 0 and 500. The default limit on most query endpoints is 20.

Setting a high limit can impact performance.

Offset

The offset into the results matching the query can be set using the offset query parameter. offset defines the number of elements skipped, it is not a page number. The default value is 0, indicating that no results should be skipped. The maximum offset is 10 000.

Total

To improve query performance, the calculation of the total field in the PagedQueryResult should be deactivated by passing false in the withTotal query parameter whenever possible. By default unless specified in request the default value for withTotal is false.

Resource timestamps

Many resources exposed on the API contain the createdAt and the lastModifiedAt timestamps. Those timestamps are automatically set by the server on creation or modification of the resource.

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.

We strongly recommend you set a structured correlation ID to your requests to commercetools Checkout APIs. When contacting the commercetools support team about a specific request, provide its correlation ID in your ticket. Our support team relies on the correlation IDs to be able to assist you in troubleshooting issues, providing performance recommendations, and security forensics.

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.

We suggest following structure for your correlation IDs: {Origin}-{Root-ID}-{Span-ID}

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.

The key principle is:
The Root-ID tracks the entire journey, while the Span-ID identifies each step along the way.

Usage

Set the x-correlation-id HTTP header to propagate the correlation ID on HTTP requests. The responses will contain the same header with the correlation ID from the corresponding request.

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

In our TypeScript SDK, you can set this header in a dedicated middleware.

Client logging

Resources within commercetools Checkout provide information on changes and modifications in the createdAt, createdBy, lastModifiedAt, and lastModifiedBy fields.

Events tracked

When you create a resource, the createdBy, createdAt, lastModifiedBy, and lastModifiedAt fields are added.

When you call an update action using an API Client, the lastModifiedBy and lastModifiedAt fields are updated. An API Client update refers to any modifications made through a client application interacting with either the HTTP or the Merchant Center.

Information in the fields

The createdBy and lastModifiedBy fields do not contain any personally identifiable information. However, they can contain an external user ID, reference to the Customer ID, or identifier for an anonymous session in optional fields. The fields themselves are JSON objects. For more information, see the CreatedBy and LastModifiedBy common types.

General concepts

Regions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

User accounts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Hosts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Authorization.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

UTF-8.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

JSON.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Identifier.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Resource updates.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Partial updates.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update guarantees.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Strong consistency.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Optimistic concurrency control.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Security.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Query features.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Single resource query response.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

PagedQueryResult.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Sorting.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Pagination.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Limit.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Offset.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Total.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Resource timestamps.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Correlation ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Purpose.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Format.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Usage.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Client logging.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Events tracked.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Information in the fields.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}