This article will guide you through how to push order, subscription, product, and customer data directly into Triple Whale using our Data-In API endpoints.

Prerequisites

API Key – Creating and Managing Triple Whale API Keys
Store Domain – e.g. example.myshop.com

Step 1: Send Data to API Endpoints

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

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

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 applicable)

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.

Customers (Optional)

Create Customer Record: POST https://api.triplewhale.com/api/v2/data-in/customers

Key Fields

customer_id
email_address, phone
first_name, last_name

Best Practices

Ensure customer_id matches IDs referenced in orders.
Use this endpoint when you have customer profiles that have no orders.
Keep consent data and tags updated using the updated_at timestamps.
If your platform doesn’t track certain customer fields, omit them.

Step 2: Confirm Successful Data Delivery

After you start sending data to the API endpoints, use the in-app Custom Account Health page to confirm that Triple Whale is receiving your records.

The Custom Account Health page shows a live status of your API connections:

Orders API – last order received, and total orders received in last 24 hours
Products API – last product received, and total products in system
Subscriptions API – last subscription received, and total subscriptions received in last 24 hours
Pixel – last Add to Cart and Contact events received in last 24 hours (see Pixel Setup Guide)

If any section shows “Not Installed” or no recent data, check your API calls and timestamps.

The Custom Account Health page displays data as soon as it’s received by Triple Whale; if counts are updating, your integration is sending data successfully.

Because backend processing can take additional time, data may not appear in the SQL Editor right away. Use this page first to confirm successful delivery, then check the SQL Editor later once processing is complete.

Step 3: 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:

Open SQL Editor

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.

Step 4: 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": "customer@example.com",
        "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.