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
Because of the integration between Billy Grace and Shopify, it isn't mandatory to add custom events via Google Tag Manager. The following events are available in Billy Grace by default if you installed the pixel via Customer Events in Shopify:
Order_completed
Search_submitted
Order_started
Add_to_cart
Product_view
Collection_view
Payment_info_submitted
In case of a headless Shopify solution, the following tag script can be used:
<script>
var order_id = Shopify.checkout.order_id
var checkout_token = Shopify.checkout.token
BillyPix('event', 'order_completed', {
oid : order_id,
cot : checkout_token
})
</script>
Create a custom event with the tag script above and fire it on the purchase event that is already set up in your GA4 configuration. It is also possible to fire it on another trigger. Just make sure that the oid and cot values are prefilled correctly.
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 values in the browser console after submit.
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:
<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.
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. 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 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 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>
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
Campaign 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.