Comment on page
GA4 Shopify App Event Definitions
📌 Bookmark this page.Understanding how attribution metrics are derived and how event properties are translated from one platform to another can be difficult. Our team is committed to taking the guesswork out of managing attribution. The definitions below are shared to provide transparency and clarity in setting up and maintaining your attribution model.
Note: If you are exclusively leveraging Fueled’s GA4 Connector App for Shopify, you don’t need to worry about Fueled’s naming convention, as events will show up in Google Analytics correctly, using Google’s event schema.
One of the challenges in attribution tracking is that every platform, from Shopify to Google Analytics to Facebook Ads to Segment, uses different naming conventions to describe a shopper’s behavioral events, and the properties of those events.
It’s Fueled’s job handle all of these translations on behalf of our merchants. However, if you are looking to customize any of your Fueled events, it’s helpful to understand and adopt our naming conventions to keep your data clean and consistent.
Fueled’s internal event naming convention follows the “Object-Action Framework.” What that means is that event names begin with the object upon which an action occurs, followed by a past-tense verb describing the action.
For example: when a user visits a product description page, we refer to this event as a
Product Viewed
event, not a Viewed Product
or viewed_product
event. The majority of CDPs and attribution platforms follow this Object-Action Framework. (Google Analytics, however, does the opposite.)Moreover, Fueled events are Title Cased, and use spaces between the Object and the Action. Google Analytics, on the other hand, uses snake_case naming.
Fueled | Google Analytics | Automatically Tracked with Fueled’s GA4 App? | Notes |
---|---|---|---|
Product Added | add_to_cart | ✅ | If your storefront theme is based upon one of Shopify’s themes, and you haven’t customized the HTML markup of your “Add to Cart” buttons, these events should automatically fire with our client-side tracking script. |
Product Added to Wishlist | add_to_wishlist | ❌ | This event can be custom coded into a merchant’s Shopify theme, leveraging Fueled’s javascript library. |
Checkout Started | begin_checkout | ✅ | Fueled tracks this event as a server-side event by default. |
Account Logged In | login | ✅ | If your storefront theme is based upon one of Shopify’s themes, and you haven’t customized the HTML markup of your account screens, these events should automatically fire with our client-side tracking script. |
Promotion Clicked | select_promotion | ❌ | This event can be custom coded into a merchant’s Shopify theme, leveraging Fueled’s javascript library. |
Order Completed | purchase | ✅ | Fueled tracks this event as a server-side event by default. |
Order Refunded | refund | ❌ | This event can be custom coded into a merchant’s Shopify theme, leveraging Fueled’s javascript library. |
Page Viewed | pageview | ✅ | pageview events sent directly from Google Analytics 4’s client-side library from the website to GA4. This is required to trigger Google Signals and assign the client-side events a Google Customer ID. |
Product Removed | remove_from_cart | ✅ | This event fires when a shopper removes a product from the full-page shopping cart page (/cart). There may be other places in a merchant’s storefront where products can be removed from the cart. Such events can be custom coded into a merchant’s Shopify theme, leveraging Fueled’s javascript library. |
Products Searched | search | ✅ | Fueled tracks these events client-side. |
Product Clicked | select_item | ❌ | This event can be custom coded into a merchant’s Shopify theme, leveraging Fueled’s javascript library. |
Product Shared | share | ❌ | This event can be custom coded into a merchant’s Shopify theme, leveraging Fueled’s javascript library. |
Account Created | sign_up | ✅ | Fueled tracks this event as a server-side event by default. |
Cart Viewed | view_cart | ✅ | Fueled tracks these events client-side. |
Product Viewed | view_item | ✅ | Fueled tracks these events client-side. |
Product List Viewed | view_item_list | ✅ | Fueled tracks these events client-side, if your storefront is using standard “Collections” pages. |
Promotion Viewed | view_promotion | ❌ | This event can be custom coded into a merchant’s Shopify theme, leveraging Fueled’s javascript library. |
Fueled uses
camelCasing
when labeling event properties. Google Analytics typically uses snake_casing
.When Fueled’s GA4 Connector App is installed, we provide an option for enabling a theme extension that installs a data layer and, optionally, injects client-side event tracking. You can leverage this data layer for your own purposes. Doing so is actually a great idea, as it helps ensure that you are using the data storefront variables across all of your client-side attribution scripts.
Our data layer exposes the following objects in your theme.
The Customer Object is only exposed when a shopper is logged into your store.
Property | Type | Shopify Storefront API Value | Description |
---|---|---|---|
Name | String | customer.first_name + customer.last_name | The shopper’s first and last name as a single value. |
externalCustomerId | String | customer.id | Shopify’s unique identifier for the customer. |
email | String | customer.email | The customer’s email address. |
firstName | String | customer.first_name | The customer’s first name. |
lastName | String | customer.last_name | The customer’s last name. |
address | Object | N/A (This object is generated using the Shopify storefront API variables listed below.) | The Address Object is made up of the following properties. |
address.street | String | customer.default_address.street | The customer’s default street address. |
address.city | String | customer.default_address.city | The customer’s default city. |
address.state | String | customer.default_address.province | The customer’s default state or province. |
address.postalCode | String | customer.default_address.zip | The customer’s default zip code. |
address.countryCode | String | customer.default_address.country_code | The customer’s default country code. |
Product objects are exposed both on individual product pages, and as an array of products on Collection pages and so forth.
Property | Type | Shopify Storefront API Value | Description |
---|---|---|---|
productId | String | Shopify’s globally-unique identifier. | |
sku | String | product.selected_or_first_available_variant.sku | The Shopify SKU for either the selected product, or for the first available variant on a product page. |
quantity | Number | cartItemsJson[i].quantity | Note: only exposed on Cart pages, via the Cart JSON object. |
variant | String | product.selected_or_first_available_variant.id | Shopify’s globally-unique identifier for either the selected product, or for the first available variant on a product page. |
name | String | product.title | The product’s title. |
price | Number | product.price / 100 | The price of the currently selected product or variant. |
brand | String | product.vendor | The product’s vendor name. |
position | Number | N/A (Position is calculated for each product in a collection, carousel, or shopping cart.) | The position of the product in either a Collection or the Cart is calculated. Positioning starts with “1.” |
url | String | product.url | The product’s online URL |
imageUrl | String | product.featured_image | The URL of the feature product image. |
category | String | product.type | The product categorization/type. |
Exposed on the cart page (https://examplestore.com/cart).
Property | Type | Shopify Storefront API Value | Description |
---|---|---|---|
products | Array | N/A | |
total | Number | cart.total_price | Note: The Shopify cart total_price is equal to the purchase price of each product line item, times the quantity of each line item, minus discounts. It does not include taxes or shipping. |
The following events are sent client-side, from your Shopify storefront to Google Analytics 4, via our javascript library, which is installed into your active Shopify theme. These are the default events that Fueled tracks out of the box. Additional tracking events can be added to your theme with a small amount of custom code.
Note: Fueled currently supports event properties marked with ✅. Properties marked with ❌ are not currently supported.
This event fires when an item is added to a cart for purchase.
GA4’s
add_to_cart
event maps to Fueled’s generalized Product Added
event specification. The add_to_cart
event is populated with the following properties.Note: The “add to cart” experiences on a Shopify theme are often heavily customized. Fueled’s out-of-the-box
add_to_cart
attribution events only cover standard use cases. Customized tracking scripts may be needed to capture all add_to_cart
events on your website.GA4 Event Property | Supported | Type | Corresponding Fueled Property | Shopify Object/Property | Description |
---|---|---|---|---|---|
currency | ✅ | String | currency is not included in Fueled’s top-level Product Added event schema. It is calculated from the currency values passed as part of the items array. | currency is not available within the Shopify Storefront API product object. Therefore, it is calculated when needed. | Currency of the items associated with the event, in 3-letter ISO 4217 format. If set, item-level currency is ignored. If not set, currency from the first item in items is used. If you set value then currency is required for revenue metrics to be computed accurately. |
value | ✅ | Number | value is not included in Fueled’s top-level Product Added event schema. It is calculated from the individual products in Fueled’s product array (which is the equivalent of GA4’s items array). | Calculated, based upon the subtotal of the items being added to the cart (ie, price minus discounts, not including shipping or taxes). | The monetary value of the event. Value is typically required for meaningful reporting. Note: By default, Google Analytics recommends that the value of conversion events is equal to the subtotal value of a cart, checkout, purchase, and so forth, where subtotal includes discounts, but not shipping or taxes. Fueled supports setting the value of carts, checkouts, and orders to total_price , which includes shipping and taxes. |
items | ✅ | Array | products | An array of product objects, exposed through the Shopify Storefront API. | An array of item objects, each with the properties described below. |
items.$.item_id | ✅ | String | products.$.id | product.id | The ID of the item. |
items.$.item_name | ✅ | String | products.$.name | product.title | The name of the item. |
items.$.affiliation | ❌ | String | N/A | N/A | Shopify doesn’t support affiliation at the individual product level. |
items.$.coupon | ❌ | String | products.$.coupon | N/A | The coupon name/code associated with the item. Event-level and item-level coupon parameters are independent. |
items.$.currency | ❌ | String | products.$.currency | N/A | The currency, in 3-letter ISO 4217 format. If set, event-level currency is ignored. Multiple currencies per event is not supported. Each item should set the same currency. |
items.$.discount | ❌ | Number | products.$.discount | N/A | The monetary discount value associated with the item. This discount value, has not been deducted from the item’s price property. |
items.$.index | ✅ | Number | products.$.position | The position of an item/product in a storefront collection, carousel, or cart is calculated. | The index/position of the item in a list. (If applicable.) |
items.$.item_brand | ✅ | String | products.$.brand | product.vendor | The brand of the item. |
items.$.item_category |