Order action schemas

Order action schemas allow you to define custom data structures for dynamic, untyped order data, making it possible to access and display external data fields in your Design Studio templates. This is especially useful for communicating logistics data like group-level tracking URLs, estimated delivery dates, or metadata that isn’t part of the default order entity.

Overview

Order action schemas enable developers to define reusable schemas that will be used to validate and structure the dynamic data sent as part of an order action.

These schemas can be defined either via Config Hub or through the API
The schema is referenced when sending data to the /api/v3/orders/{orderId}/action endpoint or when embedding action data via another endpoint when updating an order.
The dynamic fields defined in a schema are made available directly in the Design Studio, enabling editors to insert these fields safely into order-related messages.

Why use schemas?

Previously, untyped custom data sent to the order action endpoint could only be referenced in classic email design themes. With the transition to the Design Studio, a stricter way to define and validate this data was needed. Schemas solve this problem by:

Providing structure and validation for external systems pushing data into Engage
Enabling safe and intuitive use of dynamic fields in the Design Studio UI
Supporting different data scopes such as order level, line-item level, or delivery-group level

Data structure

An Order Action Schema supports three levels of dynamic data:

orderCustomData: Metadata tied to the order as a whole.
lineItemCustomData: Data per individual order line item.
groupCustomData: Group-level data (such as tracking per delivery group).

Each of these levels must be defined in the schema. If any are missing, the schema will not be accepted. As of now, only fields of type “string” are supported across all three data levels.

Other JSON Schema types such as numbers, booleans, arrays, or nested objects are not supported yet and should not be used in Order Action Schemas. Any non-string values sent in the payload will be converted to strings before being exposed in the Design Studio. This limitation ensures predictable behavior and consistent handling of dynamic data in order communication templates.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "orderCustomData": {
      "type": "object",
      "properties": {
        "comment": {
          "type": "string",
          "title": "Order comment",
          "description": "Free-text comment needed for the transactional emails"
        }
      }
    },
    "lineItemCustomData": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "title": "Line item id",
          "description": "Id used to map data to an order line item"
        },
        "estimatedDelivery": {
          "type": "string"
        }
      },
      "required": ["id"]
    },
    "groupCustomData": {
      "type": "object",
      "properties": {
        "group": {
          "type": "string",          
          "title": "Identifier for the group",
          "description": "Used to map additional custom data to a group on the order"
        },
        "longDescription": {
          "type": "string"
        }
      },
      "required": ["group"]
    }
  }
}

How to define schemas

You can define order action schemas in two ways:

1. Via Config Hub

In the Config Hub, navigate to Order action schemas
Click Add schema
Paste your JSON schema and name the integration schema
Press Save to make the fields available in Design Studio

2. Via the API

You can use the following endpoints to manage schemas programmatically:

List all schemas

GET /api/v3/order-action-schemas

Get a schema by ID

GET /api/v3/order-action-schemas/{id}

Get a schema by name

GET /api/v3/order-action-schemas/by-name/{name}

Create a new schema

POST /api/v3/order-action-schemas

Update an existing schema

PUT /api/v3/order-action-schemas/{id}

Remove a schema

DELETE /api/v3/order-action-schemas/{id}

Requirements

Each schema must include all three top-level keys:

orderCustomData
lineItemCustomData
groupCustomData

The line item and group schemas must include the fields id and group and they need to be marked as “required”.

Fields in Design Studio

Once a schema is in place and referenced in an order action, its fields will be available in the Design Studio UI under Custom data:

Order - Custom data
Line items - Custom data
Groups - Custom data

Sending data via API

When performing an order action (for example “confirmShipment”), pass your custom data along with a schemaName reference:

POST /api/v3/orders/{orderId}/action

Payload example:

{
  "action": "confirmShipment",
  "versionTag": "abc123",
  "schemaName": "MyLogisticsPartner",
  "data": {
    "orderCustomData": { "comment": "Deliver to side door" },
    "lineItemCustomData": {
      "item-1": {
        "id": "item-1",
        "estimatedDelivery": "2026-01-09"
      }
    },
    "groupCustomData": {
      "group-1": {
        "group": "group-1",
        "longDescription": "Delivery via warehouse A"
      }
    }
  }
}

If validation against the schema fails, the API will return a 400 Bad Request along with a list of issues.

In this section: