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. Ensure that the Pixel SDK is installed on every page of your store for accurate tracking across all customer interactions.	2 days
Orders API integration	Integrate the Orders API to enable WorkMagic to capture order and sales data, linking customer actions to specific orders for detailed analysis.	3 days
End to end validation	Verify that both the Pixel SDK and Orders API are integrated correctly to ensure accurate data capture and reporting.	<1 day

Steps to Complete Integration:

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 and the tag configuration is completed
Click on Triggering
Select All Pages
Name the tag appropriately, and click "Save" on the top right hand corner

✅ 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. You would observe page view events in the trendline if the Pixel SDK is installed successfully.

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. Alternatively, apply the checkout_started event if your checkout token is generated upon customers reaching your checkout page.

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 in subsequent sections.

Checkout_started

This is a sample feed of our checkout_started event, please ensure your payload structure aligns with the following example:

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

The following are the event parameters for our checkout_started event:

Parameters	Type	Required	Pattern/Enum
checkout
`checkout.token`	string	Y	A unique identifier for a single checkout session, ensuring it matches the `checkout_token` in the Order API. If the unique identifier is not available, the `order_id` (if already exists) can be used as the `checkout_token`. Ensure uniqueness: The `checkout.token` in each event must be unique, with no two orders sharing the same token. Maximum length: 40 characters.

Checkout_completed

This is a sample feed of our checkout_completed event, please ensure your payload structure aligns with the following example:

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

The following are the event parameters for our checkout_completed event:

Parameters	Type	Required	Pattern/Enum
checkout
`checkout.token`	string	Y	A unique identifier for a single checkout session, ensuring it matches the `checkout_token` in the Order API. If the unique identifier is not available, the `order_id` (if already exists) can be used as the `checkout_token`. Ensure uniqueness: The `checkout.token` in each event must be unique, with no two orders sharing the same token. Maximum length: 40 characters.
order
`checkout.order.id`	string	Y	Unique identifier of the order that matches the order ID being sent over in your Order API

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 checkout events were recorded by WorkMagic. You would observe checkout events in the trendline if the checkout events are firing properly.

✅ 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. You can have multiple API Keys by generating them using the method below:

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. The X-API-Key can be found in WorkMagic Settings (support generate new API key).
Response Codes: Use HTTP Status Codes as the unified status indicators.
- 200: Success
- 400: Invalid parameters. Please check if required fields are missing or if field types are correct.
- 401: Invalid API KEY. Please contact the developer.
- 500: Internal server error. Please contact the developer.

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

Order records with a unique key that doesn't exist in our database will be inserted into our records. Order records with the same unique key found in our database will be updated with the data in the new API push.

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

Order API Schema

When developing integration, please refer to the API documentation at https://developer.workmagic.io/reference/postapiorders as the source of truth.

Please pay special attention to the following fields as they are used directly in our product suites:

API field name	Usage
browser_ip	Used as primary geo parameter in our geo lift tests. Used for attribution Enhance mode which leverages non-cookie probabilistic signals to model user activity.
checkout_token	Used to match order records to pixel signals to inform attribution analytics. Please ensure the checkout token here matches with the metric used in your checkout pixels.
shipping_address.zipcode	Used as fall back geo parameter in our geo lift tests
discount_codes.code	Used for affiliate & influencer attribution
extensions.is_new_customer_order	Used to segment orders to inform attribution metrics such as CAC
extensions.is_subscription_order	Used to segment order data to be scoped into lift tests

This is a sample JSON payload that would load well into WorkMagic's backend:

curl --request POST \
     --url https://store-api.workmagic.io/api/orders \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "orders": [
    {
      "line_items": [
        {
          "id": "8f698a21-1801-4513-80e1-2ccab2c82cf1",
          "title": "IPod Nano",
          "price": 15,
          "quantity": 1,
          "current_quantity": 1
        }
      ],
      "id": "12295e26-36c9-457c-af57-4b20e7c58378",
      "created_at": "2025-01-01T00:00:00+00:00",
      "updated_at": "2025-01-01T00:00:00+00:00",
      "browser_ip": "216.191.105.146",
      "order_number": "10001",
      "landing_site": "http://www.example.com?source=abc",
      "referring_site": "http://www.example.com",
      "checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
      "financial_status": "paid",
      "total_price": 15,
      "current_total_price": 10,
      "subtotal_price": 20,
      "total_line_items_price": 20,
      "current_subtotal_price": 5,
      "current_total_discounts": 15,
      "current_total_tax": 2,
      "discount_codes": [
        {
          "code": "RTJUNRSHTAL9"
        }
      ],
      "shipping_address": {
        "zip": "T0E 0M0",
        "country_code": "US",
        "country": "United States",
        "city": "Drayton Valley",
        "province_code": "KY",
        "province": "Kentucky"
      },
      "customer": {
        "id": "5f098331-996d-4135-a103-d2300e64c029",
        "email": "[email protected]"
      },
      "extensions": {
        "order_app_name": "Online store",
        "order_cost_cogs": 10.01,
        "order_cost_handling": 10.01,
        "order_cost_shipping": 10.01,
        "order_cost_transaction": 10.01,
        "order_shipping_charges": 10.01,
        "order_refund_amount": 10.01,
        "order_refund_product_count": 10,
        "is_subscription_order": true,
        "is_new_customer_order": false,
        "extended_metrics": {
          "extended_metric_sample": 30
        }
      }
    }
  ]
}'

2.4. Test your payload

Now that the data table and conversion logic is built, please validate your payload format to ensure it is well received into WorkMagic's server.

Option 1: Test a sample payload without writing into WorkMagic database

Try this tool with a sample upload to check whether the schema matches: https://data-check.workmagic.io/

Option 2: Test a live payload in API documentation that would write into WorkMagic's database

Head towards our official Order API documentation, https://developer.workmagic.io/reference/postapiorders
Paste in your API order key
Paste in your payload in the right hand side panel
Click Try it!
Success is indicated by a 200 response

2.5. Pushing your data to WorkMagic

To onboard your data properly, we require historical, net-new and updated order data:

Historical data: Please send over order records from the past 180 days to enable lift testing and model learning
Net-new data: Please trigger an Order API push when a net-new order transacts
Updated order: Please trigger an Order API push when an order has been updated (e.g. Financial status updates, order value updates etc.)
When updating an order, the data with the same unique key (order id) will be overwritten with the new information.

2.6. Order Data verification

Now that all data is loaded into WorkMagic, please verify that the Orders API has taken in all the data sent over.

Option 1: Use WorkMagic's testing tool

Via Onboarding > Store data > Order API Integration > Check Status. Click "Test Orders API" button and see the results. If both orders and checkout token shows success, then the Orders API integration is successful.
Via Settings > Data Integration > Sales Data > Upload data > Debug Tools. Check the trendline graph "last 7 days success rate", when both uploads success rate and records success rates are 100% for net new orders, the Orders API integration is successful.

The check data accuracy section within the tool would surface API records received in a filtered date range.

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

Option 2: Use API to pull data for verification

Leveraging our GET orders endpoint, the team can query the latest 100 orders uploaded in the last 72 hours for data verification.

Please compare this data with your store's records to ensure complete consistency, aiming for a full match between the orders received by WorkMagic and your store's records.

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

If there are any discrepancies, refer to the API documentation at https://developer.workmagic.io/reference/getapiorders as the source of truth.

Example:

Request:

curl -v https://store-api.workmagic.io/api/orders \
     --header 'X-API-KEY: mstak_ex5mk5fddybxbhj8c3dxnmry8pcsp3z3csp3z3'

Response:

HTTP/2 200
{
  "orders": [
    ...
  ]
}

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

Step 3: End to End Validation

Now that your pixels and Order API are both live, the next step would be to validate your attribution infrastructure end to end.

Please visit our UI via Settings > Platform Integrations > Sales Channel

The goal is to achieve a match ratio close to 100% for all orders originating from web pages. The match ratio is calculated as: Match Ratio = Matched Orders / Total Orders

If the match ratio is 0: It indicates an error in the checkout.token of the pixel's "checkout_started" event or the checkout_token in the order data.
If the match ratio is low: This may suggest that some web pages are missing the Pixel SDK.
Ensure uniqueness: The checkout_token in each order must be unique, with no two orders sharing the same token.

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 with internal reporting
Sample order API records matches the source of truth marketing team uses for reporting

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

WorkMagic Custom Site Technical Onboarding