---
title: "Add custom event to order"
method: POST
path: "/v1/order/{id}/events"
tags: ["Order"]
---

# Add custom event to order

`POST /v1/order/{id}/events`

## Request

- Base URL: `https://api.sandbox.usenash.com`
- URL: `https://api.sandbox.usenash.com/v1/order/{id}/events`
- Auth: none declared

Add a custom event to an order's event timeline. Rate limited to 3 requests per second per order with a max payload of 1KB.

## Path parameters

- `id` string, required: Unique reference number for the order: either order.id (starts with "ord_") or order.externalId

## Request body

- AddEventInputSerializer: Expected payload for the add event endpoint. Exactly one of ``name`` / ``customEventDefinitionId`` / ``customEventDefinitionKey`` must be supplied — none-set and more-than-one-set are rejected with ``CUSTOM_EVENT_DEFINITION_REFERENCE_INVALID``. None can be marked required here, so that rule is enforced by the service layer (``resolve_custom_event_reference``) rather than by this schema.
  - `name` string, nullable: A free-form event name. Mutually exclusive with customEventDefinitionId and customEventDefinitionKey.
  - `customEventDefinitionId` string, nullable: The id of a pre-defined custom event in your org's catalog. The definition's immutable key becomes the event name. Mutually exclusive with name and customEventDefinitionKey.
  - `customEventDefinitionKey` string, nullable: The key of a pre-defined custom event in your org's catalog (the Event key shown under Orchestrate > Custom Events in the Portal). Resolves to that definition and emits the key as the event name. Mutually exclusive with name and customEventDefinitionId.
  - `timestamp` string, nullable: The event time in UTC in the form 'YYYY-MM-DDTHH:MM:SSZ'. Defaults to now.
  - `payload` object, nullable

## Response `200`

OK

- AddEventOutputSerializer
  - `event` EventOutputPayload, required
    - `id` string, required
    - `eventName` string, required
    - `orderId` string, required
    - `payload` object, nullable
    - `eventCreatedAt` string, required

## Other responses

- `422`: Unprocessable Content

---

[API](https://skmtc.dev/nash/apis/nash-api.md) - [All operations](https://skmtc.dev/nash/apis/nash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nash/apis/nash-api/revisions/e3713837c5c9?raw)