Standard event registry
Developer preview
App Events in Analytics is in developer preview. The preview is available to approved apps and supports declared standard events. Sign up for early access.
Developer preview:
App Events in Analytics is in developer preview. The preview is available to approved apps and supports declared standard events. Sign up for early access.
The standard event registry defines app-reported activities that Shopify Analytics can recognize across apps. Declare a standard event when your app reports an activity that matches the event definition.
For example, multiple email apps can declare shopify.marketing.email_sent. Merchants can then query the emails_sent metric by app_name in Shopify Analytics.
Anchor to HandlesHandles
Each standard event has a single handle that you use in both the app configuration and the API request:
| Handle | Example | Where it's used |
|---|---|---|
| Standard registry handle | shopify.marketing.email_sent | The Shopify-defined event identity. Use it in the shopify.extension.toml declaration and as the App Events API event_handle. |
The shopify. prefix identifies the Shopify-defined registry event. For custom and billing events the prefix is reserved, but standard analytics events emit the full prefixed handle.
Anchor to Category overviewCategory overview
The registry groups standard events by the type of app-reported activity that they represent. Use the category overview to find the right event, then refer to the event's entry for the exact handles and attributes.
| Category | Standard registry handles | Description |
|---|---|---|
| Checkout | shopify.checkout.offer_shownshopify.checkout.offer_acceptedshopify.checkout.offer_declined | Offers and other checkout actions managed by apps. |
| Demand | shopify.demand.restock_subscribedshopify.demand.restock_sentshopify.demand.restock_clickedshopify.demand.wishlist_item_addedshopify.demand.preorder_submittedshopify.demand.backorder_requested | Restock, wishlist, preorder, and backorder activity reported by apps. |
| Discovery | shopify.discovery.search_results_loadedshopify.discovery.recommendations_loaded | Search and product recommendation activity reported by apps. |
| Duties and tariffs | shopify.duties.fee_appliedshopify.duties.duty_calculatedshopify.duties.hs_code_classified | Duty, tariff, fee, and classification activity reported by apps. |
| Experimentation | shopify.experimentation.experiment_startedshopify.experimentation.variant_assignedshopify.experimentation.experiment_concluded | Experiments, assignments, and outcomes managed by apps. |
| Fraud and risk | shopify.fraud.decision_approvedshopify.fraud.decision_declinedshopify.fraud.manual_review_startedshopify.fraud.alert_received | Fraud decisions, reviews, alerts, and chargeback-related activity reported by apps. |
| Fulfillment | shopify.fulfillment.order_status_updatedshopify.fulfillment.label_createdshopify.fulfillment.carrier_exception_detectedshopify.fulfillment.delivery_promise_updatedshopify.fulfillment.shipment_delivered | Shipping, labels, tracking, delivery, and carrier activity reported by apps. |
| Inventory | shopify.inventory.stockout_risk_predictedshopify.inventory.replenishment_recommendedshopify.inventory.purchase_order_recommendedshopify.inventory.demand_forecast_updatedshopify.inventory.inventory_synced | Forecasts, stockout risk, replenishment, purchase orders, and sync activity reported by apps. |
| Lead capture | shopify.lead_capture.lead_capturedshopify.lead_capture.form_submittedshopify.lead_capture.incentive_issued | Leads, forms, and incentives managed by apps. |
| Loyalty | shopify.loyalty.member_enrolledshopify.loyalty.points_earnedshopify.loyalty.points_redeemedshopify.loyalty.reward_issuedshopify.loyalty.reward_redeemedshopify.loyalty.tier_changedshopify.loyalty.referral_completedshopify.loyalty.customer_segment_assignedshopify.loyalty.churn_risk_flagged | Enrollment, points, rewards, tiers, referrals, and segments managed by apps. |
| Marketing | shopify.marketing.email_sentshopify.marketing.email_deliveredshopify.marketing.email_openedshopify.marketing.email_clickedshopify.marketing.email_bouncedshopify.marketing.email_unsubscribedshopify.marketing.sms_sentshopify.marketing.sms_deliveredshopify.marketing.sms_clickedshopify.marketing.sms_unsubscribedshopify.marketing.push_sentshopify.marketing.push_opened | Email, SMS, and push marketing activity reported by apps. |
| Merchandising | shopify.merchandising.review_requestedshopify.merchandising.review_submittedshopify.merchandising.review_publishedshopify.merchandising.review_syndicatedshopify.merchandising.quiz_startedshopify.merchandising.quiz_completedshopify.merchandising.quiz_recommendation_viewed | Reviews, quizzes, user-generated content, and recommendations managed by apps. |
| Purchasing | shopify.purchasing.invoice_generatedshopify.purchasing.receipt_sentshopify.purchasing.download_completed | Invoices, receipts, and downloads generated or managed by apps. |
| Returns | shopify.returns.label_generatedshopify.returns.inspection_completedshopify.returns.disposition_assignedshopify.returns.exchange_offer_accepted | Return labels, inspections, dispositions, and exchanges managed by apps. |
| Subscriptions | shopify.subscriptions.payment_recovery_startedshopify.subscriptions.payment_recovery_completedshopify.subscriptions.retention_offer_startedshopify.subscriptions.retention_offer_acceptedshopify.subscriptions.cancellation_reason_capturedshopify.subscriptions.skip_requestedshopify.subscriptions.swap_completed | Payment recovery, retention, cancellation, skip, and swap activity reported by apps. |
| Support | shopify.support.ticket_createdshopify.support.first_response_sentshopify.support.ticket_resolvedshopify.support.rating_submittedshopify.support.service_recovery_offer_accepted | Support tickets, responses, resolutions, ratings, and recovery offers managed by apps. |
Anchor to Event entriesEvent entries
The full standard event registry follows. Each entry defines the event's category, standard registry handle, required attributes, optional attributes, and queryable metrics. Shopify defines these entries, and only events that are listed here can be declared.
Attribute names are followed by their value type (string, int, or bool). Optional attributes can be omitted when they don't apply to the event or to your app. The Metrics column lists each event's ShopifyQL metric name and its aggregation; query a metric by name with SHOW, such as SHOW emails_sent. Every event has a count metric, and a few also expose a sum metric for a numeric measure. To send an event, use the full standard registry handle, including the shopify. prefix, as the App Events API event_handle (the same value you declare in shopify.extension.toml).
| Category | Event handle | Required attributes | Optional attributes | Metrics |
|---|---|---|---|---|
| Checkout | shopify.checkout.offer_shown | offer_id (int), offer_type (string) | placement (string), cart_id (int), checkout_id (int), product_id (int), bundle_id (int), funnel_id (int) | offers_shown (count) |
| Checkout | shopify.checkout.offer_accepted | offer_id (int), offer_type (string) | placement (string), cart_id (int), checkout_id (int), product_id (int), bundle_id (int), funnel_id (int) | offers_accepted (count) |
| Checkout | shopify.checkout.offer_declined | offer_id (int), offer_type (string) | placement (string), cart_id (int), checkout_id (int), product_id (int), bundle_id (int), funnel_id (int) | offers_declined (count) |
| Demand | shopify.demand.restock_subscribed | product_id (int) | variant_id (int), notification_channel (string), list_id (int), source (string) | restock_subscriptions (count) |
| Demand | shopify.demand.restock_sent | product_id (int) | variant_id (int), notification_channel (string), list_id (int), source (string) | restock_notifications_sent (count) |
| Demand | shopify.demand.restock_clicked | product_id (int) | variant_id (int), notification_channel (string), list_id (int), source (string) | restock_clicks (count) |
| Demand | shopify.demand.wishlist_item_added | product_id (int) | variant_id (int), list_id (int), source (string) | wishlist_items_added (count) |
| Demand | shopify.demand.preorder_submitted | product_id (int) | variant_id (int), preorder_id (int), source (string) | preorders_submitted (count) |
| Demand | shopify.demand.backorder_requested | product_id (int) | variant_id (int), source (string) | backorders_requested (count) |
| Discovery | shopify.discovery.search_results_loaded | search_id (int), result_count (int) | query_id (int), surface (string), zero_results (bool), algorithm_id (int) | search_results_loaded_events (count); search_results_count_total (sum) |
| Discovery | shopify.discovery.recommendations_loaded | recommendation_id (int), recommendation_count (int) | recommendation_type (string), placement (string), surface (string), algorithm_id (int), product_id (int), variant_id (int) | recommendations_loaded_events (count); recommendation_count_total (sum) |
| Duties and tariffs | shopify.duties.fee_applied | order_id (int) | country_code (string), tariff_code (string), fee_type (string) | duties_fees_applied (count) |
| Duties and tariffs | shopify.duties.duty_calculated | order_id (int) | country_code (string), tariff_code (string) | duties_calculated (count) |
| Duties and tariffs | shopify.duties.hs_code_classified | order_id (int) | country_code (string), hs_code (string), classification_source (string) | hs_codes_classified (count) |
| Experimentation | shopify.experimentation.experiment_started | experiment_id (int) | audience_id (int), placement (string), objective (string) | experiments_started (count) |
| Experimentation | shopify.experimentation.variant_assigned | experiment_id (int), variant_id (int) | audience_id (int), placement (string), assignment_method (string) | variants_assigned (count) |
| Experimentation | shopify.experimentation.experiment_concluded | experiment_id (int) | result_status (string), objective (string) | experiments_concluded (count) |
| Fraud and risk | shopify.fraud.decision_approved | decision_id (int) | risk_level (string), reason_code (string), rule_id (int) | decisions_approved (count) |
| Fraud and risk | shopify.fraud.decision_declined | decision_id (int) | risk_level (string), reason_code (string), rule_id (int) | decisions_declined (count) |
| Fraud and risk | shopify.fraud.manual_review_started | review_id (int) | risk_level (string), reason_code (string) | manual_reviews_started (count) |
| Fraud and risk | shopify.fraud.alert_received | alert_type (string) | risk_level (string), chargeback_id (int) | alerts_received (count) |
| Fulfillment | shopify.fulfillment.order_status_updated | fulfillment_order_id (int) | shipment_id (int), tracking_number (string), carrier (string), service_level (string), delivery_region (string) | order_status_updates (count) |
| Fulfillment | shopify.fulfillment.label_created | shipment_id (int) | fulfillment_order_id (int), tracking_number (string), carrier (string), service_level (string), delivery_region (string) | labels_created (count) |
| Fulfillment | shopify.fulfillment.carrier_exception_detected | shipment_id (int) | fulfillment_order_id (int), tracking_number (string), carrier (string), service_level (string), exception_type (string), delivery_region (string) | carrier_exceptions_detected (count) |
| Fulfillment | shopify.fulfillment.delivery_promise_updated | shipment_id (int) | fulfillment_order_id (int), tracking_number (string), carrier (string), service_level (string), delivery_region (string) | delivery_promises_updated (count) |
| Fulfillment | shopify.fulfillment.shipment_delivered | shipment_id (int) | fulfillment_order_id (int), tracking_number (string), carrier (string), service_level (string), delivery_region (string) | shipments_delivered (count) |
| Inventory | shopify.inventory.stockout_risk_predicted | product_id (int) | variant_id (int), location_id (int), forecast_window (string), risk_level (string) | stockout_risks_predicted (count) |
| Inventory | shopify.inventory.replenishment_recommended | product_id (int) | variant_id (int), location_id (int), supplier_id (int), purchase_order_id (int) | replenishment_recommendations (count) |
| Inventory | shopify.inventory.purchase_order_recommended | product_id (int) | variant_id (int), location_id (int), supplier_id (int), purchase_order_id (int) | purchase_orders_recommended (count) |
| Inventory | shopify.inventory.demand_forecast_updated | product_id (int) | variant_id (int), location_id (int), forecast_window (string) | demand_forecasts_updated (count) |
| Inventory | shopify.inventory.inventory_synced | product_id (int) | variant_id (int), location_id (int), sync_source (string) | inventory_syncs (count) |
| Lead capture | shopify.lead_capture.lead_captured | lead_id (int) | form_id (int), campaign_id (int), flow_id (int), capture_type (string), contact_method (string), consent_state (string), incentive_id (int), source (string) | leads_captured (count) |
| Lead capture | shopify.lead_capture.form_submitted | form_id (int) | campaign_id (int), flow_id (int), placement (string), capture_type (string), contact_method (string), consent_state (string), submission_status (string), source (string) | forms_submitted (count) |
| Lead capture | shopify.lead_capture.incentive_issued | incentive_id (int) | lead_id (int), form_id (int), campaign_id (int), incentive_type (string), delivery_channel (string), source (string) | incentives_issued (count) |
| Loyalty | shopify.loyalty.member_enrolled | program_id (int), member_id (int) | referral_channel (string) | members_enrolled (count) |
| Loyalty | shopify.loyalty.points_earned | program_id (int), member_id (int), points_delta (int) | points_balance (int) | points_earned_events (count); points_earned (sum) |
| Loyalty | shopify.loyalty.points_redeemed | program_id (int), member_id (int), points_delta (int) | points_balance (int) | points_redeemed_events (count); points_redeemed (sum) |
| Loyalty | shopify.loyalty.reward_issued | program_id (int), member_id (int), reward_type (string) | points_delta (int), points_balance (int) | rewards_issued (count); reward_points_issued (sum) |
| Loyalty | shopify.loyalty.reward_redeemed | program_id (int), member_id (int), reward_type (string) | points_delta (int), points_balance (int) | rewards_redeemed (count); reward_points_redeemed (sum) |
| Loyalty | shopify.loyalty.tier_changed | program_id (int), member_id (int), tier_from (string), tier_to (string) | None | tier_changes (count) |
| Loyalty | shopify.loyalty.referral_completed | program_id (int), member_id (int) | referral_channel (string) | referrals_completed (count) |
| Loyalty | shopify.loyalty.customer_segment_assigned | program_id (int), member_id (int) | None | customer_segment_assignments (count) |
| Loyalty | shopify.loyalty.churn_risk_flagged | program_id (int), member_id (int) | None | churn_risk_flags (count) |
| Marketing | shopify.marketing.email_sent | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), consent_state (string) | emails_sent (count) |
| Marketing | shopify.marketing.email_delivered | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), recipient_status (string), consent_state (string) | emails_delivered (count) |
| Marketing | shopify.marketing.email_opened | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), consent_state (string) | emails_opened (count) |
| Marketing | shopify.marketing.email_clicked | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), consent_state (string), link_domain (string) | email_clicks (count) |
| Marketing | shopify.marketing.email_bounced | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), recipient_status (string), consent_state (string) | emails_bounced (count) |
| Marketing | shopify.marketing.email_unsubscribed | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), recipient_status (string), consent_state (string) | email_unsubscribes (count) |
| Marketing | shopify.marketing.sms_sent | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), consent_state (string), country_code (string) | sms_messages_sent (count) |
| Marketing | shopify.marketing.sms_delivered | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), recipient_status (string), consent_state (string), country_code (string) | sms_messages_delivered (count) |
| Marketing | shopify.marketing.sms_clicked | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), consent_state (string), link_domain (string), country_code (string) | sms_clicks (count) |
| Marketing | shopify.marketing.sms_unsubscribed | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), recipient_status (string), consent_state (string), country_code (string) | sms_unsubscribes (count) |
| Marketing | shopify.marketing.push_sent | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), consent_state (string), device_platform (string) | push_notifications_sent (count) |
| Marketing | shopify.marketing.push_opened | None | channel (string), campaign_id (int), flow_id (int), template_id (int), message_type (string), consent_state (string), device_platform (string) | push_notifications_opened (count) |
| Merchandising | shopify.merchandising.review_requested | product_id (int) | review_id (int), request_channel (string) | reviews_requested (count) |
| Merchandising | shopify.merchandising.review_submitted | product_id (int), review_id (int) | rating (int), review_source (string), media_attached (bool) | reviews_submitted (count) |
| Merchandising | shopify.merchandising.review_published | product_id (int), review_id (int) | rating (int), review_source (string), media_attached (bool), moderation_status (string) | reviews_published (count) |
| Merchandising | shopify.merchandising.review_syndicated | product_id (int), review_id (int) | rating (int), review_source (string), media_attached (bool) | reviews_syndicated (count) |
| Merchandising | shopify.merchandising.quiz_started | quiz_id (int) | product_id (int), question_group (string) | quizzes_started (count) |
| Merchandising | shopify.merchandising.quiz_completed | quiz_id (int) | product_id (int), question_group (string), completion_state (string) | quizzes_completed (count) |
| Merchandising | shopify.merchandising.quiz_recommendation_viewed | quiz_id (int), recommendation_id (int) | product_id (int), question_group (string) | quiz_recommendations_viewed (count) |
| Purchasing | shopify.purchasing.invoice_generated | order_id (int) | recipient_type (string), delivery_channel (string) | invoices_generated (count) |
| Purchasing | shopify.purchasing.receipt_sent | order_id (int) | recipient_type (string), delivery_channel (string) | receipts_sent (count) |
| Purchasing | shopify.purchasing.download_completed | order_id (int) | export_format (string) | downloads_completed (count) |
| Returns | shopify.returns.label_generated | return_id (int) | rma_id (int), return_reason (string), return_method (string) | labels_generated (count) |
| Returns | shopify.returns.inspection_completed | return_id (int) | rma_id (int), return_reason (string), item_condition (string) | inspections_completed (count) |
| Returns | shopify.returns.disposition_assigned | return_id (int) | rma_id (int), return_reason (string), disposition (string) | dispositions_assigned (count) |
| Returns | shopify.returns.exchange_offer_accepted | return_id (int) | rma_id (int), return_reason (string), exchange_type (string) | exchange_offers_accepted (count) |
| Subscriptions | shopify.subscriptions.payment_recovery_started | subscription_id (int) | contract_id (int), plan_id (int), cadence (string), recovery_reason (string) | payment_recoveries_started (count) |
| Subscriptions | shopify.subscriptions.payment_recovery_completed | subscription_id (int) | contract_id (int), plan_id (int), cadence (string), recovery_reason (string) | payment_recoveries_completed (count) |
| Subscriptions | shopify.subscriptions.retention_offer_started | subscription_id (int), offer_id (int) | contract_id (int), plan_id (int), cadence (string) | retention_offers_started (count) |
| Subscriptions | shopify.subscriptions.retention_offer_accepted | subscription_id (int), offer_id (int) | contract_id (int), plan_id (int), cadence (string) | retention_offers_accepted (count) |
| Subscriptions | shopify.subscriptions.cancellation_reason_captured | subscription_id (int), cancellation_reason (string) | contract_id (int), plan_id (int), cadence (string) | cancellation_reasons_captured (count) |
| Subscriptions | shopify.subscriptions.skip_requested | subscription_id (int) | contract_id (int), plan_id (int), cadence (string) | skips_requested (count) |
| Subscriptions | shopify.subscriptions.swap_completed | subscription_id (int) | contract_id (int), plan_id (int), cadence (string) | swaps_completed (count) |
| Support | shopify.support.ticket_created | ticket_id (int) | channel (string), topic (string), priority (string), agent_team (string) | tickets_created (count) |
| Support | shopify.support.first_response_sent | ticket_id (int) | channel (string), topic (string), priority (string), agent_team (string), response_time_bucket (string) | first_responses_sent (count) |
| Support | shopify.support.ticket_resolved | ticket_id (int) | channel (string), topic (string), priority (string), agent_team (string), resolution_time_bucket (string) | tickets_resolved (count) |
| Support | shopify.support.rating_submitted | ticket_id (int) | channel (string), topic (string), rating_score (int) | support_ratings_submitted (count) |
| Support | shopify.support.service_recovery_offer_accepted | ticket_id (int) | channel (string), topic (string), priority (string), agent_team (string) | service_recovery_offers_accepted (count) |
Only use a standard event when your app's activity matches the event definition. Standard event definitions are shared across apps so that merchants can compare app-reported activity consistently.
Anchor to ShopifyQL fields and metricsShopify
Merchants query standard events through FROM app_events. For the queryable fields, types, metrics, dimensions, version availability, and query examples, refer to the versioned ShopifyQL reference.
Each event's queryable metric names appear in the Metrics column of the event entries. Use those names with SHOW, such as SHOW emails_sent. Every event has a count metric, and some also expose a sum metric for a numeric measure.
Anchor to Attribute requirementsAttribute requirements
In addition to the requirements that are listed for each event, attributes must follow the App Events API constraints:
- A maximum of 15 keys.
- String, number, or boolean values only.
- No arrays or nested objects.
- String values are limited to 128 characters.
- Keys are limited to 64 characters.
Standard registry attributes count toward the 15-key payload limit.
Anchor to App-reported dataApp-reported data
Standard events represent activity that's reported by an app. They don't replace Shopify's commerce data, even when an event relates to fulfillment, returns, subscriptions, inventory, purchasing, or duties. Only send a standard event when your app is the source of the reported activity.
Don't include personal data or data that can identify a natural person in event attributes. Follow the App Events API requirements when choosing attribute values.
Was this page helpful?