Docs
kirora.ioJoin the waitlist
Menu

Developers

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.

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.