Overview

This guide walks you through the process of integrating your database and systems with WorkMagic. By completing this integration, your team will enable seamless tracking of customer interactions and order placements, ensuring precise reporting and attribution.

To complete the integration, you will need to complete:

Module	Details	Average lead time
Pixel SDK installation	Install the WorkMagic Pixel SDK on your website to accurately capture customer interaction.	2 days
Orders API integration	Integrate the Orders API to enable WorkMagic to capture order and sales data.	3 days
End to end validation	Verify that both the Pixel SDK and Orders API are integrated correctly.	<1 day

Step 1 WorkMagic Pixel installation

1.1. Pixel SDK Installation Instructions

There are two ways to install WorkMagic pixels SDK:

Manually install them on the store website
Insert them into Google Tag Manager.

Option 1: Install manually on all pages

Find your tenant ID and tenant ID sign from your WorkMagic account's setting page
(Please reach out to marketing team members to assign a seat if you do not have direct login access)

Update the following codes with your tenant ID and tenant ID sign

<script src="https://fe-assets.workmagic.io/pixel/latest/wm.min.js" crossorigin="anonymous"></script>
<script>
;(function (h) {
  h.WorkmagicPixel.init({
    tenantId: 'please replace with your tenant ID',
    tenantIdSign: 'please replace with your tenant ID sign',
    source: 'custom-built-website',
  });
})(window);
</script>

Insert a Javascript Code snippet with the updated script in front of the </head> tag on all pages

✅ Tip: Please ensure the pixel is installed on ALL pages hosted by your eCommerce shop domain

Option 2: Install with Google Tag Manager

If you use GTM to manage pixel scripts, you can add WorkMagic pixel scripts in the following way:

Find your tenant ID and tenant ID sign from your WorkMagic account's setting page
(Please reach out to marketing team members to fetch your IDs if you do not have direct login access)

Update the following codes with your tenant ID and tenant ID sign

<script src="https://fe-assets.workmagic.io/pixel/latest/wm.min.js" crossorigin="anonymous"></script>
<script>
;(function (h) {
  h.WorkmagicPixel.init({
    tenantId: 'please replace with your tenant ID',
    tenantIdSign: 'please replace with your tenant ID sign',
    source: 'custom-built-website',
    isGtm: true,
  });
})(window);
</script>

Create a new Tag In Google Tag Manager
Click on Tag Configuration
Select Custom HTML in the pop up
Paste in the updated code snippet from step 2 into the editor
Click on Triggering
Select All Pages
Name the tag appropriately, and click "Save"

✅ Success: You have successfully installed WorkMagic's Pixel SDK

1.2. Pixel SDK event tracking

Page viewed reporting

After installing the Pixel SDK, page view data will be automatically reported. Ensure that the Pixel SDK is installed on every page of your store for accurate tracking across all customer interactions.

To validate this, please head towards Settings > Data integration > Sales data > Install WorkMagic Pixel > Debug tools > Pixel events in the last 28 days to see if your testing page views were recorded by WorkMagic.

Checkout started reporting

Checkout events are essential to our attribution. While both checkout_started and checkout_completed events are supported, if your checkout token is only generated after order payment, report the checkout_completed event only.

Please ensure that checkout.token of pixel matches the checkout_token of the order. Our best practice is to use the order ID as the checkout token in both checkout pixels and the Order API.

Checkout_started

Sample feed:

window.WorkmagicPixel("checkout_started", {
  checkout: { token: "xxxx" }
});

Checkout_completed

Sample feed:

window.WorkmagicPixel && window.WorkmagicPixel("checkout_completed", {
  checkout: {
    token: "xxxx",
    order: {id: "xxxx"}
  }
});

To validate, head towards Settings > Data integration > Sales data > Install WorkMagic Pixel > Debug tools > Pixel events in the last 28 days.

✅ Success: Congratulations! WorkMagic pixels have been fully installed on your eCommerce website

Step 2: Order & Sales data integration

2.1. Find your API Key

By default, one API Key has already been generated. You can directly use it by copying the API Key.

Option 1: Via Onboarding step 2 > Store data > Order API Integration > Generate new API key
Option 2: Find API Key in Settings > Data Integration > Sales Data > Upload Data

2.2. API endpoint details

API domain: https://store-api.workmagic.io/api/orders
HTTP Method: Post
Account Authentication: Use the Header X-API-KEY as the unified authentication method.
Response Codes:
- 200: Success
- 400: Invalid parameters
- 401: Invalid API KEY
- 500: Internal server error

Example:

curl --request POST \
     --url https://store-api.workmagic.io/api/orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"orders":[]}'

2.3. Prepare Order Data Feed

Platform Unique Keys

Our platform deduplicates order records with the unique key order_id

⚠️ Warning: Order ID and Order Create Time are not editable once submitted

Order API Schema

Please refer to the API documentation at https://developer.workmagic.io/reference/postapiorders as the source of truth.

API field name	Usage
browser_ip	Used as primary geo parameter in geo lift tests and attribution Enhance mode.
checkout_token	Used to match order records to pixel signals for attribution analytics.
shipping_address.zipcode	Used as fall back geo parameter in geo lift tests
discount_codes.code	Used for affiliate & influencer attribution
extensions.is_new_customer_order	Used to segment orders for attribution metrics such as CAC
extensions.is_subscription_order	Used to segment order data for lift tests

2.4. Test your payload

Option 1: Test a sample payload without writing into WorkMagic database: https://data-check.workmagic.io/

Option 2: Test a live payload via API documentation

2.5. Pushing your data to WorkMagic

Historical data: Send order records from the past 180 days
Net-new data: Trigger an Order API push when a net-new order transacts
Updated order: Trigger an Order API push when an order has been updated

2.6. Order Data verification

Option 1: Use WorkMagic's testing tool

Via Onboarding > Store data > Order API Integration > Check Status
Via Settings > Data Integration > Sales Data > Upload data > Debug Tools

✅ Tip: We kindly ask the team to also validate 5 orders' financials with the Marketing team to ensure definitions are aligned.

Option 2: Use API to pull data for verification

API: GET https://store-api.workmagic.io/api/orders

Refer to https://developer.workmagic.io/reference/getapiorders as the source of truth.

✅ Success: Congratulations! You have connected your orders data stream with WorkMagic

Step 3: End to End Validation

Please visit Settings > Platform Integrations > Sales Channel

The goal is to achieve a match ratio close to 100%. Match Ratio = Matched Orders / Total Orders

If the match ratio is 0: error in checkout.token or checkout_token
If the match ratio is low: some web pages may be missing the Pixel SDK
Ensure the checkout_token in each order is unique

Final Checklist

Page views captured by WorkMagic is close to internal reporting
Checkout events fired are close to your eCommerce order count
Checkout events and Orders have a >90% match rate
Order API payload contains valid browser IPs
Order API payload contains valid zip codes
Order API payload contains valid discount codes (where applicable)
Order API payload contains is_new_customer_order flag that matches internal reporting
Sample order API records matches the source of truth

✅ Success: If all of the above are checked, you have completed your WorkMagic onboarding! Thank you for your support and effort!

WorkMagic Custom Site Technical Onboarding