Triple Whale

https://triplewhale.readme.io
Admin
Triple Whale provides comprehensive developer documentation for accessing and utilizing Triple Whale...
Tokens:144,331
Snippets:1,931
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Lead Event Example

Source: https://triplewhale.readme.io/reference/enrich-pixel-with-offline-events

Example payload for sending a lead event to the pixel endpoint.

```json
{
  "shop": "madisonbraids.myshopify.com",
  "type": "lead",
  "profileIdentifiers": {
    "email": "john.smith@gmail.com"
  }
}
```

--------------------------------

### Install Dependencies and Run Script

Source: https://triplewhale.readme.io/reference/sample-automation-submit-deletion-requests-from-a-csv-python

Commands to install the required requests library and execute the Python script.

```bash
pip install requests
```

```bash
python deletion_requests_from_csv.py
```

--------------------------------

### Currency Example

Source: https://triplewhale.readme.io/reference/get-customer-journey-attribution-data

Example value for the currency field in the order response.

```json
"example": "USD"
```

--------------------------------

### Retry-After Header Example

Source: https://triplewhale.readme.io/reference/create-ad-record

Example value for the Retry-After header provided during rate limiting.

```text
60
```

--------------------------------

### Refund Discount Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of the total discount applied to a refunded line item.

```json
0
```

--------------------------------

### Custom Event Example

Source: https://triplewhale.readme.io/reference/enrich-pixel-with-offline-events

Example payload for sending a custom event with additional properties.

```json
{
  "shop": "madisonbraids.myshopify.com",
  "type": "custom",
  "timestamp": 1732579200,
  "profileIdentifiers": {
    "email": "abcdef@gmail.com"
  },
  "event_name": "my_test_event",
  "value": 10
}
```

--------------------------------

### Install React Native SDK

Source: https://triplewhale.readme.io/reference/mobile-sdk-installation

Install the package via npm and update iOS pods for native dependencies.

```bash
npm install @triplewhale/react-native-triple-pixel
```

```bash
cd ios && pod install
```

--------------------------------

### Query Response JSON Example

Source: https://triplewhale.readme.io/reference/data-out-execute-natural-language-query-moby

Example of a successful query response containing the question and the resulting data set.

```json
{
  "isError": false,
  "error": null,
  "responses": [
    {
      "question": "What is the blended spend for the last 7 days, broken down by day?",
      "answer": {
        "event_date": [
          "2025-02-05",
          "2025-02-04",
          "2025-02-03",
          "2025-02-02",
          "2025-02-01",
          "2025-01-31",
          "2025-01-30"
        ],
        "blended_spend": [
          98169.2413,
          96323.7538,
          99176.6398,
          115385.6991,
          98238.0891,
          79859.6856,
          69779.5765
        ]
      },
      "isError": false,
      "errorMsg": null
```

--------------------------------

### Refund Price Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of the price for a refunded line item.

```json
20
```

--------------------------------

### Filter by Landing Page Path

Source: https://triplewhale.readme.io/docs/sql-example-multi-touch-landing-page-paths-conversion-bounce-metrics

Example of filtering the session data to analyze specific entry points.

```sql
WHERE landing_page LIKE '%sale%'
```

--------------------------------

### API Response Examples

Source: https://triplewhale.readme.io/reference/enrich-pixel-with-offline-events

Examples of success and error responses from the pixel event API.

```json
{
  "success": true,
  "message": "Pixel event received"
}
```

```json
{
  "success": false,
  "message": "Invalid pixel event data."
}
```

```json
{
  "success": false,
  "message": "Payload too large"
}
```

--------------------------------

### ISO 8601 Timestamp Example

Source: https://triplewhale.readme.io/reference/create-ad-record

Example of the required timestamp format for the last updated field.

```text
2024-11-28T15:30:00Z
```

--------------------------------

### Refund Product Identifier Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of a unique identifier for a refunded product.

```json
"product_123"
```

--------------------------------

### Verify Pixel Installation Status

Source: https://triplewhale.readme.io/reference/pixel-setup-guide-for-custom-sales-platform

Execute this command in the browser developer console to check if the Triple Whale Pixel is loaded and ready.

```javascript
TriplePixel('State');
```

--------------------------------

### Payment Gateway Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of a payment gateway identifier used in order transactions.

```json
[
  "paypal"
]
```

--------------------------------

### Success Response Example

Source: https://triplewhale.readme.io/reference/create-ad-record

JSON structure returned upon successful ad record submission.

```json
{
  "success": true,
  "message": "Ad received"
}
```

--------------------------------

### Rate Limit Header Example

Source: https://triplewhale.readme.io/reference/get-summary-page-data

Demonstrates the Retry-After header value used when a 429 Too Many Requests status is returned.

```json
"60"
```

--------------------------------

### Success Response Example

Source: https://triplewhale.readme.io/reference/get-summary-page-data

Represents a successful retrieval of metrics with a list of metric names and their corresponding values.

```json
{
  "metrics": [
    {
      "metricName": "revenue",
      "value": 12345.67
    },
    {
      "metricName": "orders",
      "value": 345
    }
  ]
}
```

--------------------------------

### Refund Currency Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of the currency code for a refund.

```json
"USD"
```

--------------------------------

### init(shopName, msCountry, curr)

Source: https://triplewhale.readme.io/reference/mobile-sdk-methods

Initializes the SDK. This method is required once at app startup.

```APIDOC
## init(shopName, msCountry, curr)

### Description
Initializes the SDK. This method is required once at app startup.

### Parameters
- **shopName** (string) - Required - Your Triple Whale shop ID.
- **msCountry** (string) - Required - Country code for attribution.
- **curr** (string) - Required - Currency code.
```

--------------------------------

### Initialize and track events in iOS (Swift)

Source: https://triplewhale.readme.io/reference/mobile-sdk-quick-start

Initialize the SDK in the AppDelegate or main App entry point and track page load events.

```swift
import TriplePixelSDK

// Once at app startup, e.g. in AppDelegate / @main App init.
// First arg = your Triple Whale shop ID (NOT your storefront domain / shop name).
TriplePixel.Companion.shared.doInit(
    shopName: "your-tw-shop-id",
    msCountry: "US",
    curr: "USD"
)

TriplePixel.Companion.shared.pageLoad(
    e: PageLoadEvent(
        url: "/home",
        productId: nil,
        productName: nil,
        productPrice: nil,
        productVariant: nil,
        searchTerm: nil,
        collection: nil
    )
)
```

--------------------------------

### Refund Quantity Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of the quantity for a refunded line item.

```json
1
```

--------------------------------

### Initialize and track events in React Native

Source: https://triplewhale.readme.io/reference/mobile-sdk-quick-start

Initialize the SDK at app startup and use the provided methods for tracking page views, cart actions, and purchases.

```js
import { TriplePixel } from '@triplewhale/react-native-triple-pixel';

// Once at app startup.
// First arg = your Triple Whale shop ID (NOT your storefront domain / shop name).
TriplePixel.init('your-tw-shop-id', 'US', 'USD');

// Screen view
TriplePixel.pageView('/home');

// Product page
TriplePixel.pageViewWithProduct('/products/42', '42', 'T-Shirt', '29.99');

// Add to cart
TriplePixel.addToCart('42', '', 29.99, 1);

// Contact capture
TriplePixel.contact('user@example.com');

// Purchase
TriplePixel.purchase({
  email: 'user@example.com',
  lineItems: [{ id: '42', quantity: 1, variant: '', price: 29.99 }],
  orderId: '1001',
  token: 'abc123',
});
```

--------------------------------

### Refund Identifier Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of a unique identifier for a refund record.

```json
"refund_1"
```

--------------------------------

### Refund Variant Identifier Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of a unique identifier for a refunded variant.

```json
"variant_456"
```

--------------------------------

### TriplePixel.init

Source: https://triplewhale.readme.io/reference/mobile-sdk-quick-start

Initializes the TriplePixel SDK. This must be called once at app startup before any other tracking methods.

```APIDOC
## TriplePixel.init

### Description
Initializes the TriplePixel SDK with shop credentials. This method must be called once at app startup; calls made before initialization will be ignored.

### Parameters
- **shopName** (string) - Required - The Triple Whale shop ID.
- **msCountry** (string) - Required - Country code for attribution (e.g., "US").
- **curr** (string) - Required - Currency code (e.g., "USD").
```

--------------------------------

### POST /products

Source: https://triplewhale.readme.io/reference/create-product-record

Creates a new product record in the system.

```APIDOC
## POST /products

### Description
Creates a new product record. The request body should contain product variant details, including pricing and creation/update timestamps.

### Method
POST

### Endpoint
/products

### Request Body
- **created_at** (string) - Optional - The time at which the product record was created. Must be in ISO 8601 format.
- **updated_at** (string) - Optional - The time at which the product record was last updated. Must be in ISO 8601 format.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A confirmation message.

#### Error Responses
- **400** (Bad Request) - Invalid product data.
- **429** (Too Many Requests) - Rate limit exceeded.
- **500** (Internal Server Error) - Error processing product.
```

--------------------------------

### Initialize and track events in Android (Kotlin)

Source: https://triplewhale.readme.io/reference/mobile-sdk-quick-start

Initialize the SDK in the Application class and track page load events using the Kotlin SDK.

```kotlin
import com.triplewhale.pixel.TriplePixel
import com.triplewhale.pixel.PageLoadEvent

// Once at app startup, e.g. in Application.onCreate.
// First arg = your Triple Whale shop ID (NOT your storefront domain / shop name).
TriplePixel.init(
    shopName = "your-tw-shop-id",
    msCountry = "US",
    curr = "USD",
)

TriplePixel.pageLoad(PageLoadEvent(url = "/home"))
```

--------------------------------

### Refund Timestamp Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of a refund timestamp in ISO 8601 format.

```json
"2024-11-29T11:00:00Z"
```

--------------------------------

### Define product journeys with window functions

Source: https://triplewhale.readme.io/docs/sql-example-library-overview-and-best-practices

Apply window functions like any() and ROW_NUMBER() to track sequential or co-purchase product behavior.

```sql
-- ✅ Sequential (Next Order)
SELECT customer_id, any(products_info) OVER (
  PARTITION BY customer_id
  ORDER BY created_at ASC
  ROWS BETWEEN 1 FOLLOWING AND 1 FOLLOWING
) AS next_order_products

-- ✅ Co-Purchase (Same Order)
SELECT customer_id, product.product_id
FROM orders_table
ARRAY JOIN products_info AS product
```

--------------------------------

### Refund Line Item Identifier Example

Source: https://triplewhale.readme.io/reference/bulk-create-order-records

Example of a unique identifier for a refunded line item.

```json
"line_item_1"
```

--------------------------------

### Verify Data via SQL Queries

Source: https://triplewhale.readme.io/reference/api-setup-guide-for-custom-sales-platform

Use these SQL queries to inspect recent orders, specific subscriptions, or individual products within the platform tables.

```sql
-- 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'
```

--------------------------------

### pageViewWithProduct(url, productId, productName, productPrice)

Source: https://triplewhale.readme.io/reference/mobile-sdk-methods

Tracks a screen view event with associated product context.

```APIDOC
## pageViewWithProduct(url, productId, productName, productPrice)

### Description
Tracks a screen view event with associated product context.

### Parameters
- **url** (string) - Required - The screen path or URL.
- **productId** (string) - Required - The product identifier.
- **productName** (string) - Required - The product name.
- **productPrice** (string) - Required - The product price.
```

--------------------------------

### TriplePixel('checkoutStarted', ...)

Source: https://triplewhale.readme.io/reference/pixel-setup-guide-for-custom-sales-platform

Tracks the initiation of the checkout process.

```APIDOC
## TriplePixel('checkoutStarted', ...)

### Description
Tracks the start of the checkout process, which is required for the Sonar Initiate Checkout event.

### Parameters
- **eventId** (string) - Optional - ID for cross-platform dedupe
- **email** (string) - Required (if phone not provided) - User email
- **phone** (string) - Required (if email not provided) - User phone number
- **firstName** (string) - Optional - User first name
- **lastName** (string) - Optional - User last name
- **orderId** (string) - Optional - System order ID
- **cotkn** (string) - Optional - Token for order and journey matching
- **lineItems** (array) - Required - List of products including i (Product ID), q (Quantity), and v (Variant ID)
- **address** (object) - Optional - Object containing zip, city, countryCode, and provinceCode
```

--------------------------------

### Top First Purchased Products SQL Query

Source: https://triplewhale.readme.io/docs/sql-example-top-first-purchased-products-count-aov-ltv

Calculates product performance metrics for first-time customers using a Common Table Expression (CTE) to aggregate order data.

```sql
WITH src_tbl AS
(
  SELECT
    customer_id,
    arrayDistinct(arrayMap(x -> (x.product_id as product_id, x.product_name as product_name), groupArrayArray(if(is_new_customer AND event_date BETWEEN '2024-01-01' AND '2024-03-31',products_info,array())))) AS products_info_first_orders,
    groupUniqArray( (event_date, order_id, order_revenue) ) AS orders,
    any(if(is_new_customer AND event_date BETWEEN '2024-01-01' AND '2024-03-31', event_date, null)) AS first_order_date,
    any(if(is_new_customer AND event_date BETWEEN '2024-01-01' AND '2024-03-31', order_revenue, null)) AS first_order_order_revenue
  FROM
    orders_table
  WHERE
    event_date BETWEEN '2024-01-01' AND '2025-03-31'
  GROUP BY 
    customer_id
  HAVING 
    first_order_date IS NOT NULL
)
SELECT
  pi.product_id AS first_product_id,
  pi.product_name AS first_product_name,
  count(1) AS count,
  avg(first_order_order_revenue) AS aov,
  avg(arraySum(arrayMap((d, o, r) -> if(dateDiff('day', first_order_date, d) <= 60, r, 0), orders))) AS avg_ltv_60,
  avg(arraySum(arrayMap((d, o, r) -> if(dateDiff('day', first_order_date, d) <= 90, r, 0), orders))) AS avg_ltv_90,
  avg(arraySum(arrayMap((d, o, r) -> if(dateDiff('day', first_order_date, d) <= 180, r, 0), orders))) AS avg_ltv_180,
  avg(arraySum(arrayMap((d, o, r) -> if(dateDiff('day', first_order_date, d) <= 365, r, 0), orders))) AS avg_ltv_365
FROM 
  src_tbl ARRAY
  JOIN products_info_first_orders AS pi
GROUP BY
  first_product_id, first_product_name
ORDER BY
  count DESC
LIMIT 10
```

--------------------------------

### GET /metrics

Source: https://triplewhale.readme.io/reference/get-summary-page-data

Retrieves metric data for a requested time period.

```APIDOC
## GET /metrics

### Description
Retrieves the value of metrics for the requested time period.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
- **metrics** (array) - List of metric objects containing metricName and value.

#### Response Example
{
  "metrics": [
    {
      "metricName": "revenue",
      "value": 12345.67
    },
    {
      "metricName": "orders",
      "value": 345
    }
  ]
}

### Error Handling
#### Bad Request (400)
- **success** (boolean) - Indicates request failure.
- **message** (string) - Error description.

#### Too Many Requests (429)
- **Retry-After** (header) - The number of seconds until the user can make another request.
```

--------------------------------

### Select initial data for export

Source: https://triplewhale.readme.io/reference/de-duplication-for-data-warehouse-export

Initial query structure for exporting ad spend data from the source table.

```sql
SELECT
  campaign_id,
  ad_id,
  spend
FROM ads_table
WHERE event_date = today()
```

--------------------------------

### Bad Request Response Example

Source: https://triplewhale.readme.io/reference/create-ad-record

JSON structure returned when the provided ad data is invalid.

```json
{
  "success": false,
  "message": "Invalid ad data."
}
```

--------------------------------

### Analyze Website Performance by Device and Country

Source: https://triplewhale.readme.io/docs/sql-example-website-performance-by-device-and-country

Calculates key performance metrics including conversion rate and new visitor percentage grouped by device and country.

```sql
SELECT
  wa.device as device,
  wa.country as country,
  sum(wa.sessions) as sessions,
  sum(wa.session_page_views) as session_page_views,
  sum(wa.unique_visitors) as unique_visitors,
  sum(wa.new_visitors) as new_visitors,
  new_visitors / unique_visitors as new_visitor_percent,
  sum(wa.orders_quantity) as orders_quantity,
  sum(wa.order_revenue) as order_revenue,
  orders_quantity / sessions as conversion_rate
FROM
  web_analytics_table wa
WHERE
  event_date BETWEEN @start_date AND @end_date
GROUP BY
  grouping sets ((device, country), ())
ORDER BY unique_visitors DESC
```

--------------------------------

### Internal Server Error Response Example

Source: https://triplewhale.readme.io/reference/create-ad-record

JSON structure returned when an unexpected server-side error occurs.

```json
{
  "success": false,
  "message": "Error processing ad"
}
```
Tokens:
Raw