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

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

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, examples of which are shown below.

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 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:
  {
     "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 data field may contain entries that provide additional business context.
  • There are no blocks or linked-to fields.
Example:
  {
    "id": "profile.email.already.exists",
    "debug-message": "Customer with the given email address 'yoda@force.net' already exists.",
    "data": {
      "email": "yoda@force-net"
    }
  }

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

Resolvable Blocking Conditions

Resolvable blocking messages are presented to the user when a required condition is not met. They prohibit (block) an action from being taken until that condition is met through the user's intervention. Their characteristics are:

  • They are returned on GET operations with Status Code 200 OK, or on POST operations with Status Code 409 Conflict.
  • 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. 

  {
    "id": "information.required",
    "debug-message": "Billing address is required",
    "data": {
    },
    "blocks": {
      "rel": "submitorderaction"
    },
    "linked-to": {
      "uri": "/commerce-legacy/orders/{scope}/{id}/billingaddressinfo",
      "href": "https://{host}/{context}/orders/{scope}/{id}/billingaddressinfo",
      "type": "controls.selector"
    }
  }
Note:

Resolvable blocking conditions have previously been modelled by needinfo controls. In future releases, these will be replaced by the equivalent structured messages as resources are converted to Helix. A compatibility flag exists that will translate blocking structured messages into needinfo controls if desired.

Non-resolvable Blocking Conditions

Non-resolvable blocking messages are presented to the user when a required condition is not met, and an action cannot be identified to help the user resolve the error. Their characteristics are:

  • They are returned on GET operations with Status Code 200 OK, or on POST operations with Status Code 409 Conflict.
  • The data field may contain entries that provide additional business context.
  • The blocks field indicates that action that is blocked.
  • There is no linked-to field.

The following example indicates that an item in the shopping cart is now out of stock and the order cannot be submitted.

  {
    "id": "item.out.of.stock",
    "debug-message": "Item 'AA-12358' is not in stock",
    "data": {
      "item-code" : "AA-12358",
    },
    "blocks": {
      "rel": "submitorderaction"
    }
  }

Informational Messages

Informational messages are non-blocking and provide information to the user to enrich their experience. Informational messages that have a linked-to field are actionable, otherwise they are non-actionable. Their characteristics are:

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

Here is an example of an actionable promotion where the provided link is to an add to cart form.

  {
    "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": "/commerce-legacy/items/{scope}/{id}/addtocartform",
      "href": "https://{host}/{context}/items/{scope}/{id}/addtocartform",
      "type": "carts.line-item"
    }
  }
And this is an example of a non-actionable message.
  {
    "id": "promo.free.shipping",
    "debug-message": "Get free shipping if you buy $5.37 more",
    "data": {
      "amount": "$5.37",
    }
  }