Reporting lifecycle events

• POST /orders/{order_id}/events — report a lifecycle event your own system recorded for an order after the initial acknowledgement: the order was Cancelled, Reopened, and so on. Unlike an acknowledgement (one latest-wins outcome), events are append-only — one row per report — so the full timeline is preserved.
• Send an event_type (a normalised token: uppercase letters, digits, and underscores, e.g. CANCELLED / REOPENED), and optionally a status_label (your verbatim label), a message, an occurred_at, and any metadata.
• Supply an external_event_id to make retries safe: reposting the same id with the same payload returns the already-stored event with 200, while reusing the id with a different payload is a 409. Without it, every call records a new event.
• The response is the recorded event — { id, event_type, status_label, message, metadata, external_event_id, occurred_at, recorded_at } — with 201 for a newly recorded event.
• Recording-only: reporting an event never changes the order's workflow status or re-triggers an export. These are events you report to Mercura — not the webhook deliveries Mercura sends you (see the Webhooks chapter).

PATCH /orders is planned for a later release.