Canonical event reference

Event names, reliability, transport eligibility, payload fields, and validated examples for schema version 1.

This reference describes canonical event schema version 1. Event names are append-only within the version. Each app receives only the events and top-level payload fields selected in its installed release.

Event

Name

Category

Reliability

Delivery

Description

session_started

Session started

Browsing

observation

Browser, Server

A new storefront browsing session began.

page_view

Page viewed

Browsing

observation

Browser, Server

A storefront page was viewed.

product_viewed

Product viewed

Browsing

observation

Browser, Server

A product detail page was viewed.

search

Search performed

Browsing

observation

Browser, Server

A shopper submitted a storefront search.

cart_add

Cart item added

Cart and wishlist

durable

Browser, Server

A cart line was added or its quantity increased.

cart_update

Cart item updated

Cart and wishlist

durable

Browser, Server

A cart line quantity was changed.

cart_remove

Cart item removed

Cart and wishlist

durable

Browser, Server

A cart line was removed or its quantity decreased.

wishlist_add

Wishlist item added

Cart and wishlist

durable

Browser, Server

A product or variant was added to a wishlist.

wishlist_remove

Wishlist item removed

Cart and wishlist

durable

Browser, Server

A product or variant was removed from a wishlist.

begin_checkout

Checkout started

Checkout and orders

durable

Browser, Server

A checkout was created from a validated cart.

purchase

Purchase completed

Checkout and orders

durable

Browser, Server

An order payment was authoritatively completed.

refund

Refund completed

Checkout and orders

durable

Server

A payment refund was authoritatively recorded.

cancellation

Order cancelled

Checkout and orders

durable

Server

An order cancellation was authoritatively recorded. Amounts and items are what the order still held when it was cancelled.

rec_impression

Recommendations shown

Browsing

observation

Browser, Server

A recommendation placement displayed products.

rec_click

Recommendation clicked

Browsing

observation

Browser, Server

A shopper opened a product from a recommendation placement.

customer_login

Customer signed in

Customer

observation

Browser, Server

A customer successfully signed in without exposing their identifier.

customer_register

Customer registered

Customer

observation

Browser, Server

A customer account was successfully created without exposing its identifier.

order_edited

Order edited

Checkout and orders

durable

Server

A merchant changed the items of an order after its purchase was recorded. Amounts are the signed change the edit made.

newsletter_signup

Newsletter sign-up

Customer

observation

Browser, Server

A shopper subscribed to the store's newsletter from the storefront. The email address is not included.

contact_submitted

Contact form sent

Customer

observation

Browser, Server

A shopper sent the storefront contact form. Nothing they typed is included.

payment_info_added

Payment chosen

Checkout and orders

observation

Browser, Server

A shopper chose how to pay and continued to payment, once per checkout cart.

Session started (`session_started`)#

A new storefront browsing session began.

This event has an empty payload object.

session_started-payload.json json
{}

Page viewed (`page_view`)#

A storefront page was viewed.

Field

Type

Required

Description

page_type

string

Yes

Canonical storefront page type.

display_name

string

No

Localized name shown for the viewed resource.

slug

string

No

Localized public handle for the resource.

resource_id

string

No

Stable identifier of the viewed resource.

page_view-payload.json json
{
  "display_name": "Canvas Print",
  "page_type": "product",
  "resource_id": "4821",
  "slug": "canvas-print"
}

Product viewed (`product_viewed`)#

A product detail page was viewed.

Field

Type

Required

Description

product_id

integer

Yes

Stable product identifier.

variant_id

integer

No

Stable selected variant identifier when one applies.

slug

string

Yes

Localized public handle for the resource.

title

string

Yes

Product or line title at event time.

currency

string

No

ISO 4217 currency code for the accompanying amounts.

price

string

No

Exact major-unit decimal amount as a string.

product_viewed-payload.json json
{
  "currency": "INR",
  "price": "1499.00",
  "product_id": 4821,
  "slug": "canvas-print",
  "title": "Canvas Print",
  "variant_id": 9102
}

A shopper submitted a storefront search.

Field

Type

Required

Description

query

string

Yes

Shopper search query.

results_total

integer

No

Number of matching results when known.

search-payload.json json
{
  "query": "canvas",
  "results_total": 12
}

Cart item added (`cart_add`)#

A cart line was added or its quantity increased.

Field

Type

Required

Description

action

string

Yes

Canonical mutation action.

source

string

No

Originating workflow when the mutation came from another feature.

product_id

integer

Yes

Stable product identifier.

variant_id

integer

No

Stable selected variant identifier when one applies.

quantity

integer

Yes

Resulting line or item quantity.

quantity_delta

integer

No

Signed quantity change made by this mutation.

pricing_status

string

Yes

Whether authoritative pricing was available for the mutation.

unit_amount

string

No

Exact major-unit price for one unit as a string.

line_total

string

No

Exact major-unit line total as a string.

currency

string

Yes

ISO 4217 currency code for the accompanying amounts.

subtotal

string

Yes

Exact major-unit cart or checkout subtotal as a string.

item_count

integer

Yes

Total quantity across the cart or checkout.

unique_item_count

integer

Yes

Number of distinct cart lines.

title

string

No

Product or line title at event time.

sku

string

No

SKU captured at event time when available.

coupons

array of value

No

Applied coupon projections when available.

customized

boolean

No

True when the line carries a file an app attached, such as the shopper's uploaded design.

cart_add-payload.json json
{
  "action": "added",
  "currency": "INR",
  "item_count": 2,
  "line_total": "2998.00",
  "pricing_status": "available",
  "product_id": 4821,
  "quantity": 2,
  "quantity_delta": 1,
  "sku": "CANVAS-A4",
  "subtotal": "2998.00",
  "title": "Canvas Print",
  "unique_item_count": 1,
  "unit_amount": "1499.00",
  "variant_id": 9102
}

Cart item updated (`cart_update`)#

A cart line quantity was changed.

Field

Type

Required

Description

action

string

Yes

Canonical mutation action.

source

string

No

Originating workflow when the mutation came from another feature.

product_id

integer

Yes

Stable product identifier.

variant_id

integer

No

Stable selected variant identifier when one applies.

quantity

integer

Yes

Resulting line or item quantity.

quantity_delta

integer

No

Signed quantity change made by this mutation.

pricing_status

string

Yes

Whether authoritative pricing was available for the mutation.

unit_amount

string

No

Exact major-unit price for one unit as a string.

line_total

string

No

Exact major-unit line total as a string.

currency

string

Yes

ISO 4217 currency code for the accompanying amounts.

subtotal

string

Yes

Exact major-unit cart or checkout subtotal as a string.

item_count

integer

Yes

Total quantity across the cart or checkout.

unique_item_count

integer

Yes

Number of distinct cart lines.

title

string

No

Product or line title at event time.

sku

string

No

SKU captured at event time when available.

coupons

array of value

No

Applied coupon projections when available.

customized

boolean

No

True when the line carries a file an app attached, such as the shopper's uploaded design.

cart_update-payload.json json
{
  "action": "updated",
  "currency": "INR",
  "item_count": 3,
  "line_total": "4497.00",
  "pricing_status": "available",
  "product_id": 4821,
  "quantity": 3,
  "quantity_delta": 1,
  "subtotal": "4497.00",
  "unique_item_count": 1,
  "unit_amount": "1499.00",
  "variant_id": 9102
}

Cart item removed (`cart_remove`)#

A cart line was removed or its quantity decreased.

Field

Type

Required

Description

action

string

Yes

Canonical mutation action.

source

string

No

Originating workflow when the mutation came from another feature.

product_id

integer

Yes

Stable product identifier.

variant_id

integer

No

Stable selected variant identifier when one applies.

quantity

integer

Yes

Resulting line or item quantity.

quantity_delta

integer

No

Signed quantity change made by this mutation.

pricing_status

string

Yes

Whether authoritative pricing was available for the mutation.

unit_amount

string

No

Exact major-unit price for one unit as a string.

line_total

string

No

Exact major-unit line total as a string.

currency

string

Yes

ISO 4217 currency code for the accompanying amounts.

subtotal

string

Yes

Exact major-unit cart or checkout subtotal as a string.

item_count

integer

Yes

Total quantity across the cart or checkout.

unique_item_count

integer

Yes

Number of distinct cart lines.

title

string

No

Product or line title at event time.

sku

string

No

SKU captured at event time when available.

coupons

array of value

No

Applied coupon projections when available.

customized

boolean

No

True when the line carries a file an app attached, such as the shopper's uploaded design.

cart_remove-payload.json json
{
  "action": "removed",
  "currency": "INR",
  "item_count": 1,
  "line_total": "1499.00",
  "pricing_status": "available",
  "product_id": 4821,
  "quantity": 1,
  "quantity_delta": -1,
  "subtotal": "1499.00",
  "unique_item_count": 1,
  "unit_amount": "1499.00",
  "variant_id": 9102
}

Wishlist item added (`wishlist_add`)#

A product or variant was added to a wishlist.

Field

Type

Required

Description

product_id

integer

Yes

Stable product identifier.

variant_id

integer

No

Stable selected variant identifier when one applies.

effect

string

No

Result of the wishlist operation.

wishlist_add-payload.json json
{
  "effect": "added",
  "product_id": 4821,
  "variant_id": 9102
}

Wishlist item removed (`wishlist_remove`)#

A product or variant was removed from a wishlist.

Field

Type

Required

Description

product_id

integer

Yes

Stable product identifier.

variant_id

integer

No

Stable selected variant identifier when one applies.

effect

string

No

Result of the wishlist operation.

wishlist_remove-payload.json json
{
  "effect": "removed",
  "product_id": 4821,
  "variant_id": 9102
}

Checkout started (`begin_checkout`)#

A checkout was created from a validated cart.

Field

Type

Required

Description

subtotal

string

Yes

Exact major-unit cart or checkout subtotal as a string.

value

string

No

Exact major-unit event value after applicable discounts.

currency

string

Yes

ISO 4217 currency code for the accompanying amounts.

item_count

integer

Yes

Total quantity across the cart or checkout.

items

array of object

No

Line-item snapshot included with the event.

items[].product_id

integer

Yes

Stable product identifier.

items[].variant_id

integer

No

Stable selected variant identifier when one applies.

items[].sku

string

No

SKU captured at event time when available.

items[].title

string

No

Product or line title at event time.

items[].quantity

integer

Yes

Resulting line or item quantity.

items[].unit_amount

string

Yes

Exact major-unit price for one unit as a string.

items[].line_total

string

Yes

Exact major-unit line total as a string.

items[].base_unit_amount

string

No

Unit amount converted into the store reporting currency.

items[].base_line_total

string

No

Line total converted into the store reporting currency.

items[].unit_amount_ex_tax

string

No

Unit price without tax and before order discounts, in the order currency.

items[].discount_ex_tax

string

No

Order discount on the items without tax, in the order currency; shipping discounts excluded.

begin_checkout-payload.json json
{
  "currency": "INR",
  "item_count": 2,
  "items": [
    {
      "line_total": "2998.00",
      "product_id": 4821,
      "quantity": 2,
      "sku": "CANVAS-A4",
      "title": "Canvas Print",
      "unit_amount": "1499.00",
      "variant_id": 9102
    }
  ],
  "subtotal": "2998.00",
  "value": "2798.00"
}

Purchase completed (`purchase`)#

An order payment was authoritatively completed.

Field

Type

Required

Description

order_id

string

Yes

Stable Tringify order identifier.

order_number

string

No

Merchant-facing order number when available.

currency

string

Yes

ISO 4217 currency code for the accompanying amounts.

value

string

Yes

Exact major-unit event value after applicable discounts.

base_currency

string

No

Store reporting currency used for normalized reporting.

base_value

string

No

Exact value converted into the store reporting currency.

items

array of object

No

Line-item snapshot included with the event.

items[].product_id

integer

Yes

Stable product identifier.

items[].variant_id

integer

No

Stable selected variant identifier when one applies.

items[].sku

string

No

SKU captured at event time when available.

items[].title

string

No

Product or line title at event time.

items[].quantity

integer

Yes

Resulting line or item quantity.

items[].unit_amount

string

Yes

Exact major-unit price for one unit as a string.

items[].line_total

string

Yes

Exact major-unit line total as a string.

items[].base_unit_amount

string

No

Unit amount converted into the store reporting currency.

items[].base_line_total

string

No

Line total converted into the store reporting currency.

items[].unit_amount_ex_tax

string

No

Unit price without tax and before order discounts, in the order currency.

items[].discount_ex_tax

string

No

Order discount on the items without tax, in the order currency; shipping discounts excluded.

discount_total

string

No

Exact total discount amount in the order currency.

shipping

string

No

Exact shipping amount in the order currency.

tax

string

No

Exact tax amount in the order currency.

has_attribution

boolean

No

Whether the order retained an eligible attribution touch.

tax_included

boolean

No

Whether the order's item prices include tax.

market_id

string

No

Market the order was placed in.

shipping_country

string

No

ISO 3166-1 alpha-2 country of the shipping address, or of the billing address when nothing ships.

locale

string

No

Language the order was placed in, such as fr or en-GB. Absent on orders placed before it was recorded.

discount_ex_tax

string

No

Order discount on the items without tax, in the order currency; shipping discounts excluded.

purchase-payload.json json
{
  "base_currency": "INR",
  "base_value": "2798.00",
  "currency": "INR",
  "discount_ex_tax": "169.49",
  "discount_total": "200.00",
  "has_attribution": true,
  "items": [
    {
      "base_line_total": "2998.00",
      "base_unit_amount": "1499.00",
      "discount_ex_tax": "169.49",
      "line_total": "2998.00",
      "product_id": 4821,
      "quantity": 2,
      "unit_amount": "1499.00",
      "unit_amount_ex_tax": "1270.34",
      "variant_id": 9102
    }
  ],
  "locale": "en",
  "market_id": "9a1f2c3d-4e5f-6789-abcd-ef0123456789",
  "order_id": "66b0a1d2-4f13-4d32-a51d-93e595034e95",
  "order_number": "1042",
  "shipping": "0.00",
  "shipping_country": "IN",
  "tax": "426.81",
  "tax_included": true,
  "value": "2798.00"
}

Refund completed (`refund`)#

A payment refund was authoritatively recorded.

Field

Type

Required

Description

order_id

string

Yes

Stable Tringify order identifier.

refund_transaction_id

string

No

Stable refund transaction identifier.

currency

string

Yes

ISO 4217 currency code for the accompanying amounts.

value

string

Yes

Exact major-unit event value after applicable discounts.

base_currency

string

No

Store reporting currency used for normalized reporting.

base_value

string

No

Exact value converted into the store reporting currency.

items

array of object

No

Line-item snapshot included with the event.

items[].product_id

integer

Yes

Stable product identifier.

items[].variant_id

integer

No

Stable selected variant identifier when one applies.

items[].sku

string

No

SKU captured at event time when available.

items[].title

string

No

Product or line title at event time.

items[].quantity

integer

Yes

Resulting line or item quantity.

items[].unit_amount

string

Yes

Exact major-unit price for one unit as a string.

items[].line_total

string

Yes

Exact major-unit line total as a string.

items[].base_unit_amount

string

No

Unit amount converted into the store reporting currency.

items[].base_line_total

string

No

Line total converted into the store reporting currency.

items[].unit_amount_ex_tax

string

No

Unit price without tax and before order discounts, in the order currency.

items[].discount_ex_tax

string

No

Order discount on the items without tax, in the order currency; shipping discounts excluded.

refund-payload.json json
{
  "base_currency": "INR",
  "base_value": "1499.00",
  "currency": "INR",
  "items": [
    {
      "base_line_total": "1499.00",
      "base_unit_amount": "1499.00",
      "line_total": "1499.00",
      "product_id": 4821,
      "quantity": 1,
      "unit_amount": "1499.00"
    }
  ],
  "order_id": "66b0a1d2-4f13-4d32-a51d-93e595034e95",
  "refund_transaction_id": "refund_1042_1",
  "value": "1499.00"
}

Order cancelled (`cancellation`)#

An order cancellation was authoritatively recorded. Amounts and items are what the order still held when it was cancelled.

Field

Type

Required

Description

order_id

string

Yes

Stable Tringify order identifier.

currency

string

Yes

ISO 4217 currency code for the accompanying amounts.

value

string

Yes

Exact major-unit event value after applicable discounts.

base_currency

string

No

Store reporting currency used for normalized reporting.

base_value

string

No

Exact value converted into the store reporting currency.

items

array of object

No

Line-item snapshot included with the event.

items[].product_id

integer

Yes

Stable product identifier.

items[].variant_id

integer

No

Stable selected variant identifier when one applies.

items[].sku

string

No

SKU captured at event time when available.

items[].title

string

No

Product or line title at event time.

items[].quantity

integer

Yes

Resulting line or item quantity.

items[].unit_amount

string

Yes

Exact major-unit price for one unit as a string.

items[].line_total

string

Yes

Exact major-unit line total as a string.

items[].base_unit_amount

string

No

Unit amount converted into the store reporting currency.

items[].base_line_total

string

No

Line total converted into the store reporting currency.

items[].unit_amount_ex_tax

string

No

Unit price without tax and before order discounts, in the order currency.

items[].discount_ex_tax

string

No

Order discount on the items without tax, in the order currency; shipping discounts excluded.

cancellation-payload.json json
{
  "base_currency": "INR",
  "base_value": "2798.00",
  "currency": "INR",
  "items": [
    {
      "base_line_total": "2998.00",
      "base_unit_amount": "1499.00",
      "line_total": "2998.00",
      "product_id": 4821,
      "quantity": 2,
      "unit_amount": "1499.00",
      "variant_id": 9102
    }
  ],
  "order_id": "66b0a1d2-4f13-4d32-a51d-93e595034e95",
  "value": "2798.00"
}

Recommendations shown (`rec_impression`)#

A recommendation placement displayed products.

Field

Type

Required

Description

placement

string

Yes

Stable recommendation placement identifier.

product_ids

array of integer

Yes

Stable product identifiers shown in the placement.

strategy

string

No

Recommendation strategy identifier when available.

rec_impression-payload.json json
{
  "placement": "related-products",
  "product_ids": [
    4821,
    4822
  ],
  "strategy": "related"
}

Recommendation clicked (`rec_click`)#

A shopper opened a product from a recommendation placement.

Field

Type

Required

Description

placement

string

Yes

Stable recommendation placement identifier.

product_id

integer

Yes

Stable product identifier.

variant_id

integer

No

Stable selected variant identifier when one applies.

rec_click-payload.json json
{
  "placement": "related-products",
  "product_id": 4821,
  "variant_id": 9102
}

Customer signed in (`customer_login`)#

A customer successfully signed in without exposing their identifier.

Field

Type

Required

Description

provider

string

Yes

Authentication method used: email or phone.

surface

string

Yes

Storefront surface where the action completed: for sign-in, account or checkout; for forms, website (newsletter) or contact_page.

customer_login-payload.json json
{
  "provider": "email",
  "surface": "account"
}

Customer registered (`customer_register`)#

A customer account was successfully created without exposing its identifier.

Field

Type

Required

Description

provider

string

Yes

Authentication method used: email or phone.

surface

string

Yes

Storefront surface where the action completed: for sign-in, account or checkout; for forms, website (newsletter) or contact_page.

customer_register-payload.json json
{
  "provider": "email",
  "surface": "checkout"
}

Order edited (`order_edited`)#

A merchant changed the items of an order after its purchase was recorded. Amounts are the signed change the edit made.

Field

Type

Required

Description

order_id

string

Yes

Stable Tringify order identifier.

edit_id

string

Yes

Stable order edit identifier.

order_version

integer

Yes

Order version the edit produced.

currency

string

Yes

ISO 4217 currency code for the accompanying amounts.

value_change

string

Yes

Signed change in the order total made by the edit, in the order currency.

base_currency

string

Yes

Store reporting currency used for normalized reporting.

base_value_change

string

Yes

Signed change in the order total converted into the store reporting currency.

items

array of object

No

Line-item snapshot included with the event.

items[].product_id

integer

Yes

Stable product identifier.

items[].variant_id

integer

No

Stable selected variant identifier when one applies.

items[].sku

string

No

SKU captured at event time when available.

items[].title

string

No

Product or line title at event time.

items[].quantity_delta

integer

Yes

Signed quantity change made by this mutation.

items[].line_total_delta

string

Yes

Signed change in the line total, in the order currency.

items[].base_line_total_delta

string

Yes

Signed change in the line total converted into the store reporting currency.

order_edited-payload.json json
{
  "base_currency": "INR",
  "base_value_change": "-1499.00",
  "currency": "INR",
  "edit_id": "0f3c2a8e-5b1d-4e6f-9a7c-2d4b8e1f6a3c",
  "items": [
    {
      "base_line_total_delta": "-1499.00",
      "line_total_delta": "-1499.00",
      "product_id": 4821,
      "quantity_delta": -1,
      "variant_id": 9102
    }
  ],
  "order_id": "66b0a1d2-4f13-4d32-a51d-93e595034e95",
  "order_version": 2,
  "value_change": "-1499.00"
}

Newsletter sign-up (`newsletter_signup`)#

A shopper subscribed to the store's newsletter from the storefront. The email address is not included.

Field

Type

Required

Description

surface

string

Yes

Storefront surface where the action completed: for sign-in, account or checkout; for forms, website (newsletter) or contact_page.

newsletter_signup-payload.json json
{
  "surface": "website"
}

Contact form sent (`contact_submitted`)#

A shopper sent the storefront contact form. Nothing they typed is included.

Field

Type

Required

Description

surface

string

Yes

Storefront surface where the action completed: for sign-in, account or checkout; for forms, website (newsletter) or contact_page.

contact_submitted-payload.json json
{
  "surface": "contact_page"
}

Payment chosen (`payment_info_added`)#

A shopper chose how to pay and continued to payment, once per checkout cart.

Field

Type

Required

Description

subtotal

string

Yes

Exact major-unit cart or checkout subtotal as a string.

value

string

No

Exact major-unit event value after applicable discounts.

currency

string

Yes

ISO 4217 currency code for the accompanying amounts.

item_count

integer

Yes

Total quantity across the cart or checkout.

items

array of object

No

Line-item snapshot included with the event.

items[].product_id

integer

Yes

Stable product identifier.

items[].variant_id

integer

No

Stable selected variant identifier when one applies.

items[].sku

string

No

SKU captured at event time when available.

items[].title

string

No

Product or line title at event time.

items[].quantity

integer

Yes

Resulting line or item quantity.

items[].unit_amount

string

Yes

Exact major-unit price for one unit as a string.

items[].line_total

string

Yes

Exact major-unit line total as a string.

items[].base_unit_amount

string

No

Unit amount converted into the store reporting currency.

items[].base_line_total

string

No

Line total converted into the store reporting currency.

items[].unit_amount_ex_tax

string

No

Unit price without tax and before order discounts, in the order currency.

items[].discount_ex_tax

string

No

Order discount on the items without tax, in the order currency; shipping discounts excluded.

payment_method

string

Yes

How the shopper chose to pay: online, cod or store_credit.

payment_info_added-payload.json json
{
  "currency": "INR",
  "item_count": 2,
  "items": [
    {
      "line_total": "2998.00",
      "product_id": 4821,
      "quantity": 2,
      "sku": "CANVAS-A4",
      "title": "Canvas Print",
      "unit_amount": "1499.00",
      "variant_id": 9102
    }
  ],
  "payment_method": "online",
  "subtotal": "2998.00",
  "value": "2798.00"
}