# General concepts

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

The 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 Checkout APIs are provided in the following Regions: North America (Google Cloud, Iowa), North America (AWS, Ohio), Europe (Google Cloud, Belgium), Europe (AWS, Frankfurt), 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](https://ok.commercetools.com/free-trial) is required for each individual Region.

If you need help choosing a Region to locate your Project in, contact the [commercetools support team](https://support.commercetools.com/).

### Hosts

The Checkout APIs are hosted at the following URLs:

(a CSV formatted table follows. The first line are the column names.)
Region,API URL
Europe (Google Cloud, Belgium),`https://checkout.europe-west1.gcp.commercetools.com/`
Europe (AWS, Frankfurt),`https://checkout.eu-central-1.aws.commercetools.com/`
North America (Google Cloud, Iowa),`https://checkout.us-central1.gcp.commercetools.com/`
North America (AWS, Ohio),`https://checkout.us-east-2.aws.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](https://docs.commercetools.com/api/authorization.md).

Some endpoints provide alternative scopes for each API operation. For more information, see [Scopes](https://docs.commercetools.com/checkout/scopes.md). 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 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](https://docs.commercetools.com/checkout/applications-api.md#update-actions) endpoint with one or more [Application update actions](https://docs.commercetools.com/checkout/applications-api.md#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:

(a CSV formatted table follows. The first line are the column names.)
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:

```json
{
  "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](https://docs.commercetools.com/checkout/general-concepts.md#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](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AConcurrentModificationError) error.

## Security

All API access is over HTTPS. API authorization uses [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6750/) bearer tokens.
For more information, see [Authorization](https://docs.commercetools.com/api/authorization.md).

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](https://docs.commercetools.com/checkout/general-concepts.md#sorting), [pagination](https://docs.commercetools.com/checkout/general-concepts.md#pagination), and [Reference Expansion](https://docs.commercetools.com/api/general-concepts.md#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](https://docs.commercetools.com/api/predicates/query.md) 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

See API type definition [PagedQueryResponse](https://docs.commercetools.com/checkout/general-concepts.md?urn=ctp%3Aapi%3Atype%3APagedQueryResponse).

### 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](https://docs.commercetools.com/urn?urn=ctp%3Acheckout%3Atype%3ALocalizedString) fields, use the field name followed by the [Locale](https://docs.commercetools.com/urn?urn=ctp%3Acheckout%3Atype%3ALocale):

```
<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.

- [Application allowedSortList](https://docs.commercetools.com/checkout/applications-api/#allowed-sortlist)
- [Payment Integration allowedSortList](https://docs.commercetools.com/checkout/payment-integrations-api/#allowed-sortlist)

### 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 10000.

#### Total

To improve query performance, the calculation of the `total` field in the [PagedQueryResult](https://docs.commercetools.com/checkout/general-concepts.md#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 Checkout APIs.
When contacting the [commercetools support team](https://support.commercetools.com) 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, Checkout generates one returned with the response.

In our TypeScript SDK, you can set this header in a dedicated [middleware](https://docs.commercetools.com/checkout/dev-tooling/ts-sdk-middleware.md#correlationidmiddleware).

## Client logging

Resources within 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](https://docs.commercetools.com/checkout/common-types.md#client-logging).

## Related pages

- [Section overview page](https://docs.commercetools.com/checkout.md)
- [Next page: Common types](https://docs.commercetools.com/checkout/common-types.md)