Zipchat Purchase Tracking Integration (Non-Shopify stores)

Purchase Tracking - Pixel (JavaScript)

Overview

The Purchase Tracking feature allows Zipchat to track purchases that originate from chat bubble interactions on your website. This helps you measure the ROI of your chat widget by attributing sales to conversations that happened within a 24-hour window.

Note: This feature is only available for non-Shopify integrations. Shopify stores have their own built-in purchase tracking mechanism.

How It Works

1. Customers interact with your Zipchat widget

2. The widget stores a visitor token in the browser's local storage

3. When a purchase is completed, your checkout page calls our tracking function

4. We match the purchase to the conversation using the visitor token and attribute the sale if it occurred within 24 hours of the last message

Activation

Step 1: Enable the Feature

1. Navigate to your chat's Integrations page

2. Find the "Purchase tracking - Pixel (JavaScript)" section

3. Click the Activate button to enable purchase tracking

Once activated, you'll see the integration interface with the script snippet and implementation instructions.

Step 2: Add the Script to Your Checkout Page

Copy the provided script snippet and add it to your checkout success/thank you page:

<script src='https://app.zipchat.ai/widget/track_zipchat_purchase.js?id=YOUR_WIDGET_TOKEN' data-no-optimize='1' defer></script>

Important: The script must be loaded on the page before calling the tracking function.

Step 3: Track the Purchase

Once the script is loaded, call the trackZipchatPurchase function with the purchase data:

<script>
window.trackZipchatPurchase({
  order_id: "12345",
  order_total: 99.99,
  currency: "USD",
  line_items: [
    {
      id: "product_1",
      title: "Product Name",
      price: 99.99,
      quantity: 1
    }
  ]
});
</script>

Function Parameters

Required Fields

Field	Type	Description
order_id	String	Unique identifier for the order
order_total	Number	Total order amount (including taxes, shipping, etc.)
currency	String	Currency code (e.g., "USD", "EUR", "GBP")

Optional Fields

Field	Type	Description
line_items	Array	Array of purchased items (see structure below)

Line Items Structure

Each item in the line_items array can include:

Field	Type	Description
id	String	Product identifier
title	String	Product name
price	Number	Item price
quantity	Number	Quantity purchased

Server Responses

The tracking function will log different messages to the browser console based on the server response:

Success Response

• HTTP Status: 200

• Response: { "success": true }

• Console Log: [Zipchat] Purchase tracked successfully.

Error Responses

Sales Tracking Not Enabled

• HTTP Status: 403 Forbidden

• Response: { "error": "Sales tracking is not enabled. Enable it from [integration_url]." }

Chat Not Found

• HTTP Status: 404 Not Found

• Response: { "error": "Chat not found" }

Missing Parameters

• HTTP Status: 422 Unprocessable Entity

• Response: { "error": "Missing widget_token or shop parameter" }

Validation Errors

• HTTP Status: 422 Unprocessable Entity

• Response: { "error": "[validation error messages]" }

Client-Side Validation

The JavaScript function performs validation before sending data to the server:

Missing Visitor Token

If no visitor token is found in localStorage:

[Zipchat] No visitor token found. Purchase tracking requires a visitor token.

Missing Required Fields

If order_id, order_total, or currency are missing:

[Zipchat] Missing required fields. Please provide order_id, order_total, and currency.

Network Errors

If the request fails due to network issues:

[Zipchat] Error tracking purchase: [error details]

Server Errors

If the server returns an error status:

[Zipchat] Failed to track purchase

Implementation Examples

Basic Implementation

// Minimal required data
window.trackZipchatPurchase({
  order_id: "ORD-123456",
  order_total: 49.99,
  currency: "USD"
});

Complete Implementation

// With all optional data
window.trackZipchatPurchase({
  order_id: "ORD-123456",
  order_total: 149.97,
  currency: "USD",
  line_items: [
    {
      id: "PROD-001",
      title: "Wireless Headphones",
      price: 99.99,
      quantity: 1
    },
    {
      id: "PROD-002",
      title: "Phone Case",
      price: 24.99,
      quantity: 2
    }
  ]
});

Troubleshooting

Common Issues

1. "No visitor token found"

   • Ensure the Zipchat widget has been loaded and a conversation has been initiated

   • Check that localStorage contains a visitor_token entry

2. "Widget token not found in script URL"

   • Verify the script URL includes the correct widget token parameter

   • Ensure the script tag src attribute is properly formatted

3. Purchase not appearing in analytics

   • Check that the purchase occurred within 24 hours of the last chat message

   • Verify that the visitor token matches an existing conversation

   • Ensure all required fields are provided correctly

Attribution Window

Purchases are only attributed to conversations if they occur within 24 hours of the last message in the conversation. This ensures accurate attribution while preventing false positives from older conversations.