Order action schemas

Order action schemas allow you to define custom data structures for dynamic, untyped order data. This makes 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.

This feature is in BETA. This means it might at any time be changed, withdrawn from your account, or become part of a paid add-on module. You might also experience interruptions of this service, degradation of user experience or faulty behavior even in critical processes such as automations and send outs. Voyado welcomes feedback on beta features, and encourages you to try them, but you should not build business critical logic on beta features in Engage. Only when a feature reaches its full release and is no longer tagged as BETA can you trust it to function reliably with no further breaking changes.

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 endpoint /api/v3/orders/{orderId}/action 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.

Example schema

{
  "schemaName": "MyLogisticsPartner",
  "jsonSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "orderCustomData": {
        "type": "object",
        "properties": {
          "longDescription": {
            "type": "string",
            "title": "Order long description",
            "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 toOrder 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}

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": "ConfirmOrder",
  "versionTag": "yirz5f26ziyqyrvcv4d2mdoy4q",
  "language": "en-US",
  "schemaName": "MyLogisticsPartner",
  "data": {
    "orderCustomData": {
      "comment": "Order contains items with different fulfillment statuses. We will ship reserved items as soon as they are available."
    },
    "lineItemCustomData": [
      {
        "id": "item-1",
        "estimatedDelivery": "2026-02-06T09:57:16+01:00",
        "group": "group-1"
      },
      {
        "id": "item-2",
        "estimatedDelivery": "2026-02-26T09:57:16+01:00",
        "group": "group-2"
      }
    ],
    "groupCustomData": [
      {
        "group": "group-1",
        "longDescription": "Reserved — awaiting pick & pack. Estimated delivery: 6 February 2026."
      },
      {
        "group": "group-2",
        "longDescription": "Not avalailable — awaiting stock. Estimated delivery: 26 February 2026."
      }
    ]
  }
}

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

Contacts

Transactions

Orders

Loyalty

Product data

Elevate

Ratings and Reviews

Overview

Why use schemas?

Data structure

How to define schemas

1. Via Config Hub

2. Via the API

Fields in Design Studio

Sending data via API

​Overview

​Why use schemas?

​Data structure

​How to define schemas

​1. Via Config Hub

​2. Via the API

​Fields in Design Studio

​Sending data via API

Overview

Why use schemas?

Data structure

How to define schemas

1. Via Config Hub

2. Via the API

Fields in Design Studio

Sending data via API