# Commerce Events

URL: https://docs.dixa.io/openapi/dixa-api/beta/commerce-events

## Submit commerce event

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

### POST /beta/commerce-events

- Server: https://dev.dixa.io
- Auth: `Authorization: <API token>` header

#### Request example

```bash
curl -X POST 'https://dev.dixa.io/beta/commerce-events' \
  -H 'Authorization: <API token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "eventId": "evt_001",
  "eventTimestamp": "2026-05-08T14:32:11Z",
  "user": {
    "userId": "04a4db4f-cd01-41e2-88cf-32c4b6079f33",
    "_type": "ById"
  },
  "payload": {
    "orderId": "ORD-9981",
    "total": {
      "amount": 8950,
      "currency": "EUR"
    },
    "lineItems": [
      {
        "label": "Leather Derby Shoes",
        "reference": "SHOE-42-BLK",
        "quantity": 1,
        "amount": {
          "amount": 8950,
          "currency": "EUR"
        }
      }
    ],
    "_type": "OrderCreated"
  }
}'
```

#### Response examples

##### 202 Event accepted

No body.

##### 400 Invalid value for: body

```json
{
  "message": "Decoding failure in request"
}
```

##### 404 An entity in this request could not be found

```json
{
  "message": "The requested resource could not be found"
}
```

##### 500 Internal failure during request processing

```json
{
  "message": "There was an internal server error while processing the request"
}
```

## OpenAPI definition

The operation and the schemas used, from the full spec at https://docs.dixa.io/openapi-specs/dixa-beta.yaml. Request and response examples are above.

```yaml
openapi: 3.0.3
info:
  title: Dixa API
  version: beta
servers:
  - url: https://dev.dixa.io
security:
  - ApiKeyAuth: []
paths:
  /beta/commerce-events:
    post:
      tags:
        - Commerce Events
      summary: Submit commerce event
      description: Submit a commerce event for a user (e.g. order lifecycle events for
        conversation routing, sales attribution, and analytics).
      operationId: postCommerce-events
      requestBody:
        description: The commerce event to submit
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommerceEvent"
        required: true
      responses:
        "202":
          description: Event accepted
        "400":
          description: "Invalid value for: body"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequest"
        "404":
          description: An entity in this request could not be found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFound"
        "500":
          description: Internal failure during request processing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerError"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    CommerceEvent:
      title: CommerceEvent
      type: object
      required:
        - eventId
        - eventTimestamp
        - user
        - payload
      properties:
        eventId:
          description: Unique identifier for the event; used for idempotency
          type: string
        eventTimestamp:
          description: When the event occurred in the source system, not when Dixa
            received it
          type: string
          format: date-time
        user:
          $ref: "#/components/schemas/UserReference"
          description: Identifies the user associated with the event.
        author:
          $ref: "#/components/schemas/UserReference"
          description: Identifies the author of the action that triggered the event (e.g.
            a staff member who initiated a refund).
        origin:
          description: Sales channel or platform origin (e.g. web, mobile, pos).
          type: string
        metadata:
          $ref: "#/components/schemas/Map_String"
          description: Optional platform-specific key-value pairs for data that does not
            fit the typed payload.
        payload:
          $ref: "#/components/schemas/CommerceEventPayload"
    UserReference:
      title: UserReference
      oneOf:
        - $ref: "#/components/schemas/ByContactPoints"
        - $ref: "#/components/schemas/ById"
    ByContactPoints:
      title: ByContactPoints
      type: object
      required:
        - displayName
      properties:
        contactPoints:
          description: Contact points used to find or create the user; first match wins
          type: array
          items:
            $ref: "#/components/schemas/ContactPoint"
        displayName:
          description: Display name used when creating a new user; ignored if an existing
            user is found
          type: string
    ContactPoint:
      title: ContactPoint
      oneOf:
        - $ref: "#/components/schemas/Email1"
        - $ref: "#/components/schemas/Phone"
    Email1:
      title: Email
      type: object
      required:
        - value
      properties:
        value:
          description: Email address
          type: string
    Phone:
      title: Phone
      type: object
      required:
        - value
      properties:
        value:
          description: Phone number in E.164 format
          type: string
    ById:
      title: ById
      type: object
      required:
        - userId
      properties:
        userId:
          description: Dixa end-user ID
          type: string
    Map_String:
      title: Map_String
      type: object
      additionalProperties:
        type: string
    CommerceEventPayload:
      title: CommerceEventPayload
      description: Typed event payload. The _type field determines the event variant.
      oneOf:
        - $ref: "#/components/schemas/DeliveryAttemptFailed"
        - $ref: "#/components/schemas/OrderCanceled"
        - $ref: "#/components/schemas/OrderCreated"
        - $ref: "#/components/schemas/OrderDelivered"
        - $ref: "#/components/schemas/OrderDrafted"
        - $ref: "#/components/schemas/OrderFulfilled"
        - $ref: "#/components/schemas/RefundCreated"
        - $ref: "#/components/schemas/ReturnReceived"
        - $ref: "#/components/schemas/ReturnRequested"
    DeliveryAttemptFailed:
      title: DeliveryAttemptFailed
      type: object
      required:
        - orderId
      properties:
        orderId:
          description: External order ID
          type: string
        fulfillmentId:
          description: External fulfillment ID — links back to the fulfillment
          type: string
        reason:
          description: Reason for the failed attempt (e.g. no one home, wrong address)
          type: string
    OrderCanceled:
      title: OrderCanceled
      type: object
      required:
        - orderId
      properties:
        orderId:
          description: External order ID
          type: string
        reason:
          type: string
    OrderCreated:
      title: OrderCreated
      type: object
      required:
        - orderId
        - total
      properties:
        orderId:
          description: External order ID
          type: string
        total:
          $ref: "#/components/schemas/Money"
          description: Total amount of the order, inclusive of tax and discounts
        lineItems:
          type: array
          items:
            $ref: "#/components/schemas/LineItem"
    Money:
      title: Money
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          description: Amount in the smallest currency unit (e.g. cents for EUR/USD, pence
            for GBP)
          type: integer
          format: int64
        currency:
          description: ISO 4217 currency code (e.g. EUR, USD, GBP)
          type: string
    LineItem:
      title: LineItem
      type: object
      required:
        - label
        - quantity
        - amount
      properties:
        label:
          type: string
        reference:
          description: SKU or other external reference for the product
          type: string
        quantity:
          description: Number of units
          type: integer
          format: int32
        amount:
          $ref: "#/components/schemas/Money"
          description: Total amount for this line item, inclusive of tax and discounts
    OrderDelivered:
      title: OrderDelivered
      type: object
      required:
        - orderId
      properties:
        orderId:
          description: External order ID
          type: string
        fulfillmentId:
          description: External fulfillment ID — links back to the fulfillment
          type: string
        lineItems:
          type: array
          items:
            $ref: "#/components/schemas/FulfillmentLineItem"
    FulfillmentLineItem:
      title: FulfillmentLineItem
      type: object
      required:
        - label
        - quantity
      properties:
        label:
          type: string
        reference:
          description: SKU or other external reference for the product
          type: string
        quantity:
          description: Number of units fulfilled
          type: integer
          format: int32
    OrderDrafted:
      title: OrderDrafted
      type: object
      required:
        - orderId
        - total
      properties:
        orderId:
          description: External draft order ID
          type: string
        total:
          $ref: "#/components/schemas/Money"
          description: Total amount of the draft order, inclusive of tax and discounts
        lineItems:
          type: array
          items:
            $ref: "#/components/schemas/LineItem"
        note:
          description: Staff note or reason for the draft
          type: string
    OrderFulfilled:
      title: OrderFulfilled
      type: object
      required:
        - orderId
      properties:
        orderId:
          description: External order ID
          type: string
        fulfillmentId:
          description: External fulfillment ID — useful for partial fulfillments
          type: string
        trackingNumber:
          type: string
        trackingUrl:
          type: string
        lineItems:
          type: array
          items:
            $ref: "#/components/schemas/FulfillmentLineItem"
    RefundCreated:
      title: RefundCreated
      type: object
      required:
        - orderId
        - total
      properties:
        orderId:
          description: External order ID
          type: string
        refundId:
          description: External refund ID — useful for idempotency on partial refunds
          type: string
        total:
          $ref: "#/components/schemas/Money"
          description: Total refund amount, inclusive of tax and discounts
        lineItems:
          type: array
          items:
            $ref: "#/components/schemas/LineItem"
    ReturnReceived:
      title: ReturnReceived
      type: object
      required:
        - orderId
      properties:
        orderId:
          description: External order ID
          type: string
        returnId:
          description: External return ID — links back to the return request
          type: string
        lineItems:
          type: array
          items:
            $ref: "#/components/schemas/FulfillmentLineItem"
    ReturnRequested:
      title: ReturnRequested
      type: object
      required:
        - orderId
      properties:
        orderId:
          description: External order ID
          type: string
        returnId:
          description: External return ID
          type: string
        reason:
          description: Reason for the return
          type: string
        lineItems:
          type: array
          items:
            $ref: "#/components/schemas/FulfillmentLineItem"
    BadRequest:
      title: BadRequest
      type: object
      required:
        - message
      properties:
        message:
          type: string
    NotFound:
      title: NotFound
      type: object
      required:
        - message
      properties:
        message:
          type: string
    ServerError:
      title: ServerError
      type: object
      required:
        - message
      properties:
        message:
          type: string
```