Order Management System (OMS) reached end of support in October 2024.
The documentation available here is intended for historical reference only and is not maintained.
For other Commerce-related documentation, see Adobe Commerce Documentation.

Custom attributes

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

Features affected by the custom attributes functionality include:

  • Order—header and lines level
  • Return—header and lines level
  • Refund—header level

Standard custom attributes

Any custom attributes can be configured for any client/merchant, and each must have a defined supported type.

The following are available standard custom attributes:

  • Order
  • Order item
  • Address
  • Payment
  • Return
  • Return line

Supported attribute types

The following are supported custom attribute types and are validated against configured attributes:

  • string—No check; you may specify a regular expression if you want to implement a check
  • integer—Only contains numbers with no decimal value (no comma separator)
  • float—Only contains numbers with a decimal value (zero, comma, or point separators)
  • enum—Pre-defined list of accepted values; must be configured in the System Integrator (SI) Portal

Restrictions

There are no restrictions in terms of flow or order type. Custom attributes can be changed during any lifecycle of the order.

Configuration

The Custom attributes field is completely customizable to your individual needs, and can be enabled or disabled per configuration, for both the integration and the user interface (UI).

You can use custom attributes at the order or order item levels, managed directly in the OMS Admin, to enable the addition of info to orders at specific moments during the order lifecycle.

Proper configuration for custom attributes can be done before launch by your Technical Account Manager (TAM) so that we can validate the info you are sending matches types configured in the SI Portal. To make these changes after launch, you must create a ticket in the Support portal to request assistance.

If the custom attribute value does not match the specified type the order is rejected and you will see an explicit error/warning message in the user interface (UI). If, for instance, you implement custom address modification via the API and the value does not match the specified attribute type, you will see a warning message.

Enable functionality for user

You can modify roles (permissions) in the OMS Admin to enable or disable this functionality for a user.

To create a new role with custom attribute permissions:

  1. In the OMS Admin, click System > Roles.
  2. Add a name and hierarchy level. See more info about configuring users and roles in our Permissions user guide.

  3. In the Order Modification section, tick/select the Update Custom Attributes option and click Create.

    Enable custom attributes modification

    Order Modification section system settings

See our Permissions user guide to learn about managing permissions and roles, and applying those to existing users.

Show custom attributes in order grid

You can change the configuration of the order grid to show columns for each custom attribute you want to view, per order.

To enable custom attribute visibility in the order grid:

  1. Click Sales > Orders in the OMS Admin.
  2. Click the downward pointing arrow of the Columns option near the top of the page.

  3. Tick the attribute in the Order Custom Attributes section that you want to be visible in the order grid below, and click Save.

    Enable custom attribute visibility in order grid

    Enable custom attribute visibility in order grid

    Now, the order grid shows a column for that custom attribute. Any orders with that custom attribute will show a value in that column.

The custom attributes column is refreshed every hour. Changes are not immediately reflected in this view.

Add or edit attributes

You can create a new, or edit an existing, custom attribute via the OMS Admin or with a custom message.

Proper configuration for custom attributes can be done by your Technical Account Manager (TAM) in your SI Portal—this is optional but recommended.

To create a new custom attribute based on a predefined type in the OMS Admin:

  1. Click Sales > Orders in the OMS Admin.
  2. Ensure the desired custom attribute is visible in the order grid.
  3. Click the open an order, in the Order ID column, that contains the desired custom attribute.
  4. In the General Information section, click Edit (adjacent to the Custom attributes line indicating how many custom attributes exist for the order).
  5. In the Edit Custom Attributes view that opens, edit any existing attribute as applicable.
  6. Click Add a new custom attribute to add a new one:
    1. Select the attribute name from the available dropdown menu.
    2. In the second dropdown that populates, based on your first selection, choose the applicable value, key/value pair, etc.

    3. Click Save.

      Create a new, or edit an existing, custom attribute

      Create a new, or edit an existing, custom attribute

      You can also add or edit custom attributes, using the same process, in the Customer Service > Orders page.

To create a new custom attribute, using a custom message, based on a predefined type:

{
  "category": "Customizations",
  "description": "Definition of the predefined Custom Attributes",
  "title": "Custom attributes",
  "type": "object",
  "targetScopeTypes": ["CLIENT"],
  "securityTypes": ["SYSTEM_INTEGRATOR", "ADMIN"],
  "properties": {
    "addressLevel": {
      "title": "Address level",
      "description": "List of predefined custom attributes for the Address entity",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "title": "Attribute Name",
            "description": "Key that will identify the custom attribute",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "description": "Type of the custom attribute being defined",
            "type": "string",
            "enum": [
              "integer",
              "float",
              "enum",
              "string"
            ]
          },
          "enumValues": {
            "title": "Enum Values",
            "description": "List of allowed values (only for custom attributes of type 'enum')",
            "type": "array",
            "default": [],
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["key", "type"],
        "additionalProperties": false
      }
    },
    "orderLevel": { . . . },        // contains the same definition as addressLevel
    "orderItemLevel": { . . . },    // contains the same definition as addressLevel
    "paymentLevel": { . . . },      // contains the same definition as addressLevel
    "returnLevel": { . . . },       // contains the same definition as addressLevel
    "returnLineLevel": { . . . }    // contains the same definition as addressLevel
  },
  "additionalProperties": false
}

Filter by attribute

You can quickly filter orders in the OMS Admin by custom attributes, one or multiple, at the order level.

To filter orders based on custom attribute:

  1. Click Sales > Orders in the OMS Admin.
  2. Click the downward pointing arrow just to the right of the Hide Filters option near the top of the page.

  3. Tick the Order Custom Attribute option (or ensure it has already been ticked) and click Save. This filter is hidden by default, so you must ensure that it is a visible field.

    Enable the custom attribute filter

    Enable custom attribute filter

  4. Choose From date and To date entries, Order status reason, Shipping method, and more, as applicable.
  5. Select a custom attribute from the Order Custom Attribute options.

  6. In the next selection field, select an attribute criteria from the available options.

    Select custom attribute filter criteria

    Filter by custom attribute

  7. Continue choosing custom attributes by which to filter, if you want to use more than one.
  8. Click Apply. Your rendered results, based on search criteria, will appear in a list below.

You can also filter by custom attribute, using the same process, in the Customer Service > Orders page.

The custom attributes filter is refreshed every hour. Changes are not immediately reflected in this view.

Hide custom attribute filter

Just as you enable the custom attribute filter, as detailed in the above Filter by attribute steps, you can also disable it from view.

The filter is hidden by default, so you must configure it to show or be hidden as needed.

To hide the custom attribute filter:

  1. Click the downward pointing arrow just to the right of the Hide Filters option near the top of the page.
  2. Deselect/un-tick the Order Custom Attribute option and click Save.

Integration

The following commands and events modify each 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)

When the following action is performed, 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.

Example of appending a custom attribute for a 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"
    }
}

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

Example of a failure response

{
    "jsonrpc":"2.0",
    "id":1,
    "error": {
        "message":"Feature with name \u0027updateCustomAttributes\u0027, is not enabled.",
        "code":-32602
    }
}
© 2024 Adobe. All rights reserved.