Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. The Developer Center continues to support Commerce 6.13.0 through 7.4.1.Visit new site

Types of Structured Messages

Types of Structured Messages

Structured messages are created by validation constraints and business rules in the service layer, and by advisors in the API prototype layer. Structured messages are very flexible and can be used to represent a variety of conditions based on the type of the message and how it was generated.

Error Messages

Structured messages with a type field of error are generated in Cortex from field validation errors, business state errors, and non-resolvable blocking conditions.

Field Validation Errors

Field validation errors are generated from service layer constraint violations. Their characteristics are:

  • They are returned on POST and PUT operations with Status Code 400 Bad Request
  • The type is error.
  • The id begins with field..
  • The data field always contains a field-name entry, and may contain other entries depending on the error.
  • There are no blocks or linked-to fields.
Example:
  {
     "type": "error",
     "id": "field.invalid.size",
     "debug-message": "Password must be between 8 to 255 characters inclusive",
     "data": {
        "field-name": "password",
        "min": "8",
        "max": "255"
     }
  }      

See Field Validation Errors for a list of messages returned by Cortex.

Business State Errors

Business state errors are generated by service layer business rules. Their characteristics are:

  • They are returned on POST, PUT and DELETE operations with Status Code 409 Conflict.
  • The type is error.
  • The data field may contain entries that provide additional business context.
  • There may be blocks or linked-to fields if the error is resolvable by the user.
Example:
{
  type: "error", 
  id: "cart.item.not.available", 
  debug-message: "Item '{item-code}' is not available for purchase.", 
  linked-to: {
    uri:    "/availabilities/carts/{scope}/{id}/lineitems/{id}", 
    href: "http://{host}/{context}/availabilities/carts/{scope}/{id}/lineitems/{id}", 
    type: "availabilities.availability-for-cart-line-item"
  }, 
  data: {
    item-code: "physical_product_with_fixed_inventory_sku"
  }
}

See Business State Errors for a list of messages returned by Cortex.

NeedInfo Messages

Structured messages with a type field of needinfo are generated in Cortex from resolvable blocking conditions. A needinfo message indicates that additional information needs to be provided by the user.

Their characteristics are:

  • They are returned on GET operations with Status Code 200 OK, or on POST operations with Status Code 409 Conflict.
  • The type is needinfo.
  • The data field may contain entries that provide additional business context.
  • The blocks field indicates that action that is blocked.
  • The linked-to field indicates the action the user needs to take to resolve the condition.

The following example indicates that a billing address is required in order to submit an order.

  {
    "type": "needinfo",
    "id": "need.billing.address",
    "debug-message": "Billing address is required",
    "data": {
    },
    "blocks": {
      "rel": "submitorderaction"
    },
    "linked-to": {
      "uri": "/orders/{scope}/{id}/billingaddressinfo",
      "href": "https://{host}/{context}/orders/{scope}/{id}/billingaddressinfo",
      "type": "orders.billingaddress-info"
    }
  }          

Informational Messages

Structured Messages with a custom type field are generated in Cortex as a result of an advisor. Custom structured messages can be actionable or non-actionable.

Cortex provides two out of the box informational type fields, information and promotion.

Actionable Informational Messages

Custom structured messages with a linked-to field are actionable. They have the following characteristics:

  • They are returned on GET operations with Status Code 200 OK.
  • The type may be information, promotion, or another custom type.
  • The data field may contain entries that provide additional business context.
  • The linked-to field is present if the message is actionable.

Example:

  {
    "type": "promotion",
    "id": "promo.buy.more.get.one.free",
    "debug-message": "If you purchase 2 more 'AA-12358' items, you get 1 for free.",
    "data": {
      "item-code" : "AA-12358",
      "threshold" : "3",
      "quantity" : "1"
    },
    "linked-to": {
      "uri": "/items/{scope}/{id}/addtocartform",
      "href": "https://{host}/{context}/items/{scope}/{id}/addtocartform",
      "type": "carts.line-item"
    }
  }

Non-Actionable Informational Messages

Custom structured messages without a linked-to field are non-actionable. Otherwise, they have the same characteristics as an actionable custom structured message.

Example:

  {
  "type": "promotion",
  "id": "promo.free.shipping",
  "debug-message": "Get free shipping if you buy $5.37 more",
  "data": {
    "amount": "$5.37",
  }
}