API & SDK Reference

Create Product Record

post
https://api.triplewhale.com/api/v2/data-in/products

Ingest product data into Triple Whale. This endpoint allows users to upload detailed product information, including variants, tags, collections, and images.

🚧

Product Data Is Required for Sonar and Product Analytics

Sonar event enrichment

  • Sonar uses product data to enrich events sent to downstream platforms (e.g. Meta, Google, TikTok, Klaviyo, Attentive).
  • Missing product fields can result in missing or incomplete data in Sonar-enriched events. Key fields include: product_title, product_id, variants (including pricing fields like variants[].variant_price), and—when applicable—collections, images, vendor, and product_type.

Product Analytics (requires Orders data)

  • Product Analytics is powered by joining Products ↔ Orders on product_id. Sending product data alone is not sufficient; to enable product-level reporting, line_items.product_id values must also be sent via the /orders endpoint.
📘

Match Product and Order Platform Values

To apply product-based COGS and handling fees to orders, the platform and platform_account_id values sent in product records must exactly match the values sent in the matching order records.

Body Params
string
required

The exact Shop URL (e.g., 'example.myshopify.com'). Must match the Shop URL value shown in Settings → Store. The API key owner must also have access to the shop, otherwise the request will return 403.

string
Defaults to custom-msp

The platform where the product originated. To apply product-based COGS and handling fees to orders, this value must exactly match the platform value sent in the matching order records.

string
Defaults to custom-msp

The account ID associated with the platform. To apply product-based COGS and handling fees to orders, this value must exactly match the platform_account_id value sent in the matching order records.

string
required

The unique identifier for the product. To use Product Analytics, matching line_items.product_id values must also be sent via the /orders endpoint.

string
required

The name or title of the product.

string

The vendor of the product.

string
Defaults to active

The status of the product in the connected sales platform (e.g., active, draft, archived).

product_tags
array of strings

Tags associated with the product, set in the main sales platform (e.g. Upsell, Order Credits, discount_eligible).

product_tags
string

The type or category of the product.

collections
array of strings

Collections the product belongs to.

collections
images
array of objects
Defaults to []

Images associated with the product.

images
variants
array of objects
required

Variants of the product. If there are no variants, then use product_id.

variants*
date-time

The time at which the product record was created. 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.

date-time

The time at which the product 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.

Responses

Updated 23 days ago

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 23 days ago