Documentation

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 pageRepresented resources
Approval Rule and Approval Flow MessagesApproval Rules, Approval Flows
Business Unit and Associate Role MessagesBusiness Units, Associate Roles
Customer MessagesCustomers, Customer Tokens, Customer Groups
Order and Payment MessagesOrders, Order Edits, Payments
Pricing and Discount MessagesCart Discounts, Discount Codes, Standalone Prices
Product Catalog MessagesProducts, Product Selections, Product Tailorings, Categories, Inventory Entries, Reviews
Quote MessagesQuote Requests, Staged Quotes, Quotes
Shopping List MessagesShopping Lists
Store MessagesStores

Representations

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​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: 10 000​
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.
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​
offset
​
Int
​

Number of elements skipped.

Default: 0​
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:
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}"