# Public Orders Record Event

Report a lifecycle event your system recorded for one order.
Append-only: each POST records one event (e.g. the order was *Cancelled* in
your ERP), so the full partner-side timeline is preserved. Supply
`external_event_id` to make retries idempotent — an identical replay
returns the already-stored event with `200`, a conflicting reuse of the id
is `409`. **Recording-only**: this never changes the order's workflow
status or re-triggers any export. These are events *you* report to Mercura —
not the webhook deliveries Mercura sends you.

Endpoint: POST /orders/{order_id}/events
Version: 1.79.2

## Path parameters:

  - `order_id` (string, required)

## Header parameters:

  - `authorization` (string | null)
    Bearer <mrc_live_…> API key

## Request fields (application/json):

  - `event_type` (string, required)
    Normalised event token: uppercase letters, digits, underscores (e.g. WON, LOST, CANCELLED).

  - `status_label` (string | null)
    The partner's verbatim status label, e.g. 'Cancelled'.

  - `message` (string | null)
    Optional free-text note about the event.

  - `metadata` (object | null)
    Optional extra references / raw payload the partner echoed back for traceability.

  - `external_event_id` (string | null)
    The partner's own id for this event; supplying it makes retries idempotent.

  - `occurred_at` (string | null)
    When the event happened in the partner system (defaults to unreported).

## Response 200:

  - `200` (unknown)
    Idempotent replay: this external_event_id was already recorded

## Response 201:

  - `201` (unknown)
    Successful Response

## Response 201 fields (application/json):

  - `id` (string, required)
    Mercura's id for the recorded event.

  - `event_type` (string, required)
    Normalised partner event token (e.g. WON / LOST / CANCELLED).

  - `status_label` (string | null)
    The partner's verbatim status label.

  - `message` (string | null)
    Free-text note about the event.

  - `metadata` (object | null)
    Optional extra references the partner echoed back.

  - `external_event_id` (string | null)
    The partner's own id for this event, when provided.

  - `occurred_at` (string | null)
    When the event happened in the partner system.

  - `recorded_at` (string, required)
    When Mercura recorded the event (server receipt time).

## Response 400:

  - `400` (unknown)
    Validation failed (e.g. bad event_type, oversized metadata, future occurred_at)

## Response 404:

  - `404` (unknown)
    Order not found

## Response 409:

  - `409` (unknown)
    external_event_id reused with a different payload, or per-request event cap reached

## Response 422:

  - `422` (unknown)
    Validation Error

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

  - `detail.input` (any)

  - `detail.ctx` (object)