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

Prerequisites

API Key – Create & manage keys in Settings ➜ API Keys
Store Domain – e.g. example.myshop.com
Platform Identifiers – platform and platform_account_id

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

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.

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.

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.

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.