Create a new Custom Event (E-commerce)
Custom Events can be setup for all types of stores. Which custom events are mandatory and how they should be set up can be different per e-commerce platform.
The Purchase event is mandatory to set up for Billy Grace to work. In this guide, we explain sending custom events using Google Tag Manager, this is not mandatory, in fact other tag management software can also be used to install the Pixel and send Custom Events to it. Click below to go to the desired set-up:
Shopify
The installation of the Pixel in Shopify is not done via Google Tag Manager. Instead, Shopify has its own solution for tracking pixels. This is called Customer Events and is available in your Shopify store. Read here how to install our Shopify Pixel.
By default, our Pixel will measure the following events in Shopify:
order_completed
search_submitted
order_started
add_to_cart
product_view
collection_view
payment_info_submitted
Do you want to add an event that is not listed above? Then you can set up an extra custom event via Tag Manager. You can do this by creating a new Custom HTML tag with the following script:
<script>
BillyPix('event', 'insertEventName')
</script>
make sure to replace inserteventname with the name of the event.
Since the Billy Pixel in Shopify isn’t installed through Tag Manager, ensure that the custom event does not trigger immediately while the website is still loading. If the event fires before the Pixel is initialized, it may fail to send properly.
After you submit the changes to the live website, you can go to Billy Grace to see the first hits coming in. The Custom Events are automatically visible the next day on this page. In order to make sure that events are configured correctly, we recommend testing the firing of event, in the browser console after submit. Follow this guide on how to test this.
Magento2 (Adobe Commerce)
For the integration with Magento2 (Adobe Commerce) to work properly, we need to set up 2 types of events: purchase and purchase_started. You can use the following script for the purchase event:
Purchase
This is the event that should be send on completion of an order in the webshop.
You can use the following Custom HTML script for this event:
<script>
BillyPix('event', 'purchase',{
transaction_id: {{transaction_id}},
value: {{ecommerceRevenue}}});
</script>
{{transaction_id}} and {{ecommerceRevenue}} in the example above need to be replaced with the proper data layer values. Values other than transaction_id and value are currently not supported and will not show in BG. For transaction_id you need to send the increment_id or entity_id.
These id's are used in Magento, and we will use them to match orders from the purchase event to the actual orders in Magento.
Below, an example on how to replace transaction id and value to the correct data layer values. (This is an example, the actual values can have different names in your specific data layer).
Example of how the tag looks like in Google Tag Manager:
The trigger needs to fire upon completion of the order. Most of the time, you can use the same triggers that are already set up for your GA4 configuration.
Purchase_started
The second mandatory event to send is purchase_started. This should fire the moment a customer starts the checkout process. Use this script:
<script>
BillyPix('event', 'purchase_started',{
transaction_id: {{transaction_id}}});
</script>
For transaction_id you again need to send the increment_id or quote id, if this is available in the datalayer. Make sure the quote id is unhashed.
A checkout token or user ID could also work if these IDs are available
in Magento on order level.
The purchase_started should fire when the checkout process has started. Make sure to test if the right ID is filled after you configured this tag. The increment_id (or quote id) must be present when the checkout process starts.
If you need assistance with GTM, please contact us via the in-app messenger, and we are happy to point you in the right direction.
Once the events are firing on your website, you can activate them in Billy Grace. Navigate to Custom Events under Settings on app.billygrace.com.
Additional Events can be configured and send to Billy Grace via tags using the following script:
<script>
BillyPix('event', 'InsertEventName')
</script>
Important: For accurate data tracking, we advise sending a unique transaction ID with a Custom Event that can't be trigger twice by the same user. (e.g. E-mail subscription, contact form submitted etc.) An ID is not required with events like: Product_view, category_view or add-to-cart.
If available, the ID can be retrieved from the data layer.
Example script for a Custom Event with a transaction id:
<script>
BillyPix('event', 'InsertEventName',{
transaction_id: {{transaction_id}}});
</script>
Additional events can be:
add_to_cart
product_view
collection_view
payment_info_submitted
search_submitted
Triggers that are already setup for GA4 can also be sent to Billy Grace by creating a new tag in Google Tag Manager. Below, a video on how to add a Custom Event.
Replace InsertEventName with the name of the event. Keep in mind that this name should correspond with the name of the Custom Event in Billy Grace. No worries If you didn't create the Custom Event in Billy Grace yet.
The Pixel will automatically create new incoming Custom Events and show them on the Custom Event page under Settings in Billy Grace. In order to use the Custom Events in Billy Grace, you need to activate it on this page.
Lightspeed (C-series)
For the integration with Lightspeed to work properly, we need to set up 2 types of events: purchase and purchase_started.
Purchase
This is the event that should be send on completion of an order in the webshop.
You can use the following Custom HTML script for this event:
<script>
BillyPix('event', 'purchase',{
transaction_id: {{transaction_id}},
value: {{ecommerceRevenue}}});
</script>
{{transaction_id}} and {{ecommerceRevenue}} in the example above need to be replaced with the proper data layer values. Values other than transaction_id and value are currently not supported and will not show in BG. For transaction_id you need to send the order id that corresponds with the order number in Lightspeed.
Billy will use them to match orders from the purchase event to the actual orders in Lightspeed.
Below, an example on how to replace transaction id and value to the correct data layer values. (This is an example, the actual values can have different names in your specific tag manager set-up).
Example of how the tag looks like in Google Tag Manager:
The trigger needs to fire upon completion of the order. Most of the time, you can use the same triggers that are already set up for your GA4 configuration.
Purchase_started
The second mandatory event to send is purchase_started. This should fire the moment a customer starts the checkout process. Use this script:
<script>
BillyPix('event', 'purchase_started',{
transaction_id: {{transaction_id}}});
</script>
For transaction_id you again need to send the quote id, if this is available in the datalayer. Make sure the quote id is unhashed.
A checkout token or user ID could also work if these IDs are available
in lightspeed on order level. Please get in touch with support@billygrace.com if you have questions about this.
The purchase_started should fire when the checkout process has started. Make sure to test if the right ID is filled after you configured this tag. The quote id must be present when the checkout process starts. It could be that this is not implemented by default in your datalayer.
If you need assistance with GTM, please contact us via the in-app messenger, and we are happy to point you in the right direction.
Once the events are firing on your website, you can activate them in Billy Grace. Navigate to Custom Events under Settings on app.billygrace.com.
Additional Events can be configured and send to Billy Grace via tags using the following script:
<script>
BillyPix('event', 'InsertEventName')
</script>
Important: For accurate data tracking, we advise sending a unique transaction ID with a Custom Event that can't be trigger twice by the same user. (e.g. E-mail subscription, contact form submitted etc.) An ID is not required with events like: Product_view, category_view or add-to-cart.
If available, the ID can be retrieved from the data layer.
Example script for a Custom Event with a transaction id:
<script>
BillyPix('event', 'InsertEventName',{
transaction_id: {{transaction_id}}});
</script>
Additional events can be:
add_to_cart
product_view
collection_view
payment_info_submitted
search_submitted
Triggers that are already setup for GA4 can also be sent to Billy Grace by creating a new tag in Google Tag Manager. Below, a video on how to add a Custom Event.
Replace InsertEventName with the name of the event. Keep in mind that this name should correspond with the name of the Custom Event in Billy Grace. No worries If you didn't create the Custom Event in Billy Grace yet.
The Pixel will automatically create new incoming Custom Events and show them on the Custom Event page under Settings in Billy Grace. In order to use the Custom Events in Billy Grace, you need to activate it on this page.
Other (WooCommerce, Shopware, BigCommerce etc.)
One of the mandatory events that e-commerce stores need to configure is the Purchase event. That fires when an order is placed in the webshop. As extra event parameters, Billy Grace needs:
transaction_id
value
<script>
BillyPix('event', 'purchase',{
transaction_id: {{transaction_id}},
value: {{ecommerceRevenue}}});
</script>
Replace InsertEventName with the name of the event. Keep in mind that this name should correspond with the name of the Custom Event in Billy Grace. No worries If you didn't create the Custom Event in Billy Grace yet. The Pixel will automatically create new incoming Custom Events and show them on the Custom Event page under Settings in Billy Grace. In order to use the Custom Events in Billy Grace you need to activate it on this page.
Triggers that are already setup for GA4 can also be sent to Billy Grace by creating a new tag in Google Tag Manager.
Important: For accurate data tracking, we advise to always send a unique transaction ID with a Custom Event. If available, the id can be retrieved from the data layer.
Example script for a Custom Event with a transaction id:
<script>
BillyPix('event', 'InsertEventName',{
transaction_id: {{transaction_id}}});
</script>
Once you have completed setting up the Custom Events, they will become available in Billy Grace on the next day. Navigate to Settings - Custom Events to see all incoming events. To show an event in reports, you must activate the event. You can do this be clicking on the three dots in the table on the right.
Here you have the option to create new Events or activate Events that are picked up by the Pixel. After activation, the Events are selectable in your reports as Goal filter. Selecting an event will show the event (or Goal as we could call it) performance. The goals are available in:
The Overview
Automations
Channel Performance
Paid Performance
Frequently asked questions
After configuring Custom Events we get uncaught reference errors in the inspect console?
This can happen because the Billy Pixel isn't initialized yet when the Custom Event fires. In this case we advise to add tag sequencing to the Custom Event in which you set the Pixel to always fire before the Custom Event. Below, a more detailed explanation on how to do this.
I installed the tags correctly in Tag Manager, I tested them in Debug mode, but they are not coming in Billy Grace. What can I do?
You probably need to change the settings of your Tag Manager Tags. We want the Billy Grace Pixel to fire before the event occurs. How do I fix this?
Go to your Tags in Tag Manager;
Click on your Tag and go to “advanced settings”;
Here you can click on “Tag Sequencing”
Click on “Fire a tag before ‘Insert your custom event’” fires;
Select your Billy Grace Pixel as Set up Tag;
Repeat this for all your Billy Grace Tags in Tag Manager;
Hereby a video showing the steps to adjust tag sequencing.
The next day your events will be added to your account, if not please contact our support team.