Data dictionary: order events

See also: Customised data export

Order events data relates to the orders placed by your customers. Each exported record is one order, and includes the order totals, the customer who placed it, the delivery and billing addresses, the individual products in the order, and the Ometria campaign the order is attributed to (if any).

How to read this article

• You choose the fields. An order export contains only the fields you select when you set it up — not everything listed below.
• Empty fields. A field with no data is exported as null in JSON, and as an empty cell in CSV.
• Nested fields. Some fields are objects or lists rather than single values. lineitems is the only one whose individual sub-fields you can pick one by one; totals, shipping_address, billing_address, attribution, extra_identifiers, properties and variant_options are selected as a whole.
• Personal data. Fields marked as containing personal data can be anonymised or renamed when you configure the export, including individual line-item fields.

File formats

Order events can be exported as JSON or CSV.

JSON exports are written as newline-delimited JSON: one complete order object per line, rather than one array wrapping the whole file.

How often an order appears in your export

A scheduled order export includes every order that was created or changed during the run window — not only orders placed in that window.

This means an order you have already received can appear again in a later file. For example, an order placed in January and refunded in March is included in both the January file (as placed) and the March file (with the refund applied). Its timestamp does not change, because that is always the time the order was placed.

Backfills

You can backfill historical orders as far back as your account's data retention period allows. If your account has no retention limit, you can backfill your full order history. Your Customer Success Representative can tell you what applies to your account.

Order details

Campaign attribution

These fields show which of your Ometria campaigns the order is attributed to, using Ometria's standard order attribution logic. They are empty when the order isn't attributed to a campaign. They come from Ometria's email attribution and are not part of the Ometria Order API.

See also: Email order attribution

Customer details

These fields describe the contact the order is linked to in Ometria. An order that could not be matched to a contact — for example a guest checkout with no usable identifier — exports these fields as null.

Addresses

Both address fields are single objects containing the four sub-fields below. They are selected as a whole, not sub-field by sub-field. Both contain personal data.

Session and traffic attribution

attribution is a single object describing the browsing session the order came from. It is selected as a whole, not sub-field by sub-field. It is separate from Campaign attribution, which reports the Ometria campaign the order is credited to.

"attribution": {"session_id": "b2f1c9e0", "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "winter_sale", "utm_content": "hero_cta", "utm_terms": null, "device_type": "mobile", "referring_domain": "mail.google.com"}

Line items

Each order has a lineitems field: a list of the individual products in that order, with one entry per product. Unlike the other nested fields, you can select line-item fields individually — tick Line item to include them all, or pick only the ones you need.

Example record

One line of a JSON order export, with every field selected:

{
  "id": "ORD-58211",
  "timestamp": "2026-09-10T14:32:00+00:00",
  "customer_id": "546548",
  "email": "sample@ometria.com",
  "firstname": "John",
  "lastname": "Smith",
  "phone_number": "+447700900123",
  "profile_hash": "8cdcf152e871646a",
  "campaign_name": "Winter Sale",
  "variant_name": "Variation B",
  "subtotal": 91.41,
  "discount": 10.00,
  "tax": 11.41,
  "shipping": 4.99,
  "grand_total": 96.40,
  "total_refunded": 0.00,
  "total_unit_quantity": 2,
  "total_unit_quantity_refunded": 0,
  "currency": "GBP",
  "totals": {
    "base": {"subtotal": 91.41, "discount": 10.00, "shipping": 4.99, "tax": 11.41, "grand_total": 96.40, "refunded": 0.00, "currency": "GBP"},
    "local": {"subtotal": 106.03, "discount": 11.60, "shipping": 5.79, "tax": 13.24, "grand_total": 111.82, "refunded": 0.00, "currency": "EUR"}
  },
  "status": "complete",
  "is_valid": true,
  "channel": "online",
  "store": "uk-web",
  "coupon_code": "SAVE10",
  "shipping_method": "standard",
  "payment_method": "card",
  "web_id": "58211-web",
  "ip_address": "203.0.113.42",
  "extra_identifiers": [{"type": "loyalty_id", "value": "LOY-7898734"}],
  "shipping_address": {"city": "London", "state": "Greater London", "postcode": "W1K 4TG", "country_code": "GB"},
  "billing_address": {"city": "London", "state": "Greater London", "postcode": "W1K 4TG", "country_code": "GB"},
  "attribution": {"session_id": "b2f1c9e0", "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "winter_sale", "utm_content": "hero_cta", "utm_terms": null, "device_type": "mobile", "referring_domain": "mail.google.com"},
  "properties": {"gift_wrap": "true"},
  "lineitems": [
    {
      "product_id": "SS14-059493",
      "variant_id": "SS14-059493-S5",
      "sku": "SS14-059493-S5",
      "quantity": 2,
      "quantity_refunded": 0,
      "unit_price": 50.00,
      "subtotal": 100.00,
      "discount": 10.00,
      "tax": 0.00,
      "total": 90.00,
      "refunded": 0.00,
      "currency": "GBP",
      "is_on_sale": true,
      "variant_options": [{"type": "size", "id": "large", "label": "Large"}],
      "totals": {
        "base": {"subtotal": 100.00, "discount": 10.00, "tax": 0.00, "total": 90.00, "unit_price": 50.00, "refunded": 0.00, "currency": "GBP"},
        "local": {"subtotal": 116.00, "discount": 11.60, "tax": 0.00, "total": 104.40, "unit_price": 58.00, "refunded": 0.00, "currency": "EUR"}
      },
      "properties": {"engraving": "J.S."}
    }
  ]
}