API Reference
Start typing to search…

Custom MSP (Custom Cart) Integration - Quick Start Guide

Set up your custom sales platform using Triple Pixel and Data-In API

Welcome to your quick-start guide for installing and configuring the Triple Whale Pixel on your site, and integrating your custom Main Sales Platform (MSP) via our server-side APIs. Follow these steps to ensure you capture the data you need—from visitor identification to advanced event tracking—so you can make data-driven decisions and optimize customer journeys.

Part 1: Pixel Installation for Attribution

Prerequisites

Step 1: Add the Base Tracking Snippet (Required)

Locate the Pixel Snippet

Navigate to the Headless installation tab on the Attribution → Settings → Installation page and copy the base snippet.

Add to <head>

Install the snippet in the <head> of all site pages.

The snippet loads the Triple Pixel javascript asynchronously so it won’t affect your page load speed.

Verify installation:

Open any page with the snippet and open your browser’s console.

Type TriplePixelData and hit Enter. You should see the Pixel data object.

If undefined, ensure:

  • The script is within the <head> tag.
  • Any cached HTML is purged.

Step 2: Add a Purchase or Subscription Event (Required)

Add to <head> after the base snippet

You must track at least one of the following events in order to connect the transaction to the customer journey to ensure all of your transactions are properly attributed.

  • purchase
  • NewSubscription
TriplePixel('purchase', {
  eventId: '<EVENT_ID>', //Optional
  email: '<USER_EMAIL>',
  phone: '<USER_PHONE>',
  firstName: '<FIRST_NAME>',
  lastName: '<LAST_NAME>',
  orderId: '<ORDER_ID>',
  cotkn: '<CUSTOM_TOKEN>',
  lineItems: ['<PRODUCT_ID1>', '<PRODUCT_ID2>'],
  address: { zip: '12345', city: 'City', countryCode: 'US', provinceCode: 'CA' }
});

TriplePixel('NewSubscription', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: '[email protected]',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Last',
  orderId: 'order_0000',
  subscriptionId: 'sub_0123',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

Verify installation:

  • A properly configured event will appear in the Network tab when triggered. If not, check the console for errors or inspect the page source to verify the implementation.
  • Contact the TW SE team for further support: [email protected]

Step 3: Capture Viewed Product Events

Add to <head> after the base snippet

To automatically record when a visitor views a product page, update the TriplePixelData object with product details and fire a ViewedProduct event immediately after the base snippet:

<script>
window.TriplePixelData = window.TriplePixelData || {};
window.TriplePixelData.product = {
  id: '<PRODUCT_ID>',      // e.g., '48269676624115'
  name: '<PRODUCT_NAME>',  // e.g., 'Top Knot Messy Bun Ponytail Holder'
  price: '<PRICE>',        // e.g., '42.99'
  variant: '<VARIANT_ID>'   // e.g., '8218652206806'
};
TriplePixel('ViewedProduct', { product: window.TriplePixelData.product });
</script>

Step 4: Capture Visitor Contact Info

Add to <head> after the base snippet

To tie visitor actions to real leads, fire a Contact event whenever you collect an email or phone number.

<script>
(function TP() {
  const email = "<DYNAMIC_EMAIL>";  // Insert dynamic customer email
  if (!email || !window.TriplePixel) {
    setTimeout(TP, 400);
    return;
  }
  TriplePixel('Contact', { email: email });
})();
</script>

Optional Variations:

TriplePixel('Contact', { email: '[email protected]' });
TriplePixel('Contact', { phone: '123-456-7891' });
TriplePixel('Contact', { email: '[email protected]', phone: '123-456-7891' });

Best Practice: Place this snippet anywhere customer contact info is submitted (e.g., signup forms, newsletter pop‑ups).

Step 5: Track Additional Standard Events

Add to <head> after the base snippet

Add to Cart

TriplePixel('AddToCart', {
  item: '<PRODUCT_ID>',      // e.g., '4428522618989'
  q: <QUANTITY>,             // e.g., 1
  v: '<VARIANT_ID>',         // e.g., '9898162258244'
  // Optional: cart token
  token: '<CART_TOKEN>'
});

Page Views

  • Automatic: Tracked on snippet load.
  • Single Page Manual: Call TriplePixel('pageLoad') or include context (see SPA section).

Checkout Funnel (Recommended)

  • checkoutStarted
  • contactSubmitted
  • addressSubmitted
  • shippingSubmitted
  • paymentSubmitted
TriplePixel('checkoutStarted', {
  eventId: '<EVENT_ID>', //Optional
  email: '<USER_EMAIL>',
  phone: '<USER_PHONE>',
  firstName: '<FIRST_NAME>',
  lastName: '<LAST_NAME>',
  orderId: '<ORDER_ID>',
  cotkn: '<CUSTOM_TOKEN>',
  lineItems: ['<PRODUCT_ID1>', '<PRODUCT_ID2>'],
  address: { zip: '12345', city: 'City', countryCode: 'US', provinceCode: 'CA' }
});

TriplePixel('contactSubmitted', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: '[email protected]',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Name',
  order_id: 'order_0000',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

TriplePixel('addressSubmitted', {
  eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: '[email protected]',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Name',
  order_id: 'order_0000',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

TriplePixel('shippingSubmitted', {
 eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
 email: '[email protected]',
 phone: '1234567',
 firstName: 'First',
 lastName: 'Name',
 order_id: 'order_0000',
 cotkn: '121212121212', // Additional token/data relevant to your system
 lineItems: ['3333333', '555555'], // The product IDs or SKUs
 address: {
   zip: '67676',
   city: 'Sterling',
   countryCode: 'US',
   provinceCode: 'KS'
 }
});

TriplePixel('paymentSubmitted', {
eventId: 'n65N65', // Optional - should match the eventID used when sending the same event to other platforms to assist in event deduplication
  email: '[email protected]',
  phone: '1234567',
  firstName: 'First',
  lastName: 'Name',
  order_id: 'order_0000',
  cotkn: '121212121212', // Additional token/data relevant to your system
  lineItems: ['3333333', '555555'], // The product IDs or SKUs
  address: {
    zip: '67676',
    city: 'Sterling',
    countryCode: 'US',
    provinceCode: 'KS'
  }
});

These lifecycle events help capture the complete checkout journey and power accurate attribution.

You can customize the parameters passed based on your data requirements, though the fields above are commonly used. Key fields include the eventId (for cross-platform event referencing) and contact details (email or phone) to enable Triple Whale to attribute future actions to the specific subscriber.

Step 6: Track Custom Events

Add to <head> after the base snippet

With custom events, you can track any type of event that is relevant for your business. Custom events can have whatever name you choose, and support passing any custom property that is relevant for that event.

TriplePixel('custom', 'scheduleDemo', {
  'action': 'booked_demo',
  'version': '1.0',
  'shop': 'example-shop.myshopify.com',
  'email': '[email protected]',
  'firstName': 'John',
  'lastName': 'Doe',
  'phone': '+1-555-123-4567'
});

Only the event name (scheduleDemo in the example) is required. All parameters/fields are optional and can be whatever you'd like to track with the event.

Custom Events can also be marked as ‘conversion events’ in your settings to enable attribution for these events.

For more information on setting up and tracking custom events, see the Tracking Custom Events knowledge base article.

Step 7: Add Page Context

Enhance tagging by including product or search context in the TriplePixelData object. Only one product and one search value per page.

Product Pages (Recommended)

window.TriplePixelData.product = {
  id: '<PRODUCT_ID>',
  name: '<PRODUCT_NAME>',
  price: '<PRICE>',
  variant: '<VARIANT_ID>'
};

Search Results

window.TriplePixelData.search = '<SEARCH_TERM>';

Single Page Application (SPA) Support

Option A: Context with Manual Page Loads

TriplePixel('pageLoad', {
  product: { id: '123', name: 'Item', price: '9.99', variant: '456' },
  search: 'query',
  collection: '789'
});

Option B: Update Data Object

window.TriplePixelData.product = { /* ... */ };
TriplePixel('pageLoad');
// Then reset TriplePixelData to avoid stale context

Step 8: Tracking Consent

TriplePixel('trackingConsent', false); // Disable
TriplePixel('trackingConsent', true);  // Enable

Step 9: Advanced Install Methods

  • Tag Managers: Pixel works with most tag management solutions. Refer to your tag manager’s docs and verify via console.
  • Mobile Websites: If separate from desktop, install on both to capture mobile traffic.

Testing & Troubleshooting

  • Verify TriplePixelData in console.
  • Check network requests for TriplePixel calls.
  • Purge any caches or CDN layers if events are missing.

Part 2: Server-Side API Integration

Push order, subscription, and product data directly into Triple Whale using our Data-In API endpoints.

Prerequisites

Rate Limit: 25 000 requests per minute across all Data-In endpoints

API Endpoints

Use the endpoints below to complete your initial MSP setup. Send each record once it’s created, keep it up-to-date, and backfill historical data.

Orders (Required)

Create Order Record: POST https://api.triplewhale.com/api/v2/data-in/orders

Key Fields

  • order_id (unique per store)
  • created_at, updated_at for data freshness
  • line_items, customer, shipping_address, refunds
  • subscription_id (if recurring)

Best Practices

  • Retry Logic: Use exponential backoff (e.g., 2s, 4s, 8s) on 429 or 500+ errors.
  • Update Logic: Re-submit the entire order when updates occur. Use updated_at to inform changes.
  • Backfill: Fetch all historical orders and loop through POST calls in batches (e.g., 100/day).

Subscriptions (If you sell recurring products)

Create Subscription Record: POST https://api.triplewhale.com/api/v2/data-in/subscriptions

Key Fields

  • subscription_id, status
  • created_at, ended_at, canceled_at
  • subscription_items (include pricing, discounts, quantity)

Best Practices

  • Ensure updates on cancelation, renewal, or changes to product details.
  • Set status accurately: e.g., active, canceled.

Products (Required)

Create Product Record: POST https://api.triplewhale.com/api/v2/data-in/products

Key Fields

  • product_id, product_title
  • variants, collections, tags

Best Practices

  • Update Frequency: Sync nightly or on product update events.
  • Backfill: One-time batch import for historical catalog.
  • No Batch Import Support: Submit each product separately.
  • Map SKUs and variant IDs carefully to link to line items in orders.

Orders Enrichment (Optional / After the order exists)

Enrich Orders Data: POST https://api.triplewhale.com/api/v2/data-in/orders-enrichment

Use this to:

  • Add custom financial metrics (custom_net_revenue, custom_gross_sales)
  • Append shipping costs and fulfillment data
  • Add flags like ignore_order, custom_status

Best Practices

  • Only use for additional metadata after an order has been submitted.
  • Can be helpful for adding calculated values not present in source platform.

Verify Data via SQL Editor

Once you've sent your data to the API endpoints, it’s important to confirm that everything is flowing correctly into the Triple Whale platform.

Go to the SQL Editor:

Use the in-app SQL Editor to run simple queries and confirm your submitted records are appearing as expected:

You can query tables like Orders (orders_table), Subscriptions (subscriptions_table), and Products (products_table) to inspect recently created or updated records.

Example Queries:

-- Check recent orders
SELECT
   *
FROM
   orders_table
WHERE
   event_date = CURRENT_DATE()
ORDER BY
   created_at DESC
LIMIT
   10

-- Check a specific subscription
SELECT 
   * 
FROM 
   subscriptions_table
WHERE 
   subscription_id = 'sub_12345';

-- Check a specific product
SELECT
   *
FROM
   products_table
WHERE
   product_id = 'product_123'

If your data isn’t showing up:

  • Re-check that all required fields were submitted.
  • Verify timestamps (e.g., created_at, updated_at) are properly formatted.
  • Review the API response logs for error messages or missing fields.

Manage Data Updates, Reliability, and Best Practices

Once you’ve connected your data via the required endpoints, use the following practices to ensure data remains reliable, complete, and up-to-date over time.

Retry & Error Handling

Implement basic retry and error-handling logic to make your integration more robust.

  • Retry 3 times on timeout (5xx) or 429 Too Many Requests responses, using exponential back-off (e.g., 2s, 4s, 8s).
  • Log all failures with key information (order ID, error message, retry status) for troubleshooting.
  • Only send finalized orders: Use status: "completed" to filter out draft or abandoned carts.

Smart Update Logic

Keep your data fresh by detecting changes and re-sending updated records.

  • Use theupdated_at field to track if an order, subscription, or product has changed since last sync (compare against previously stored timestamp).
  • On any detected change (customer info, item, pricing, etc.), re-send the full order or subscription record.
  • De-duplicate by tracking a combination of order_id or subscription_id + shop.

Historical Backfill

Backfill historical data to give Triple Whale full visibility into your past performance.

Orders

  • Export orders as CSV from your platform (e.g., Shopify, WooCommerce, Magento).
  • Iterate through each row and POST orders individually using the Create Order Record endpoint.
  • Rate-limit your calls to avoid overloading: Aim for about 5 requests/second.

Products

  • Fetch your full product catalog and POST each item individually using the Create Product Record.
  • Continue syncing newly created or updated products as part of regular operations.

Inventory Considerations

Maintaining inventory consistency is critical for accurate reporting.

  • Always keep product_id and variant_id aligned across both order and product records.
  • Sync product updates regularly (pricing, titles, variants) to to ensure pricing and SKUs match your current live catalog.

Subscriptions & Rebilling Logic

Recurring revenue depends on keeping subscription records updated.

  • Re-submit subscriptions whenever a billing/renewal event happens.
  • Make sure to update the following fields accurately:
    • interval
    • interval_count
    • status (e.g., active, canceled)
    • ended_at
  • If a subscription is canceled, paused, or resumed, update Triple Whale immediately to maintain churn and LTV accuracy.

Sample Python Script Snippet

Adapt the fields and structure to match your platform's output.

import requests

url = "https://api.triplewhale.com/api/v2/data-in/orders"

payload = {
    "shop": "example.myshop.com",
    "order_id": "order_12345",
    "order_revenue": 150.75,
    "platform": "magento",
    "platform_account_id": "shop_account_123",
    "created_at": "2022-06-15T19:26:30.000Z",
    "currency": "USD",
    "customer": {
        "id": "customer_123",
        "email": "[email protected]",
        "phone": "+1234567890",
        "first_name": "John",
        "last_name": "Doe"
    },
    "custom_expenses": 25,
    "discount_codes": [
        {
            "code": "BLACKFRIDAY",
            "amount": 15.5,
            "type": "percentage"
        }
    ],
    "line_items": [
        {
            "id": "line_item_1",
            "price": 20,
            "quantity": 2,
            "product_id": "product_123",
            "product_name": "T-shirt",
            "variant_id": "variant_456",
            "variant_name": "Red T-shirt (Large)",
            "sku": "sku_123",
            "tax_lines": [
                {
                    "price": 1.5,
                    "rate": 0.075,
                    "title": "Sales Tax"
                }
            ]
        }
    ],
    "name": "Order #12345",
    "refunds": [
        {
            "refund_id": "refund_1",
            "refunded_at": "2024-11-29T11:00:00Z",
            "line_items": [
                {
                    "id": "line_item_1",
                    "line_item_id": "line_item_1",
                    "quantity": 1,
                    "product_id": "product_123",
                    "variant_id": "variant_456",
                    "price": 20,
                    "currency": "USD",
                    "total_discount": 0,
                    "tax_lines": [
                        {
                            "price": 1,
                            "rate": 0.075,
                            "title": "Sales Tax"
                        }
                    ]
                }
            ],
            "total_refund": 40,
            "total_tax_refund": 3,
            "total_shipping_refund": 5,
            "tags": ["damaged_item"]
        }
    ],
    "shipping_address": {
        "address_1": "123 Main Street",
        "address_2": "Apt 4B",
        "zip": "10001",
        "city": "New York",
        "country_code": "US",
        "province_code": "NY"
    },
    "shipping_lines": [
        {
            "shipping_discounted_price": 5,
            "shipping_price": 10,
            "source": "standard_shipping",
            "title": "Standard Shipping",
            "tax_lines": [
                {
                    "price": 0.5,
                    "rate": 0.05,
                    "title": "Shipping Tax"
                }
            ]
        }
    ],
    "shipping_costs": 15,
    "subscription_id": "sub_12345",
    "tags": ["holiday_sale", "new_customer"],
    "taxes_included": True,
    "tax_lines": [
        {
            "price": 8,
            "rate": 0.1,
            "title": "VAT"
        }
    ],
    "total_discounts": 15.5,
    "total_tax": 8.25,
    "status": "completed",
    "updated_at": "2024-11-29T10:00:00Z",
    "void": False
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Dev Tips

  • Log all POST responses, including order_id, response, and status.
  • Validate all payloads against the required fields for each endpoint.
  • Test your integration on a staging environment first before pushing live.
  • Use separate API keys for Testing and Production to prevent cross-environment issues.

Support & Resources

Sample Demo Site

To help you get familiar with working code samples, we’ve created a demo site that shows the Triple Whale Pixel in action:

Documentation & Support