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 querying the API, or by subscribing to them with a Subscription. To query them using the API, you must enable the feature first.

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	Approval Rules, Approval Flows
Business Unit and Associate Role Messages	Business Units, Associate Roles
Customer Messages	Customers, Customer Tokens, Customer Groups
Order and Payment Messages	Orders, Order Edits, Payments
Pricing and Discount Messages	Cart Discounts, Discount Codes, Standalone Prices
Product Catalog Messages	Products, Product Selections, Product Tailorings, Categories, Inventory Entries, Reviews
Quote Messages	Quote Requests, Staged Quotes, Quotes
Store Messages	Stores

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` Int	Version of a resource. In case of Messages, this is always `1`.
`sequenceNumber` Int	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` Int	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` Int	Number of results requested.
`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.
`offset` Int	Number of elements skipped.
`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.

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

Expansion

The parameter can be passed multiple times.

Response:

200Messageasapplication/json

Request Example:cURL

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

200 Response Example: Messagejson

{
  "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` QueryPredicate	The parameter can be passed multiple times.
`/^var[.][a-zA-Z0-9]+$/` Any string parameter matching this regular expression	Predicate parameter values. The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested.
`offset` Int	Number of elements skipped.
`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`

Response:

200MessagePagedQueryResponseasapplication/json

Request Example:cURL

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

200 Response Example: MessagePagedQueryResponsejson

{
  "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 for a given id. Returns a 200 OK status if the Message exists or a 404 Not Found 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

Request Example:cURL

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 a Message exists for a given Query Predicate. Returns a 200 OK status if any Messages match the Query Predicate or a 404 Not Found 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

QueryPredicate

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

Request Example:cURL

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