---
title: "Submit commerce event"
method: POST
path: "/beta/commerce-events"
tags: ["Commerce Events"]
---

# Submit commerce event

`POST /beta/commerce-events`

Submit a commerce event for a user (e.g. order lifecycle events for conversation routing, sales attribution, and analytics).

## Request body

- CommerceEvent
  - `eventId` string, required — Unique identifier for the event; used for idempotency
  - `eventTimestamp` string, date-time, required — When the event occurred in the source system, not when Dixa received it
  - `user` union, required
    - ByContactPoints
      - `contactPoints` ContactPoint[] — Contact points used to find or create the user; first match wins
        - union
          - Email1
            - `value` string, required — Email address
          - Phone
            - `value` string, required — Phone number in E.164 format
      - `displayName` string, required — Display name used when creating a new user; ignored if an existing user is found
    - ById
      - `userId` string, required — Dixa end-user ID
  - `author` union
    - ByContactPoints
      - `contactPoints` ContactPoint[] — Contact points used to find or create the user; first match wins
        - union
          - Email1
            - `value` string, required — Email address
          - Phone
            - `value` string, required — Phone number in E.164 format
      - `displayName` string, required — Display name used when creating a new user; ignored if an existing user is found
    - ById
      - `userId` string, required — Dixa end-user ID
  - `origin` string — Sales channel or platform origin (e.g. web, mobile, pos).
  - `metadata` MapString
  - `payload` union, required — Typed event payload. The _type field determines the event variant.
    - DeliveryAttemptFailed
      - `orderId` string, required — External order ID
      - `fulfillmentId` string — External fulfillment ID — links back to the fulfillment
      - `reason` string — Reason for the failed attempt (e.g. no one home, wrong address)
    - OrderCanceled
      - `orderId` string, required — External order ID
      - `reason` string
    - OrderCreated
      - `orderId` string, required — External order ID
      - `total` Money, required
        - `amount` integer, required — Amount in the smallest currency unit (e.g. cents for EUR/USD, pence for GBP)
        - `currency` string, required — ISO 4217 currency code (e.g. EUR, USD, GBP)
      - `lineItems` LineItem[]
        - `label` string, required
        - `reference` string — SKU or other external reference for the product
        - `quantity` integer, required — Number of units
        - `amount` Money, required
          - `amount` integer, required — Amount in the smallest currency unit (e.g. cents for EUR/USD, pence for GBP)
          - `currency` string, required — ISO 4217 currency code (e.g. EUR, USD, GBP)
    - OrderDelivered
      - `orderId` string, required — External order ID
      - `fulfillmentId` string — External fulfillment ID — links back to the fulfillment
      - `lineItems` FulfillmentLineItem[]
        - `label` string, required
        - `reference` string — SKU or other external reference for the product
        - `quantity` integer, required — Number of units fulfilled
    - OrderDrafted
      - `orderId` string, required — External draft order ID
      - `total` Money, required
        - `amount` integer, required — Amount in the smallest currency unit (e.g. cents for EUR/USD, pence for GBP)
        - `currency` string, required — ISO 4217 currency code (e.g. EUR, USD, GBP)
      - `lineItems` LineItem[]
        - `label` string, required
        - `reference` string — SKU or other external reference for the product
        - `quantity` integer, required — Number of units
        - `amount` Money, required
          - `amount` integer, required — Amount in the smallest currency unit (e.g. cents for EUR/USD, pence for GBP)
          - `currency` string, required — ISO 4217 currency code (e.g. EUR, USD, GBP)
      - `note` string — Staff note or reason for the draft
    - OrderFulfilled
      - `orderId` string, required — External order ID
      - `fulfillmentId` string — External fulfillment ID — useful for partial fulfillments
      - `trackingNumber` string
      - `trackingUrl` string
      - `lineItems` FulfillmentLineItem[]
        - `label` string, required
        - `reference` string — SKU or other external reference for the product
        - `quantity` integer, required — Number of units fulfilled
    - RefundCreated
      - `orderId` string, required — External order ID
      - `refundId` string — External refund ID — useful for idempotency on partial refunds
      - `total` Money, required
        - `amount` integer, required — Amount in the smallest currency unit (e.g. cents for EUR/USD, pence for GBP)
        - `currency` string, required — ISO 4217 currency code (e.g. EUR, USD, GBP)
      - `lineItems` LineItem[]
        - `label` string, required
        - `reference` string — SKU or other external reference for the product
        - `quantity` integer, required — Number of units
        - `amount` Money, required
          - `amount` integer, required — Amount in the smallest currency unit (e.g. cents for EUR/USD, pence for GBP)
          - `currency` string, required — ISO 4217 currency code (e.g. EUR, USD, GBP)
    - ReturnReceived
      - `orderId` string, required — External order ID
      - `returnId` string — External return ID — links back to the return request
      - `lineItems` FulfillmentLineItem[]
        - `label` string, required
        - `reference` string — SKU or other external reference for the product
        - `quantity` integer, required — Number of units fulfilled
    - ReturnRequested
      - `orderId` string, required — External order ID
      - `returnId` string — External return ID
      - `reason` string — Reason for the return
      - `lineItems` FulfillmentLineItem[]
        - `label` string, required
        - `reference` string — SKU or other external reference for the product
        - `quantity` integer, required — Number of units fulfilled

## Response `202`

Event accepted

## Other responses

- `400` — Invalid value for: body
- `500` — Internal failure during request processing

---

[API](https://skmtc.net/dixa/apis/dixa-api.md) · [All operations](https://skmtc.net/dixa/apis/dixa-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dixa/dixa-api/versions/041e058483f0/schema)