openapi: 3.0.3
info:
title: Triple Whale API
version: '1.0'
description: 'Triple Whale API documentation, providing endpoints for managing user authentication, API key validation,
and uploading data such as ads and metrics.
'
servers:
- url: https://api.triplewhale.com/api/v2/
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
security:
- apiKeyAuth: []
paths:
/users/api-keys/me:
get:
summary: Validate Your Triple Whale API Key
description: 'Enter your API key in Credentials > Header to the right and click "Try it!" to test its validity.
'
operationId: validate-your-triple-whale-api-key
tags:
- API Keys
security:
- apiKeyAuth: []
parameters: []
responses:
'200':
description: A successful response
headers:
RateLimit-Policy:
description: 'The rate limit policy for this endpoint, given as `{quota};w={window}` where `window` is in seconds
and `quota` is the allowed number of calls a user can make per window.
'
schema:
type: string
example: 100;w=60
RateLimit:
description: 'Information about the user''s rate limit usage for this endpoint.
'
schema:
type: string
content:
application/json:
schema:
type: object
examples:
Result:
value: '{}'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
examples:
Result:
value: '{}'
'429':
description: Too Many Requests
headers:
Retry-After:
description: 'The number of seconds until the user can make another request.
'
schema:
type: string
example: '60'
/data-in/ads:
post:
summary: Create Ad Record
description: 'Ingest ad data into Triple Whale. This endpoint allows users to upload detailed ad information, including
campaign, adset, ad details, and performance metrics.
'
operationId: create-ad-record
tags:
- Data In
security:
- apiKeyAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- shop
- channel
- event_date
- currency
properties:
shop:
type: string
description: 'The exact Shop URL (e.g., ''example.myshopify.com''). Must match the Shop URL value shown
in [Settings → Store](https://app.triplewhale.com/store-settings/general). The API key owner must also
have access to the shop, otherwise the request will return 403.
'
example: madisonbraids.myshopify.com
channel:
type: string
description: 'The advertising platform associated with the ad data. Use a [Standardized Ad Channel ID](https://triplewhale.readme.io/docs/ads-standardized-channel-ids#/)
or enter a custom value.
'
example: facebook-ads
channel_account_id:
type: string
description: 'The platform-specific account ID. Maps to `account_id` in the Ads table.
'
default: CUSTOM_CHANNEL
example: example_fb_account
event_date:
type: string
format: date
description: 'The date of the event in local timezone. Must be a valid date string (e.g., YYYY-MM-DD).
'
example: '2024-11-28'
currency:
type: string
description: The currency used for reporting (e.g., 'USD').
example: USD
campaign:
type: object
description: Details of the advertising campaign. At least one of `campaign`, `adset`, or `ad` is required.
required:
- id
- name
- status
properties:
id:
type: string
description: The unique ID of the campaign. Maps to `campaign_id` in the Ads table.
example: campaign_example_id
name:
type: string
description: The name of the campaign. Maps to `campaign_name` in the Ads table.
example: Example Campaign
status:
type: string
enum:
- PAUSED
- ACTIVE
description: The status of the campaign (e.g., 'PAUSED' or 'ACTIVE'). Maps to `campaign_status` in the
Ads table.
example: ACTIVE
adset:
type: object
description: Details of the adset. At least one of `campaign`, `adset`, or `ad` is required.
required:
- id
- name
- status
properties:
id:
type: string
description: The unique ID of the adset. Maps to `adset_id` in the Ads table.
example: adset_example_id
name:
type: string
description: The name of the adset. Maps to `adset_name` in the Ads table.
example: Example Adset
status:
type: string
enum:
- PAUSED
- ACTIVE
description: The status of the adset (e.g., 'PAUSED' or 'ACTIVE'). Maps to `adset_status` in the Ads
table.
example: ACTIVE
ad:
type: object
description: Details of the individual ad. At least one of `campaign`, `adset`, or `ad` is required.
required:
- id
- name
- status
properties:
id:
type: string
description: The unique ID of the ad. Maps to `ad_id` in the Ads table.
example: ad_example_id
name:
type: string
description: The name of the ad. Maps to `ad_name` in the Ads table.
example: Example Ad
status:
type: string
enum:
- PAUSED
- ACTIVE
description: The status of the ad (e.g., 'PAUSED' or 'ACTIVE'). Maps to `ad_status` in the Ads table.
example: ACTIVE
thumbnail:
type: string
description: The URL of the ad's thumbnail image. Maps to `ad_image_url` in the Ads table.
example: https://example.com/placeholder.jpg
metrics:
type: object
description: Performance metrics for the ad.
properties:
clicks:
type: number
description: Total number of clicks.
default: 0
example: 1500
conversions:
type: number
description: Total number of conversions (purchases).
default: 0
example: 75
conversion_value:
type: number
description: Total conversion value (order revenue).
default: 0
example: 3750.5
impressions:
type: number
description: Total number of impressions.
default: 0
example: 25000
spend:
type: number
description: Total ad spend.
default: 0
example: 500
visits:
type: number
description: Total number of visits.
default: 0
example: 2000
updated_at:
type: string
format: date-time
description: 'The time at which the ad record was last updated. Must be provided in ISO 8601 format, with
explicit timezone information (`Z` or `+/-HH:mm` offset). Offsets are supported (e.g., `2024-11-29T12:00:00+02:00`).
Defaults to the current time.
'
example: '2024-11-28T15:30:00Z'
responses:
'200':
description: Ad record successfully received.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Ad received
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Invalid ad data.
'429':
description: Too Many Requests
headers:
Retry-After:
description: The number of seconds until the user can make another request.
schema:
type: string
example: '60'
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Rate limit exceeded. Try again later.
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
example: Error processing ad
/data-in/orders:
post:
summary: Create Order Record
description: 'Ingest order data into Triple Whale for Custom Sales Platforms. This endpoint allows users to upload detailed
order information, including customer details, product information, transaction totals, discounts, refunds, and
shipping details.
'
operationId: create-order-record
tags:
- Data In
security:
- apiKeyAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- shop
- order_id
- created_at
- currency
- customer
- order_revenue
properties:
shop:
type: string
description: 'The exact Shop URL (e.g., ''example.myshopify.com''). Must match the Shop URL value shown
in [Settings → Store](https://app.triplewhale.com/store-settings/general). The API key owner must also
have access to the shop, otherwise the request will return 403. Maps to `shop_id` in the Orders table.
'
example: madisonbraids.myshopify.com
order_id:
type: string
description: The unique identifier for the order.
example: order_12345
platform:
type: string
description: 'The sales platform where the order originated. Note that for custom sales platforms, the platform
will appear as `custom-msp` in SQL queries the Triple Whale app, regardless of the value sent.
'
default: custom-msp
example: magento
platform_account_id:
type: string
description: 'The account ID associated with the platform.
'
default: custom-msp
example: shop_account_123
created_at:
type: string
format: date-time
description: 'The time at which the order record was created. Must be provided in ISO 8601 format, with
explicit timezone information (`Z` or `+/-HH:mm` offset). Offsets are supported (e.g., `2022-06-15T21:26:30+02:00`).
Maps to `created_at` in the Orders table and is used to derive `event_date`, which reflects the shop
time zone.
'
example: '2022-06-15T19:26:30.000Z'
currency:
type: string
description: The currency in which the transaction was processed (e.g. `USD`, `EUR`).
example: USD
customer:
type: object
description: 'Details of the customer who placed the order. The `id` field is required. Additionally, at
least one of `email` or `phone` must be provided.
'
required:
- id
properties:
id:
type: string
description: The unique identifier for the customer. Maps to `customer_id` in the Orders table.
example: customer_123
email:
type: string
description: The customer’s email address. Maps to `customer_email` in the Orders table.
example: [email protected]
phone:
type: string
description: The customer’s phone number.
example: '+1234567890'
first_name:
type: string
description: The customer’s first name. Maps to `customer_first_name` in the Orders table.
example: John
last_name:
type: string
description: The customer’s last name. Maps to `customer_last_name` in the Orders table.
example: Doe
custom_expenses:
type: number
description: Custom expenses associated with the order, must be non-negative.
example: 25.0
discount_codes:
type: array
description: Discount codes applied to the order.
items:
type: object
properties:
code:
type: string
description: The discount code used in the order. Maps to `discount_code` in the Orders table.
example: BLACKFRIDAY
amount:
type: number
description: The discount amount applied for the discount code. Must be non-negative. Note that this
field does not map to `discount_amount` in the Orders table; to send total discount amount for the
order, use `total_discounts`.
example: 15.5
type:
type: string
description: 'The type of discount applied. Use `percentage` when the discount amount represents a
percentage of the order total, and `fixed_amount` when it represents a fixed monetary value in the
order’s currency. Maps to `discount_type` in the Orders table.
'
enum:
- percentage
- fixed_amount
example: percentage
line_items:
type: array
description: Details of the products in the order.
items:
type: object
required:
- id
- quantity
- price
- variant_id
- product_id
properties:
id:
type: string
description: The unique identifier for the line item.
example: line_item_1
name:
type: string
description: The name for the line item.
example: Line Item 1
price:
type: number
description: The price of the product. Maps to `products_info.product_name_price` in the Orders table.
example: 20.0
quantity:
type: integer
description: The quantity of the product in the order. Maps to `products_info.product_name_quantity_sold`
in the Orders table.
example: 2
product_id:
type: string
description: The unique identifier for the product. Maps to `products_info.product_id` in the Orders
table. Required for [Product Analytics](https://app.triplewhale.com/dashboards/product-analytics);
must match a `product_id` sent via the `/products` endpoint.
example: product_123
product_name:
type: string
description: The name of the product associated with this line item. Maps to `products_info.product_name`
in the Orders table.
example: T-shirt
variant_id:
type: string
description: The unique identifier for the product variant. Maps to `products_info.variant_id` in
the Orders table.
example: variant_456
variant_name:
type: string
description: The name of the product variant. Maps to `products_info.variant_name` in the Orders table.
example: Red T-shirt (Large)
sku:
type: string
description: The stock keeping unit of the product. Maps to `products_info.product_sku` in the Orders
table.
example: sku_123
name:
type: string
description: 'The name of the order, as assigned by the seller on the main sales platform. Maps to `order_name`
in the Orders table. Defaults to `order_id` if not provided.
'
example: 'Order #12345'
payment_gateway_names:
type: array
description: 'The payment gateway used for the transaction (e.g., `shopify_payments`, `paypal`, `gift_card`).
Required in order to update payment gateway settings, and to calculate `payment_gateway_costs` in the
Orders table. Edit Payment Gateway Costs in [Cost Settings](https://app.triplewhale.com/cost-settings)
> Gateway Costs.
'
items:
type: string
example:
- paypal
refunds:
type: array
description: Details of refunds applied to the order.
items:
type: object
required:
- refund_id
- refunded_at
- total_refund
properties:
refund_id:
type: string
description: The unique identifier for the refund.
example: refund_1
refunded_at:
type: string
format: date-time
description: 'The time at which the refund was processed. Must be provided in ISO 8601 format, with
explicit timezone information (`Z` or `+/-HH:mm` offset). Offsets are supported (e.g., `2024-11-29T12:00:00+02:00`).
'
example: '2024-11-29T11:00:00Z'
line_items:
type: array
description: Details of refunded line items.
items:
type: object
required:
- id
- quantity
- price
- variant_id
properties:
id:
type: string
description: The unique identifier for the refunded line item.
example: line_item_1
line_item_id:
type: string
description: The unique identifier of the line item associated with this refund line item.
example: line_item_1
quantity:
type: integer
description: The quantity of the refunded line item.
example: 1
product_id:
type: string
description: The unique identifier for the refunded product.
example: product_123
variant_id:
type: string
description: The unique identifier for the refunded variant.
example: variant_456
price:
type: number
description: The price of the refunded line item.
example: 20.0
currency:
type: string
description: The currency of the refunded line item.
example: USD
total_discount:
type: number
description: The total discount applied to the refunded line item.
example: 0.0
total_refund:
type: number
description: The total amount refunded.
example: 40.0
total_tax_refund:
type: number
description: The total tax refunded.
example: 3.0
total_shipping_refund:
type: number
description: The total shipping refunded.
example: 5.0
tags:
type: array
description: Tags associated with the refund.
items:
type: string
example: damaged_item
void:
type: boolean
description: 'Set to `true` to void (soft delete) this refund. Voided refund records are excluded
from all queries. To void a refund, resend the entire Order record with all fields identical except
for `"void": true` for this refund. [Learn more](https://triplewhale.readme.io/reference/managing-data-in-connections#voiding-records-soft-delete)
'
default: false
example: false
shipping_address:
type: object
description: Shipping address details.
properties:
address_1:
type: string
description: The first line of the address.
example: 123 Main Street
address_2:
type: string
description: The second line of the address.
example: Apt 4B
zip:
type: string
description: The ZIP or postal code of the address.
example: '10001'
city:
type: string
description: The city of the address. Maps to `customer_from_city` in the Orders table.
example: New York
country:
type: string
description: The country of the address.
example: USA
country_code:
type: string
description: The country code of the address. Maps to `customer_from_country_code` in the Orders table.
example: US
province_code:
type: string
description: The province or state code of the address. Maps to `customer_from_state_code` in the Orders
table.
example: NY
shipping_lines:
type: array
description: Details of the shipping lines for the order.
items:
type: object
properties:
shipping_discounted_price:
type: number
description: The discounted price for shipping.
example: 5.0
shipping_price:
type: number
description: The original price for shipping.
example: 10.0
source:
type: string
description: The source or method of shipping.
example: standard_shipping
title:
type: string
description: The title or description of the shipping method.
example: Standard Shipping
shipping_price:
type: number
description: The total shipping price of the order (paid by the buyer), including shipping taxes and shipping
discounts.
example: 15.0
shipping_costs:
type: number
description: 'Shipping costs paid by the seller. Must be non-negative. To apply this value to your data,
ensure **Default Shipping Costs** is selected in [Cost Settings](https://app.triplewhale.com/cost-settings)
> Shipping.
'
example: 15.0
source_name:
type: string
description: The origin of the order as designated by the seller on the main sales platform (e.g. `web`,
`pos`, `tiktok`).
example: web
subscription_id:
type: string
description: The unique identifier for the subscription associated with the order.
example: sub_12345
tags:
type: array
description: 'Tags associated with the order. Include a distinct tag to classify or identify specific order
types or processing rules. For example, use `holiday_sale` to mark seasonal campaign purchases, or `staff_order`
for internal orders.
'
items:
type: string
example:
- holiday_sale
- staff_order
taxes_included:
type: boolean
description: Indicates if taxes are included in the total price of the order.
default: false
example: false
order_revenue:
type: number
description: The total revenue after adjustments such as discounts, shipping, fees, and taxes. Must be non-negative.
example: 150.75
total_discounts:
type: number
description: The total discount amount applied to the order, including shipping discounts. Must be non-negative.
Maps to `discount_amount` in the Orders table.
example: 15.5
taxes:
type: number
description: The total tax applied to the order. Must be non-negative.
example: 8.25
status:
type: string
description: The current status of the order (e.g., "completed", "pending"). Maps to `fulfillment_status`
in the Orders table.
example: completed
updated_at:
type: string
format: date-time
description: 'The time at which the order record was last updated. Must be provided in ISO 8601 format,
with explicit timezone information (`Z` or `+/-HH:mm` offset). Offsets are supported (e.g., `2024-11-29T12:00:00+02:00`).
Defaults to the current time.
'
example: '2024-11-29T10:00:00Z'
void:
type: boolean
description: 'Set to `true` to void (soft delete) this order record, as well as all associated refund records (even
if the refunds are not individually voided). Voided orders (and associated refunds) are excluded from
all queries. To void an order record, resend it with all fields identical except for `"void": true`. [Learn
more](https://triplewhale.readme.io/reference/managing-data-in-connections#voiding-records-soft-delete)
'
default: false
example: false
responses:
'200':
description: Order record successfully received.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Order received
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
# --- truncated at 32 KB (167 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/triple-whale/refs/heads/main/openapi/triple-whale-openapi.yml