Messages

A Message represents a change or an action performed on a resource, for example an Order or a Product.

Messages are available in a variety of Message Types specific to a resource. Common fields across Message Types are represented by a base resource, Message. In addition to these common fields, each Message contains further fields related to a particular change or action (for example, the field firstName is present on a CustomerFirstNameSet Message).

You can access Messages either by retrieving them from the API, or by subscribing to them with a Subscription. To retrieve them from the API, you must enable the feature first.

When Messages are delivered through a Subscription, the payload may exceed the size limit of the message queue. In that case, the additional Message fields are replaced with a PayloadNotIncluded object. You can retrieve the full Message by calling the Get Message endpoint.

Message Types

To see a list of available Message Types for a specific resource, use the following table:

Messages page	Represented resources
Approval Rule and Approval Flow Messages B2B B2X	Approval Rules, Approval Flows
Business Unit and Associate Role Messages B2B B2X	Business Units, Associate Roles
Cart and Order Messages	Carts, Orders, Recurring Orders, Order Edits
Approval Rule and Approval Flow Messages B2B	Approval Rules, Approval Flows
Business Unit and Associate Role Messages B2B	Business Units, Associate Roles
Cart and Order Messages	Carts, Orders, Order Edits, Recurring Orders
Customer Messages	Customers, Customer Tokens, Customer Groups
Payment Messages	Payments, Payment Methods
Pricing and Discount Messages	Cart Discounts, Discount Codes, Discount Groups, Standalone Prices
Product Catalog Messages	Products, Product Selections, Product Tailorings, Categories, Inventory Entries, Reviews, Variants
Quote Messages	Quote Requests, Staged Quotes, Quotes
Shopping List Messages	Shopping Lists
Store Messages	Stores

Enable querying Messages via the API

To optimize the performance of your Project, Messages are not persisted by default. To access Messages via the API, you must first enable the feature in the Settings > Developer Settings section of the Merchant Center. Alternatively, you can use the Change Messages Configuration update action.

Get Message

GET

https://api.{region}.commercetools.com/{projectKey}/messages/{id}

Deprecated OAuth 2.0 Scope: view_orders:{projectKey}

OAuth 2.0 Scopes:

view_messages:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the Message.

Query parameters:

expand

String

Use to expand resources in a single request.

For more information, see Reference Expansion.

The parameter can be passed multiple times.

Response:

200

Message

application/json

curl --get https://api.{region}.commercetools.com/{projectKey}/messages/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

{
  "id": "2723ca8f-283c-4add-90bc-0978d195ed3c",
  "version": 1,
  "sequenceNumber": 4,
  "resource": {
    "typeId": "payment",
    "id": "e57c8183-eb2b-4bf3-acf1-f8a7846689f8"
  },
  "resourceVersion": 5,
  "resourceUserProvidedIdentifiers": {
    "key": "e57-payment-key"
  },
  "type": "PaymentStatusInterfaceCodeSet",
  "paymentId": "e57c8183-eb2b-4bf3-acf1-f8a7846689f8",
  "interfaceCode": "InterfaceCodeString",
  "createdAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedAt": "1970-01-01T00:00:00.001Z",
  "lastModifiedBy": {
    "clientId": "ey8aTsYwE0_kxFvT1rJeglpC",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "ey8aTsYwE0_kxFvT1rJeglpC",
    "isPlatformClient": false
  }
}

Query Messages

GET

https://api.{region}.commercetools.com/{projectKey}/messages

Deprecated OAuth 2.0 Scope: view_orders:{projectKey}

OAuth 2.0 Scopes:

view_messages:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

`where` String	Use to filter query responses. For more information, see Query Predicates. The parameter can be passed multiple times.
`sort` String	Use to sort query results. For more information, see Sorting. The parameter can be passed multiple times.
`expand` String	Use to expand resources in a single request. For more information, see Reference Expansion. The parameter can be passed multiple times.
`limit` Int32	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int32	Number of elements skipped. Default: `0` Maximum: `10000`
`withTotal` Boolean	Controls the calculation of the total number of query results. Set to `false` to improve query performance when the `total` is not needed. Default: `true`
`var.<varName>` String	Predicate parameter values. The parameter can be passed multiple times.

Response:

200

MessagePagedQueryResponse

application/json

curl --get https://api.{region}.commercetools.com/{projectKey}/messages -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "2723ca8f-283c-4add-90bc-0978d195ed3c",
      "version": 1,
      "sequenceNumber": 4,
      "resource": {
        "typeId": "payment",
        "id": "e57c8183-eb2b-4bf3-acf1-f8a7846689f8"
      },
      "resourceVersion": 5,
      "resourceUserProvidedIdentifiers": {
        "key": "e57-payment-key"
      },
      "type": "PaymentStatusInterfaceCodeSet",
      "paymentId": "e57c8183-eb2b-4bf3-acf1-f8a7846689f8",
      "interfaceCode": "InterfaceCodeString",
      "createdAt": "1970-01-01T00:00:00.001Z",
      "lastModifiedAt": "1970-01-01T00:00:00.001Z",
      "lastModifiedBy": {
        "clientId": "ey8aTsYwE0_kxFvT1rJeglpC",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "ey8aTsYwE0_kxFvT1rJeglpC",
        "isPlatformClient": false
      }
    }
  ]
}

Check if Message exists

Check if Message exists by ID

HEAD

https://api.{region}.commercetools.com/{projectKey}/messages/{id}

Checks if a Message exists with the provided id. Returns a 200 status if the Message exists, or a 404 status otherwise.

OAuth 2.0 Scopes:

view_messages:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the Message.

Response:

200

curl --head https://api.{region}.commercetools.com/{projectKey}/messages/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Message exists by Query Predicate

HEAD

https://api.{region}.commercetools.com/{projectKey}/messages

Checks if one or more Messages exist for the provided query predicate. Returns a 200 status if any Messages match the query predicate, or a 404 status otherwise.

OAuth 2.0 Scopes:

view_messages:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

where

String

Use to filter query responses.

For more information, see Query Predicates.

Query Predicates on Messages are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.

Response:

200

curl --head https://api.{region}.commercetools.com/{projectKey}/messages -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Representations

Message

MessagePagedQueryResponse

UserProvidedIdentifiers -ContainerAndKey

Message

Base representation of a Message containing common fields to all Message Types.

`id` String	Unique identifier of the Message. Can be used to track which Messages have been processed.
`version` Int64	Version of a resource. In case of Messages, this is always `1`.
`sequenceNumber` Int64	Message number in relation to other Messages for a given resource. The `sequenceNumber` of the next Message for the resource is the successor of the `sequenceNumber` of the current Message. Meaning, the `sequenceNumber` of the next Message equals the `sequenceNumber` of the current Message + 1. `sequenceNumber` can be used to ensure that Messages are processed in the correct order for a particular resource.
`resource` Reference	Reference to the resource on which the change or action was performed.
`resourceVersion` Int64	Version of the resource on which the change or action was performed.
`type` String	Message Type of the Message.
`resourceUserProvidedIdentifiers` UserProvidedIdentifiers	User-provided identifiers of the resource, such as `key` or `externalId`. Only present if the resource has such identifiers.
`createdAt` DateTime	Date and time (UTC) the Message was generated.
`createdBy`BETA CreatedBy	IDs and references that created the Message.
`lastModifiedAt` DateTime	Value of `createdAt`.
`lastModifiedBy`BETA LastModifiedBy	IDs and references that last modified the Message.

Message fields that can be used in query predicates: createdAt, lastModifiedAt, id, version, sequenceNumber, resource, resourceVersion, type.

MessagePagedQueryResponse

PagedQueryResult with results containing an array of Message.

`limit` Int64	Number of results requested. Default: `20`Minimum: `0`Maximum: `500`
`count` Int64	Actual number of results returned.
`total` Int64	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.
`offset` Int64	Number of elements skipped. Default: `0`Maximum: `10000`
`results` Array of Message	Messages matching the query.

UserProvidedIdentifiers

User-provided identifiers present on the resource for which the Message is created. The value of the identifier stored in the Message corresponds to the one that was set on the resource at the version shown in resourceVersion.

`key` String	User-provided unique identifier of the resource.
`customerNumber` String	User-provided unique identifier of a Customer.
`externalId` String	User-provided unique identifier of the resource.
`orderNumber` String	User-provided unique identifier of an Order.
`sku` String	Unique SKU of a Product Variant.
`slug` LocalizedString	Unique identifier usually used in deep-link URLs for a Product. The value corresponds to the slug in the `current` Product Projection.
`containerAndKey` ContainerAndKey	Unique identifier of a Custom Object.

ContainerAndKey

ContainerAndKey is specific to Custom Objects. Custom Objects are grouped into containers, which can be used like namespaces. Within a given container, a user-defined key can be used to uniquely identify resources.

`key` String	User-defined identifier that is unique within the given container.
`container` String	Namespace to group Custom Objects.

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

Enable querying Messages via the API.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

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

Check if Message exists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if Message exists by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Check if Message exists by Query Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

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

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

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

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

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

Message Types

Enable querying Messages via the API

Get Message

Query Messages

Check if Message exists

Check if Message exists by ID

Check if Message exists by Query Predicate

Representations

Message

MessagePagedQueryResponse

UserProvidedIdentifiers

ContainerAndKey