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 B2B	Approval Rules, Approval Flows
Business Unit and Associate Role Messages B2B	Business Units, Associate Roles
Cart and Order Messages	Carts, Orders, Recurring Orders, Order Edits
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
Quote Messages	Quote Requests, Staged Quotes, Quotes
Shopping List Messages	Shopping Lists
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. Default: `20`Minimum: `0`Maximum: `500`
`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. 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.

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:

200

Message

application/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.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	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

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

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

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}"

Messages

Message Types.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;}

Message.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;}

UserProvidedIdentifiers.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;}

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;}

Get Message.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;}

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;}

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;}

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;}

Message Types

Representations

Message

MessagePagedQueryResponse

UserProvidedIdentifiers

ContainerAndKey

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