# E-commerce events

The standard commerce event names and properties, and payments from a connected provider

Journeys, segments and conversion goals work with any event name you track. For commerce,
use these six names so starter journeys, goal pickers and future store integrations line
up with your data. They follow Segment's e-commerce v2 spec, and `GET /events/names`
returns them as `suggestedNames` before you have sent any.

| Event | When |
| --- | --- |
| `Product Viewed` | A customer opens a product page |
| `Product Added` | A product goes into the cart |
| `Checkout Started` | The customer begins checkout |
| `Order Completed` | Payment succeeds |
| `Order Refunded` | An order is refunded, in full or in part |
| `Order Cancelled` | An order is cancelled |

## Properties

| Property | Type | Notes |
| --- | --- | --- |
| `order_id` | string | Your order or payment reference |
| `total` | number | In **major units**: dollars, not cents |
| `currency` | string | ISO 4217, such as `USD` or `EUR` |
| `products` | array | Optional: `{ product_id, name, price, quantity }` per line |

A conversion goal on `Order Completed` with `valueProperty: "total"` and
`currency: "USD"` reports revenue for the campaign or journey that drove the order.
An order whose own `currency` is not `USD` still counts as a conversion, but adds no
revenue: amounts are never converted between currencies.

```bash
curl https://api.kirora.io/v1/events/track \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: order-10042" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "customer-881",
    "eventName": "Order Completed",
    "properties": { "order_id": "10042", "total": 125.5, "currency": "USD" }
  }'
```

Use the order ID in the `Idempotency-Key` so a retried request records the order once.
Name the customer by `contactId`, `externalId` or `email` (exactly one). To backfill
history, `POST /v1/events/batch` takes up to 100 orders at once, each with its own
`idempotencyKey`. Give each order its real time in `occurredAt`, or it is recorded as
happening now. It is an ISO 8601 timestamp with `Z` or an offset (`+01:00`), at most 24
hours ahead.

## Payment providers

Payments from a connected payment provider need no code. Once the workspace owner connects
the provider in Settings › Integrations, each successful charge becomes an `Order Completed`
on the paying customer, found or created by email (without marketing consent), with
`order_id` set to the provider's payment reference and `total` in the currency's major
unit. A charge the provider redelivers is recorded once.