Custom attributes

The main functionality of custom attributes in your Order Management System (OMS) is to bring flexibility to the System Integrator (SI) in order to append or modify the relevant information for client-specific requirements.

These features are affected by the custom attributes functionality:

  • Order (at header and lines level)
  • Return (at header and lines level)
  • Refund (at header level)


There are no restrictions in terms of flow or order type. The custom attributes could be changed in any lifecycle of the order.

Modify shipping address If the SI wants to modify the shipping address when the order is already in the logistics stage, you must cancel the shipment request before attempting to change it.


This feature is enabled or disabled per configuration, both integration and the UI is configurable.

For UI privileges, the roles and permissions will bring granularity to enable or disable this functionality for a certain role.

Roles & Permissions


There are separate commands and events to modify each one of the existing entities.

Order level

  • magento.sales.order_management.update_custom_attributes (command)
  • magento.sales.order_management.custom_attributes_updated (event)

Order Line level

  • magento.sales.order_management.update_line_custom_attributes (command)
  • magento.sales.order_management.line_custom_attributes_updated (event)

Return level

  • magento.postsales.return_management.update_custom_attributes (command)
  • magento.postsales.return_management.custom_attributes_updated (event)

Return Line level

  • magento.postsales.return_management.update_line_custom_attributes (command)
  • magento.postsales.return_management.line_custom_attributes_updated (event)

Refund level

  • magento.postsales.refund_management.update_custom_attributes (command)
  • magento.postsales.refund_management.custom_attributes_updated (event)

This example appends a custom attribute for a specific return:

    "return_custom_attributes_modification": {
        "custom_attributes": [
                "name": "newCustomAttribute",
                "value": "value"
        "order_id": "000000023",
        "rma": "RMA-CS-000000023-1",
        "sales_channel_id": "ST1",
        "user": "Username"

When the action is performed successfully our system will generate an event that can be consumed by any integration with the name magento.postsales.return_management.custom_attributes_updated, and with exactly the same content as the previous one.

As this request is a synchronous one, if a failure occurs you will see a response message listing the reason of the non-expected behavior.

The following is an example of a failure response:

    "error": {
        "message":"Feature with name \u0027updateCustomAttributes\u0027, is not enabled.",