# Quickstart Guide to Bonsai Welcome to Bonsai. This overview is designed to help you quickly understand **what Bonsai does**, **what data you need**, and **how to get live in the platform** as fast as possible. Whether you are onboarding for Business Reporting, Multi-Touch Attribution (MTA), Incrementality, or Algorithms—your first step is always the same: **connect your data sources** so Bonsai can build a trusted measurement foundation. *** ## What Bonsai Helps You Do Bonsai is a measurement and optimization platform that unifies marketing and business data to help teams: * Understand what is driving revenue and customer growth * Measure marketing performance across digital and offline channels * Attribute outcomes across touchpoints (not last-click) * Quantify true causal lift with incrementality modeling and testing * Optimize marketing spend and bidding using algorithms trained on attributed buyers *** ## What You Need Before You Start To ensure a smooth onboarding, we recommend having the following ready: * Admin access (or credentials) for your marketing and analytics platforms * A primary business system source of truth (POS / ecommerce / CRM) * A clear reporting definition for core KPIs (e.g., revenue, orders, new customers) * A point of contact from your marketing and/or data team for validation *** ## Get Up and Running #### 1. Connect your data sources Bonsai uses secure integrations (“Connect Cards”) to ingest data from platforms such as: * Digital marketing (Google Ads, Meta, TikTok, Amazon, etc.) * Analytics (GA4, Adobe Analytics) * Business systems (POS / ecommerce / CRM / order management) * Offline media (TV/OOH spend and delivery) * Google Search Console (for branded demand insights) Once connected, data will flow automatically into your Bonsai cloud data warehouse.
Connect to BonsaiSecurely connect your sources and destinations. Start here if you’re new to Bonsai./spaces/wBudqXqxQ4IAeXerm1Hd/pages/fNrakZOyICFwM3wLlXsr
Review the Data SchemaUnderstand required fields for business data onboarding./spaces/wBudqXqxQ4IAeXerm1Hd/pages/05hFMMSmegwiqdpVcCS2
Understanding AnalyticsRead how we use analytics data for marketing attribution./spaces/wBudqXqxQ4IAeXerm1Hd/pages/YxwcdYWW1iWwNk3Xhc0c
#### 2. Configure your business KPIs Business Reporting is the foundation for everything in Bonsai. During onboarding, Bonsai works with your team to define and configure: * Revenue and order KPIs * New vs returning customer logic * Custom business metrics (LTV, repeat rate, frequency) * Aggregation rules and date definitions #### 3. Validate the data Before launching measurement views, Bonsai runs a validation process to confirm: * data completeness (missing days, gaps) * schema and formatting consistency * correct KPI definitions and mappings * reconciliation against your source of truth (when available) #### 4. Launch measurement products Once onboarding is complete, you can begin using Bonsai measurement views: * **Business Reporting**: Executive-ready reporting on business outcomes + marketing investment * **Multi-Touch Attribution (MTA)**: Customer journeys + fractional credit across digital touchpoints * **Incrementality (Modeling + Testing)**: Causal lift and ROI measurement across channels * **Budget Planner**: Forecast outcomes and optimize spend allocation * **Algorithms**: AI-driven bidding optimization trained on attributed buyer behavio *** ## Explore the APIs
Developer DocsOne place for endpoints, parameters, and examples for every Bonsai API./spaces/Sc7oU2m62deMCHXGIJKu/pages/p8zOUIttlCmwYA3prGmI
Multi-Touch Attribution APIJourney and touchpoint endpoints plus fractional attribution metrics./spaces/Sc7oU2m62deMCHXGIJKu/pages/stvnulWRkO3p2f1rpf5q
Business Reporting APISpend, impressions, DMA/time dimensions, and modeled business results./spaces/Sc7oU2m62deMCHXGIJKu/pages/GshoR3fXHCmIEwsxwUpK
Audience Analytics APICreate, list, and retrieve audiences for activation./spaces/Sc7oU2m62deMCHXGIJKu/pages/86M9TzCkXoWIIc893Qtw
Incrementality Modeling APIModeled ROI, lift, and forecast curve data for incrementality modeling./spaces/Sc7oU2m62deMCHXGIJKu/pages/usp9RvcNrYYQ0ZU1dY6m
## Help & Resources
Resources OverviewA guided index of external resources for marketers and analysts./spaces/wBudqXqxQ4IAeXerm1Hd/pages/kSr1AxMCbdU8tdBcnlox
FAQsAnswers to common setup, authentication, platform logic, and data questions./spaces/wBudqXqxQ4IAeXerm1Hd/pages/HOwfjP3HVYAPGtcjtumv
TroubleshootingCommon errors and how to fix them quickly./spaces/Sc7oU2m62deMCHXGIJKu/pages/uLlvtureI5giOFxW87qf
Release NotesWhat’s new in the APIs and documentation./spaces/Sc7oU2m62deMCHXGIJKu/pages/vwzsFN7kGvfwkSq0Pbl8
{% hint style="success" %} Pro tip: Bookmark the **Developer Docs** index for quick navigation across all API references. {% endhint %} # Overview Explore APIs, schemas, and resources to power reporting and analysis with foundational marketing and business data. {% hint style="warning" %} **Our API documentation is currently in development and will be published soon.**\ \ Interested in early access? [Contact our team](https://www.bonsaidata.io/demo) to get started! {% endhint %} Get up and running on the latest version of Bonsai’s developer platform:
:chart-column: Business Reporting APIAccess spend, impressions, and ROI data with flexible geo and time dimensions./pages/GshoR3fXHCmIEwsxwUpK
:chart-line-up: Unified Marketing APIAccess normalized cross-channel marketing data including spend, impressions, clicks, and conversions across ad platforms in a unified schema./pages/sQA6qTw1urWmUXPIOWTt
:timeline: Multi-Touch Attribution APIExplore customer journeys, touchpoints, and fractional attribution metrics./pages/stvnulWRkO3p2f1rpf5q
⬢ Marketing Mix Modeling APIRun media mix models, analyze incrementality, and measure lift./pages/usp9RvcNrYYQ0ZU1dY6m
:scale-balanced: Incrementality Testing APIMeasure causal lift through marketing mix models and controlled A/B tests to quantify true incremental impact./pages/Z4whaBHjWPaPCfELiTGN
:people: Coming Soon: Audience Analytics APICreate, sync, and retrieve customer audiences for activation.
:magnifying-glass-dollar: Predictive Buying Algorithm APIOptimize bidding and budget allocation using predictive conversion value models and automated tROAS adjustments./pages/k6q70BgN79W5x0O8sFT0
:earth-americas: Geo APIAccess standardized geographic reference data including DMAs, regions, ZIP mappings, and demographic indices for segmentation and modeling./pages/6dFXxfyrk40Q6Jrnd9ZZ
:gear: TroubleshootingCommon errors and how to fix them quickly./spaces/wBudqXqxQ4IAeXerm1Hd/pages/qoWRAozd92sixKVnvjCp
:bullhorn: Release NotesWhat’s new in the APIs and documentation./spaces/wBudqXqxQ4IAeXerm1Hd/pages/IlDzob8BvgSkVOW3dINq
# API Coming Soon! # Schema This documentation describes the standard tables in your Bonsai data warehouse, enabling reliable access to core marketing and business data with consistent naming, data types, and performance. ## Overview These tables consolidate first-party business outcome data, including revenue, orders, customer attributes, and KPI metrics, into a standardized reporting framework. They serve as the source of truth for measuring business performance across channels, enabling consistent reporting, downstream modeling, and executive-level visibility into marketing impact. *** ### Client Business Results
client_business_results_dma_dev_table schema

Description: Business Results by Bonsai DMA ID | field\_name | is\_nullable | data\_type | definition | | --------------------- | ------------ | --------------- | ---------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. | | dma\_id | YES | INT64 | Bonsai's DMA ID | | spend | YES | FLOAT64 | Ad spend | | impressions | YES | INT64 | Ad impressions | | clicks | YES | INT64 | Ad clicks | | conversions\_3p | YES | FLOAT64 | Ad platform conversions, as reported by the ad platform | | conversion\_value\_3p | YES | FLOAT64 | Ad platform conversion value, as reported by the ad platform | | num\_visits | YES | INT64 | Web or app visits | | num\_visitors | YES | INT64 | Web or app visitors | | metric1–metric20 | YES | INT64 / FLOAT64 | Business-specific KPI metrics (e.g., revenue, page views, conversions) |
client_business_results_dev_mmm_table schema

Description: Business Results for Incrementality Modeling | field\_name | is\_nullable | data\_type | definition | | --------------------- | ------------ | --------------- | ----------------------------- | | client\_number | YES | INT64 | Internal client identifier | | date | YES | DATE | Calendar date | | spend | YES | FLOAT64 | Ad spend | | impressions | YES | INT64 | Ad impressions | | clicks | YES | INT64 | Ad clicks | | conversions\_3p | YES | FLOAT64 | Ad platform conversions | | conversion\_value\_3p | YES | FLOAT64 | Ad platform conversion value | | num\_visits | YES | INT64 | Web/app visits | | num\_visitors | YES | INT64 | Web/app visitors | | metric1–metric20 | YES | INT64 / FLOAT64 | Business-specific KPI metrics |
client_business_results_dev_table schema

Description: Business Results Data Table | field\_name | is\_nullable | data\_type | definition | | --------------------- | ------------ | --------------- | ----------------------------- | | client\_number | YES | INT64 | Internal client identifier | | date | YES | DATE | Calendar date | | spend | YES | FLOAT64 | Ad spend | | impressions | YES | INT64 | Ad impressions | | clicks | YES | INT64 | Ad clicks | | conversions\_3p | YES | FLOAT64 | Ad platform conversions | | conversion\_value\_3p | YES | FLOAT64 | Ad platform conversion value | | num\_visits | YES | INT64 | Web/app visits | | num\_visitors | YES | INT64 | Web/app visitors | | metric1–metric20 | YES | INT64 / FLOAT64 | Business-specific KPI metrics |
### Business Results
business_results_customer_dim_table schema

Description: Business Results at a Customer ID level | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ------------------------------------------------------------------ | | client\_number | YES | INT64 | An internal client identifier | | customer\_id | YES | STRING | Journey customer ID used in Bonsai Platform | | first\_name | YES | STRING | Customer first name | | last\_name | YES | STRING | Customer last name | | email | YES | STRING | Customer email | | email2 | YES | STRING | Secondary email | | email3 | YES | STRING | Tertiary email | | phone | YES | STRING | Customer phone number | | phone2 | YES | STRING | Secondary phone | | phone3 | YES | STRING | Tertiary phone | | zip | YES | STRING | Postal code | | city | YES | STRING | Customer city | | state | YES | STRING | Customer state | | country | YES | STRING | Customer country | | dob | YES | DATE | Date of birth | | gender | YES | STRING | Customer gender | | klaviyo\_id | YES | STRING | Klaviyo platform customer ID | | dim1–dim30 | YES | STRING | Client-defined custom 1P touchpoint dimensions | | flag1–flag25 | YES | BOOL | Logical fields identifying configured customer journey event types |
business_results_order_facts_table schema

Description: Business Results Facts Table | field\_name | is\_nullable | data\_type | definition | | ---------------- | ------------ | --------------- | ----------------------------------------- | | client\_number | YES | INT64 | Internal client identifier | | order\_id | YES | STRING | Unique identifier for an order | | metric1–metric20 | YES | INT64 / FLOAT64 | Business-specific order-level KPI metrics |
business_results_order_dim_table schema

Description: Business Results Order-Level Data Table | field\_name | is\_nullable | data\_type | definition | | ------------------------ | ------------ | ---------- | -------------------------------------- | | client\_number | YES | INT64 | Internal client identifier | | order\_id | YES | STRING | Unique order ID | | order\_type | YES | STRING | Type of business order | | customer\_id | YES | STRING | Journey customer ID | | created\_at | YES | TIMESTAMP | Record creation timestamp | | dayofweek | YES | INT64 | Day of week | | year | YES | STRING | Calendar year (YYYY) | | month | YES | STRING | Calendar month | | dma\_id | YES | INT64 | Bonsai DMA ID | | order\_dim1–order\_dim10 | YES | STRING | Client-defined custom order dimensions | | cookie\_match\_dim1 | YES | STRING | 1P event parameter used for matching | | cookie\_match\_dim2 | YES | STRING | Alternative 1P matching parameter |
# Schema This documentation describes the standard tables in your Bonsai data warehouse, enabling reliable access to core marketing and business data with consistent naming, data types, and performance. ## Overview These tables standardize marketing platform data across channels into a unified schema, normalizing campaign structure, spend, impressions, clicks, and conversion metrics. They serve as the integration layer between external ad platforms and the Bonsai platform, ensuring consistent cross-channel reporting, attribution, and modeling readiness. *** ### Customer Journey Views
cjv_key_gclid_map_table schema

Description: A mapping table for Google click IDs used by the Bonsai platform. | field\_name | is\_nullable | data\_type | definition | | ----------- | ------------ | ---------- | ------------------------------------- | | gclid | YES | STRING | A Google click ID used by Google Ads. |
### Event Touchpoint
event_touchpoint_dim_table schema

Description: A table of characteristics about each touchpoint used by the Bonsai platform | field\_name | is\_nullable | data\_type | definition | | ------------------------ | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | key | YES | STRING | A primary key for the specific interaction or event within the journey. | | journey\_time | YES | INT64 | The timestamp, in UNIX seconds, of the event or interaction within the journey. | | cookie\_id | YES | STRING | the 1P cookie id from web & app event tracking | | cookie\_match\_dim1 | YES | STRING | the 1P event parameter utilized to match event data to business results data | | cookie\_match\_dim2 | YES | STRING | an alternative 1P event parameter utilized to match event data to business results data | | cookie\_match\_flag | YES | INT64 | denotes if a 1P event will be utilzed for cookie\_match\_dim | | region | YES | STRING | Geographical dimension related to the user's location. | | continent | YES | STRING | Geographical dimension related to the user's location. | | dayofweek | YES | INT64 | The day of the week, 1 = Sunday | | medium | YES | STRING | The category of the source. Used to classify the type of channel that drove traffic (e.g., CPC, organic, email). | | referrer | YES | STRING | web or app event referrer information | | mobile\_brand\_name | YES | STRING | User's mobile brand. | | mobile\_model\_name | YES | STRING | The mobile device's model name | | deviceCategory | YES | STRING | User's device category | | product\_category | YES | STRING | The category of the product | | item\_category5 | YES | STRING | the product 5th-level category | | netsalesquantity | YES | INT64 | Sales Quantity | | net\_sales\_amount\_usd | YES | FLOAT64 | Net Sales in US Dollars | | key\_interaction\_flag | YES | INT64 | A binary flag, indicating if an event in the customer journey is eligible for attributed impact | | key\_interaction\_weight | YES | FLOAT64 | the attributable weight assigned for a key event | | dclid | YES | STRING | A click ID used by DoubleClick. | | fbclid | YES | STRING | A click ID used by Facebook and Instagram Ads. | | gbraid | YES | STRING | A Google click ID used for iOS campaigns, specifically for app-to-web measurement on browsers that do not support third-party cookies. (Google Brand Referrer ID) | | gclid | YES | STRING | A Google click ID used by Google Ads. | | ko\_click\_id | YES | STRING | | | li\_fat\_id | YES | STRING | A click ID used by LinkedIn. | | msclkid | YES | STRING | A click ID used by Microsoft Advertising (formerly Bing Ads). | | ttclid | YES | STRING | A click ID used by TikTok for its advertising campaigns. | | twclid | YES | STRING | A click ID used by Twitter (X) for its advertising platform. | | wbraid | YES | STRING | A Google click ID for iOS campaigns, used for web-to-app measurement. | | dim1–dim10 | YES | STRING | Client-defined custom 1st-party touch point dimensions. | | flag1–flag10 | YES | STRING | a logical field, identifying event types for custom configured events in Bonsai customer journey tables |
event_touchpoint_facts_table schema

Description: A table of critical characteristics for each touchpoint in the Bonsai Platform | field\_name | is\_nullable | data\_type | definition | | ------------------------ | ------------ | ---------- | ----------------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | cookie\_id | YES | STRING | the 1P cookie id from web & app event tracking | | cookie\_match\_dim1 | YES | STRING | the 1P event parameter utilized to match event data to business results data | | cookie\_match\_dim2 | YES | STRING | an alternative 1P event parameter utilized to match event data to business results data | | cookie\_match\_flag | YES | INT64 | denotes if a 1P event will be utilzed for cookie\_match\_dim | | journey\_time | YES | INT64 | The timestamp, in UNIX seconds, of the event or interaction within the journey. | | key | YES | STRING | A primary key for the specific interaction or event within the journey. | | key\_interaction\_flag | YES | INT64 | A binary flag, indicating if an event in the customer journey is eligible for attributed impact | | key\_interaction\_weight | YES | FLOAT64 | the attributable weight assigned for a key event | | user\_id | YES | STRING | the user ID captured in 1P event tracking |
### Google Search Console
google_search_console_brand_demand_daily_table schema

Description: A table of data utilized by the Bonsai Platform to measure a client's brand demand, using Google Search Console data | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | -------------------------------------------- | | brand\_demand | YES | FLOAT64 | The ad platform account ID, where applicable | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. |
google_search_console_category_demand_daily_table schema

Description: A table of data utilized by the Bonsai Platform to measure a client's category demand, using Google Search Console data | field\_name | is\_nullable | data\_type | definition | | ---------------- | ------------ | ---------- | ---------------------------------- | | Category\_Demand | YES | FLOAT64 | An index of category search demand | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. |
### Performance Marketing
performance_marketing_campaign_key_all_table schema

Description: A dimension table for all marketing campaigns available in a client's Bonsai platform | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | Platform | YES | STRING | the ad platform |
performance_marketing_campaign_key_table schema

Description: A dimension table for all marketing campaigns available in a client's Bonsai platform | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | medium | NO | ARRAY | The category of the source. Used to classify the type of channel that drove traffic (e.g., CPC, organic, email). | | Platform | YES | STRING | the ad platform | | source | NO | ARRAY | The website origination of a customer journey touchpoint |
performance_marketing_daily_campaign_dma_stats_table schema

Description: A daily stats table, segmented by campaign and DMA, utilized by the Bonsai platform, covering all integrated marketing channels. | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | dma\_id | YES | INT64 | Bonsai's DMA ID | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
performance_marketing_daily_campaign_stats_table schema

Description: A daily stats table, segmented by campaign , utilized by the Bonsai platform, covering all integrated marketing channels. | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | impressions | YES | FLOAT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
performance_marketing_daily_dma_stats_table schema

Description: A daily stats table, segmented by DMA, utilized by the Bonsai platform, covering all integrated marketing channels. | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ------------------------------------------------------------ | | account\_id | YES | STRING | The ad platform account ID, where applicable | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | dma\_id | YES | INT64 | Bonsai's DMA ID | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
performance_marketing_daily_region_stats_campaign_table schema

Description: A daily stats table, segmented by campaign and region, utilized by the Bonsai platform, covering all integrated marketing channels. | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | country | YES | STRING | Geographical dimension related to the user's location. | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | region | YES | STRING | Geographical dimension related to the user's location. | | spend | YES | FLOAT64 | ad spend |
performance_marketing_daily_stats_table schema

Description: A daily stats table, utilized by the Bonsai platform, covering all integrated marketing channels. | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ------------------------------------------------------------ | | account\_id | YES | STRING | The ad platform account ID, where applicable | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
### Google Analytics 4
ga4_event_dim_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------------------- | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | key | YES | STRING | A primary key for the specific interaction or event within the journey. | | journey\_time | YES | INT64 | The timestamp, in UNIX seconds, of the event or interaction within the journey. | | date | YES | DATE | The calendar date of the event. | | year | YES | INT64 | the year, YYYY | | month | YES | INT64 | The calendar month | | week | YES | INT64 | the week of the year (1-53) | | dayofweek | YES | INT64 | The day of the week, 1 = Sunday | | event\_name | YES | STRING | the name of the customer behavior event | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | source | YES | STRING | The website origination of a customer journey touchpoint | | medium | YES | STRING | The category of the source. Used to classify the type of channel that drove traffic (e.g., CPC, organic, email). | | cookie\_id | YES | STRING | the 1P cookie id from web & app event tracking | | cookie\_match\_dim1 | YES | STRING | the 1P event parameter utilized to match event data to business results data | | cookie\_match\_dim2 | YES | STRING | an alternative 1P event parameter utilized to match event data to business results data | | cookie\_match\_flag | YES | INT64 | denotes if a 1P event will be utilzed for cookie\_match\_dim | | session\_id | YES | INT64 | the 1P event tracking session ID | | stream\_id | YES | STRING | the 1P event stream ID | | user\_id | YES | STRING | the user ID captured in 1P event tracking | | transaction\_id | YES | STRING | the Order ID used in the Bonsai Platform | | continent | YES | STRING | Geographical dimension related to the user's location. | | sub\_continent | YES | STRING | Geographical dimension related to the user's location. | | country | YES | STRING | Geographical dimension related to the user's location. | | region | YES | STRING | Geographical dimension related to the user's location. | | metro | YES | STRING | Geographical dimension related to the user's location. | | deviceCategory | YES | STRING | User's device category | | mobile\_brand\_name | YES | STRING | User's mobile brand. | | mobile\_marketing\_name | YES | STRING | The mobile device's marketing name | | mobile\_model\_name | YES | STRING | The mobile device's model name | | operating\_system | YES | STRING | User's operating system. | | operating\_system\_version | YES | STRING | User's operating system, version segmented. | | referrer | YES | STRING | web or app event referrer information | | item\_category | YES | STRING | the highest-level product category | | item\_category2 | YES | STRING | the product sub-category | | item\_category3 | YES | STRING | the product 3rd-level category | | item\_category4 | YES | STRING | the product 4th-level category | | item\_category5 | YES | STRING | the product 5th-level category | | product\_category | YES | STRING | The category of the product | | product\_brand | YES | STRING | The Brand of the product | | product\_name | YES | STRING | The name of the product | | product\_sku | YES | STRING | The product SKU | | netsalesquantity | YES | INT64 | Sales Quantity | | net\_sales\_amount\_usd | YES | FLOAT64 | Net Sales in US Dollars | | key\_interaction\_flag | YES | INT64 | A binary flag, indicating if an event in the customer journey is eligible for attributed impact | | key\_interaction\_weight | YES | FLOAT64 | the attributable weight assigned for a key event | | dclid | YES | STRING | A click ID used by DoubleClick. | | fbclid | YES | STRING | A click ID used by Facebook and Instagram Ads. | | gbraid | YES | STRING | A Google click ID used for iOS campaigns, specifically for app-to-web measurement on browsers that do not support third-party cookies. (Google Brand Referrer ID) | | gclid | YES | STRING | A Google click ID used by Google Ads. | | ko\_click\_id | YES | STRING | | | li\_fat\_id | YES | STRING | A click ID used by LinkedIn. | | msclkid | YES | STRING | A click ID used by Microsoft Advertising (formerly Bing Ads). | | ttclid | YES | STRING | A click ID used by TikTok for its advertising campaigns. | | twclid | YES | STRING | A click ID used by Twitter (X) for its advertising platform. | | wbraid | YES | STRING | A Google click ID for iOS campaigns, used for web-to-app measurement. | | dim1–dim10 | YES | STRING | Client-defined custom 1st-party touch point dimensions. | | flag1–flag10 | YES | STRING | a logical field, identifying event types for custom configured events in Bonsai customer journey tables |
ga4_reservepageinstantiated_daily schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ------------------------------ | | client\_number | YES | INT64 | An internal client identifier. | | event\_ts | YES | TIMESTAMP | the event timestamp | | metric\_date | YES | TIMESTAMP | The calendar date |
ga4_reservepageinstantiated_event schema

Description: | field\_name | is\_nullable | data\_type | definition | | ---------------- | ------------ | ---------- | -------------------------------------------- | | client\_number | NO | INT64 | An internal client identifier. | | event\_date | YES | STRING | The calendar date of the event. | | event\_id | YES | STRING | the event ID | | event\_timestamp | YES | INT64 | the event timestamp, in UNIX seconds | | event\_ts | YES | TIMESTAMP | the event timestamp | | ga\_session\_id | YES | INT64 | the session ID from a 1P event tracking tool | | metric\_date | YES | TIMESTAMP | The calendar date |
### Google Ads
google_ads_campaign_key_all_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | Platform | YES | STRING | the ad platform |
google_ads_campaign_key_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | medium | NO | ARRAY | The category of the source. Used to classify the type of channel that drove traffic (e.g., CPC, organic, email). | | Platform | YES | STRING | the ad platform | | source | NO | ARRAY | The website origination of a customer journey touchpoint |
google_ads_daily_dma_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | dma\_id | YES | INT64 | Bonsai's DMA ID | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
google_ads_daily_region_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | country | YES | STRING | Geographical dimension related to the user's location. | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | region | YES | STRING | Geographical dimension related to the user's location. | | spend | YES | FLOAT64 | ad spend |
google_ads_daily_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
### Facebook Ads
facebook_ads_campaign_key_all_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | Platform | YES | STRING | the ad platform |
facebook_ads_campaign_key_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | medium | NO | ARRAY | The category of the source. Used to classify the type of channel that drove traffic (e.g., CPC, organic, email). | | Platform | YES | STRING | the ad platform | | source | NO | ARRAY | The website origination of a customer journey touchpoint |
facebook_ads_daily_dma_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | INT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | INT64 | ad platform conversions, as reported by the ad platform | | Date | YES | DATE | The calendar date of the event. | | dma\_id | YES | INT64 | Bonsai's DMA ID | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
facebook_ads_daily_region_stats_campaign_table schema

Description: A daily Facebook Ads stats table segmented by campaign and region. | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | INT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | INT64 | ad platform conversions, as reported by the ad platform | | country | YES | STRING | Geographical dimension related to the user's location. | | Date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | region | YES | STRING | Geographical dimension related to the user's location. | | spend | YES | FLOAT64 | ad spend |
facebook_ads_daily_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | INT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | INT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
### Instagram Ads
instagram_ads_campaign_key_all_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | Platform | YES | STRING | the ad platform |
instagram_ads_campaign_key_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | medium | NO | ARRAY | The category of the source. Used to classify the type of channel that drove traffic (e.g., CPC, organic, email). | | Platform | YES | STRING | the ad platform | | source | NO | ARRAY | The website origination of a customer journey touchpoint |
instagram_ads_daily_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | INT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | INT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
### Reddit Ads
reddit_ads_campaign_key_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | medium | NO | ARRAY | The category of the source. Used to classify the type of channel that drove traffic (e.g., CPC, organic, email). | | Platform | YES | STRING | the ad platform | | source | NO | ARRAY | The website origination of a customer journey touchpoint |
reddit_ads_daily_dma_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | INT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | INT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | dma\_id | YES | INT64 | Bonsai's DMA ID | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
reddit_ads_daily_region_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | INT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | INT64 | ad platform conversions, as reported by the ad platform | | country | YES | STRING | Geographical dimension related to the user's location. | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | region | YES | STRING | Geographical dimension related to the user's location. | | spend | YES | FLOAT64 | ad spend |
reddit_ads_daily_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | INT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | INT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
### Youtube Ads
youtube_ads_campaign_key_all_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | Platform | YES | STRING | the ad platform |
youtube_ads_campaign_key_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | Channel | YES | STRING | the marketing channel associated with the row of data | | client\_number | YES | INT64 | An internal client identifier. | | medium | NO | ARRAY | The category of the source. Used to classify the type of channel that drove traffic (e.g., CPC, organic, email). | | Platform | YES | STRING | the ad platform | | source | NO | ARRAY | The website origination of a customer journey touchpoint |
youtube_ads_daily_region_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | country | YES | STRING | Geographical dimension related to the user's location. | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | region | YES | STRING | Geographical dimension related to the user's location. | | spend | YES | FLOAT64 | ad spend |
youtube_ads_daily_stats_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
youtube_ads_daily_stats_dma_campaign_table schema

Description: | field\_name | is\_nullable | data\_type | definition | | ----------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | account\_id | YES | STRING | The ad platform account ID, where applicable | | campaign\_id | YES | STRING | The campaign ID utilized in the Bonsai platform, applicable to different levels of marketing depending on the input platform | | clicks | YES | INT64 | ad clicks | | client\_number | YES | INT64 | An internal client identifier. | | conversion\_value | YES | FLOAT64 | ad platform conversion value, as reported by the ad platform | | conversions | YES | FLOAT64 | ad platform conversions, as reported by the ad platform | | date | YES | DATE | The calendar date of the event. | | dma\_id | YES | INT64 | Bonsai's DMA ID | | impressions | YES | INT64 | ad impressions | | Platform | YES | STRING | the ad platform | | reach | YES | INT64 | ad reach, in Users | | spend | YES | FLOAT64 | ad spend |
# Schema This documentation describes the standard tables in your Bonsai data warehouse, enabling reliable access to core marketing and business data with consistent naming, data types, and performance. ## Overview These tables consolidate customer journey data, linking marketing touchpoints to downstream outcomes such as orders and revenue. They serve as the foundation for multi-touch attribution, enabling clear visibility into how media interactions influence customer behavior and conversion. *** ### Customer Journey Views
cjv_dashboard_channel_platform_campaign_dma_table schema

Description: The Bonsai Attribution Results Summary Table, by Campaign and DMA. | field\_name | is\_nullable | data\_type | definition | | ------------------------------ | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. | | channel | YES | STRING | The marketing channel associated with the row of data. | | platform | YES | STRING | The ad platform. | | campaign | YES | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | dma\_id | YES | INT64 | Bonsai's DMA ID. | | impressions | YES | INT64 | Ad impressions. | | clicks | YES | INT64 | Ad clicks. | | visits | YES | INT64 | Web or app visits. | | cost | YES | FLOAT64 | Ad spend. | | att\_metric\_1–att\_metric\_20 | YES | FLOAT64 | Fractional attributed metrics associated with this touchpoint using Bonsai’s multi-touch attribution model. |
cjv_dashboard_channel_platform_campaign_region_table schema

Description: The Bonsai Attribution Results Summary Table, by Campaign and Region. | field\_name | is\_nullable | data\_type | definition | | ------------------------------ | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. | | channel | YES | STRING | The marketing channel associated with the row of data. | | platform | YES | STRING | The ad platform. | | campaign | YES | STRING | An organized effort to promote a product or service. | | region | YES | STRING | Geographical dimension related to the user's location. | | impressions | YES | INT64 | Ad impressions. | | clicks | YES | INT64 | Ad clicks. | | visits | YES | INT64 | Web or app visits. | | cost | YES | FLOAT64 | Ad spend. | | att\_metric\_1–att\_metric\_20 | YES | FLOAT64 | Fractional attributed metrics associated with this touchpoint using Bonsai’s multi-touch attribution model. |
cjv_attribution_simplified_details_table schema

Description: The Bonsai Attribution Results by Customer Outcome, without order-level breakdown. | field\_name | is\_nullable | data\_type | definition | | ---------------------------------------------------------------------------------- | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | customer\_id | YES | STRING | The Customer ID. | | date | YES | DATE | The calendar date of the event. | | created\_at | YES | TIMESTAMP | The timestamp the record was created. | | order\_id | YES | STRING | The unique identifier for an order, if one was placed. | | order\_type | YES | STRING | The type of business order. | | campaign | YES | STRING | Campaign associated with the interaction. | | channel | YES | STRING | Marketing channel associated with the interaction. | | platform | YES | STRING | Ad platform associated with the interaction. | | source | YES | STRING | The website origination of a customer journey touchpoint. | | medium | YES | STRING | Channel classification (e.g., CPC, organic, email). | | deviceCategory | YES | STRING | User's device category. | | operating\_system | YES | STRING | User's operating system. | | continent | YES | STRING | Geographical dimension related to the user's location. | | country | YES | STRING | Geographical dimension related to the user's location. | | region | YES | STRING | Geographical dimension related to the user's location. | | metro | YES | STRING | Geographical dimension related to the user's location. | | dma\_id | YES | INT64 | Bonsai's DMA ID. | | attributed\_metric1–attributed\_metric20 | YES | FLOAT64 | Fractional attributed metrics associated with this touchpoint using Bonsai’s multi-touch attribution model. | | dim1–dim10 | YES | STRING | Client-defined custom 1P touchpoint dimensions. | | order\_dim1–order\_dim10 | YES | STRING | Client-defined custom 1P order dimensions. | | flag1–flag10 | YES | STRING | Logical fields identifying configured event types in the customer journey. | | gclid / gbraid / wbraid / fbclid / msclkid / ttclid / twclid / li\_fat\_id / dclid | YES | STRING | Platform click identifiers used for attribution matching. |
cjv_table schema

Description: The Customer Journey Data Table containing interaction-level journey records. | field\_name | is\_nullable | data\_type | definition | | -------------------------------------------------------- | ------------ | --------------- | ----------------------------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | journey\_customer\_id | YES | STRING | The unique internal identifier for the customer's journey. | | date | YES | DATE | The calendar date of the event. | | journey\_time | YES | INT64 | UNIX timestamp of the event within the journey. | | source | YES | STRING | The website origination of a customer journey touchpoint. | | medium | YES | STRING | Channel classification (e.g., CPC, organic, email). | | campaign | YES | STRING | Campaign associated with the interaction. | | deviceCategory | YES | STRING | User's device category. | | operating\_system | YES | STRING | User's operating system. | | continent | YES | STRING | Geographical dimension related to the user's location. | | country | YES | STRING | Geographical dimension related to the user's location. | | region | YES | STRING | Geographical dimension related to the user's location. | | metro | YES | STRING | Geographical dimension related to the user's location. | | attributed\_metric1–attributed\_metric20 | YES | FLOAT64 | Fractional attributed metrics associated with this touchpoint using Bonsai’s multi-touch attribution model. | | metric1–metric20 | YES | INT64 / FLOAT64 | Business-specific metrics associated with an interaction. | | dim1–dim10 | YES | STRING | Client-defined custom 1P touchpoint dimensions. | | order\_dim1–order\_dim5 | YES | STRING | Client-defined custom 1P order dimensions. | | key\_interaction\_flag | YES | INT64 | Binary flag indicating if an event is eligible for attributed impact. | | order\_flag | YES | INT64 | Binary flag indicating if an order occurred. | | gclid / fbclid / msclkid / ttclid / twclid / li\_fat\_id | YES | STRING | Platform click identifiers used for attribution matching. |
### Lifetime Value
ltv_rfm_table schema

Description: The Bonsai Customer Lifetime Value and Recency, Frequency, and Monetization Data Table. | field\_name | is\_nullable | data\_type | definition | | ---------------------------- | ------------ | ---------- | ---------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | journey\_customer\_id | YES | STRING | The unique internal identifier for the customer's journey. | | customer\_value | YES | FLOAT64 | Total customer lifetime value. | | orders | YES | INT64 | Total number of orders for a customer. | | touchpoints | YES | INT64 | Total customer journey touchpoints. | | key\_interactions | YES | FLOAT64 | Total number of key interactions for a customer. | | first\_date | YES | DATE | First interaction date. | | first\_purchase\_date | YES | DATE | First purchase date. | | recent\_date | YES | DATE | Most recent interaction date. | | recent\_purchase\_date | YES | DATE | Most recent purchase date. | | days\_since\_touchpoint | YES | INT64 | Days since first interaction. | | days\_since\_first\_purchase | YES | INT64 | Days since first purchase. | | days\_alive | YES | INT64 | Days between yesterday and first record. |
### Percent Attributable
percent_attributable_business_table schema

Description: The trackable percentage of customer business results in Bonsai attribution. | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | -------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | pct\_att | YES | FLOAT64 | The trackable percentage of overall business results viewable by 1P attribution. |
percent_attributable_by_channel_platform_table schema

Description: The trackable percentage of each channel, by platform. | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | -------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | channel | YES | STRING | The marketing channel associated with the row of data. | | platform | YES | STRING | The ad platform. | | visits | YES | INT64 | Web or app visits. | | clicks | YES | INT64 | Ad clicks. | | pct\_att | YES | FLOAT64 | The trackable percentage of overall business results viewable by 1P attribution. |
# Schema This documentation describes the standard tables in your Bonsai data warehouse, enabling reliable access to core marketing and business data with consistent naming, data types, and performance. ## Overview These tables power Bonsai’s incrementality modeling framework by structuring media inputs and business outcomes into statistically modeled results. They serve as the source of truth for measuring true incremental lift, separating baseline performance from marketing-driven impact across channels and time. *** ### MMM Feature Data
raw_feature_data_validation_table schema

Description: The data validation table for input data versus Bonsai Incrementality feature model data. | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. | | channel | YES | STRING | The marketing channel associated with the feature. | | platform | YES | STRING | The ad platform. | | account\_id | YES | STRING | The ad platform account ID from which a campaign derived. | | campaign | YES | STRING | An organized effort to promote a product or service. | | campaign\_id | YES | STRING | The ad platform ID of the campaign. | | feature | YES | STRING | The strategic segment of marketing activity measured in the Bonsai incrementality model. | | impressions | YES | FLOAT64 | Ad impressions. | | clicks | YES | INT64 | Ad clicks. | | reach | YES | INT64 | Media reach by users. | | conversions | YES | FLOAT64 | Media conversions, as measured by ad platform conversion data. | | cost | YES | FLOAT64 | Media ad cost. |
### MMM Results
incrementality_daily_results_table schema

Description: The table of results from all live Bonsai incrementality models. | field\_name | is\_nullable | data\_type | definition | | ---------------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. | | channel | YES | STRING | The marketing channel associated with the feature. | | feature | YES | STRING | The strategic segment of marketing activity measured in the Bonsai incrementality model. | | model\_number | YES | INT64 | The model number for the client in Bonsai incrementality products. | | training\_number | YES | INT64 | The training number for the Bonsai incrementality model. | | type | YES | STRING | The type of result: Base, Base+, or Incremental. | | live\_flag | YES | INT64 | Denotes whether an Incrementality model is live in the Bonsai platform. | | spend | YES | FLOAT64 | Media ad cost. | | incremental\_dv | YES | FLOAT64 | Incremental outcomes. | | incremental\_dv\_value | YES | FLOAT64 | Incremental outcome value. |
incrementality_daily_predicted_actual_table schema

Description: Bonsai Incrementality model results compared to actual business outcomes. | field\_name | is\_nullable | data\_type | definition | | ---------------- | ------------ | ---------- | ----------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. | | model\_number | YES | INT64 | The model number for the client. | | training\_number | YES | INT64 | The training number for the model. | | actual\_value | YES | FLOAT64 | The actual measured business outcome. | | predicted\_value | YES | FLOAT64 | The predicted outcome from the Bonsai incrementality model. |
### Forecaster
forecaster_validator_table schema

Description: The Budget Planner forecast validation data, comparing forecasts to actual outcomes. | field\_name | is\_nullable | data\_type | definition | | ----------------------------- | ------------ | ---------- | ------------------------------------------------------------------ | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. | | year | YES | INT64 | The calendar year (YYYY). | | month | YES | INT64 | The month of the year. | | channel | YES | STRING | The marketing channel associated with the feature. | | feature | YES | STRING | The strategic segment of marketing activity measured in the model. | | model\_number | YES | INT64 | The model number for the client. | | type | YES | STRING | The type of result: Base, Base+, or Incremental. | | bid\_ratio | YES | FLOAT64 | Estimated auction position relative to historical position. | | spend\_forecast | YES | FLOAT64 | The spend forecasted. | | incremental\_dv\_actual | YES | FLOAT64 | Incremental outcomes, actual. | | incremental\_dv\_forecast | YES | FLOAT64 | Incremental outcomes forecasted. | | incremental\_return\_actual | YES | FLOAT64 | Incremental return, actual. | | incremental\_return\_forecast | YES | FLOAT64 | Incremental return forecasted. | | incremental\_return\_rank | YES | INT64 | Incremental return volume rank (descending). | | max\_inc\_return\_forecast | YES | FLOAT64 | Maximum incremental return forecasted. | | min\_inc\_return\_forecast | YES | FLOAT64 | Minimum incremental return forecasted. |
forecaster_table schema

Description: The table of all Budget Planner forecasts, for all scenarios. | field\_name | is\_nullable | data\_type | definition | | -------------------------------- | ------------ | ---------- | ------------------------------------------------------------------ | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the forecast. | | year | YES | INT64 | The calendar year (YYYY). | | month | YES | INT64 | The month of the year. | | weekday | YES | INT64 | The calendar weekday (1 = Sunday). | | channel | YES | STRING | The marketing channel associated with the feature. | | feature | YES | STRING | The strategic segment of marketing activity measured in the model. | | model\_number | YES | INT64 | The model number for the client. | | forecast\_number | YES | INT64 | Bonsai internal ID for the Budget Planner forecast result. | | type | YES | STRING | The type of result: Base, Base+, or Incremental. | | Bid\_Ratio | YES | FLOAT64 | Estimated auction position relative to historical position. | | spend\_base | YES | FLOAT64 | Base spend. | | spend\_forecast | YES | FLOAT64 | Forecasted spend. | | click\_base | YES | FLOAT64 | Base click estimate. | | click\_forecast | YES | FLOAT64 | Forecasted click totals. | | impression\_base | YES | FLOAT64 | Base expected impressions. | | impression\_forecast | YES | FLOAT64 | Forecasted impressions. | | reach\_base | YES | FLOAT64 | Base media reach. | | reach\_forecast | YES | FLOAT64 | Forecasted media reach. | | incremental\_dv\_base | YES | FLOAT64 | Base business outcomes. | | incremental\_dv\_forecast | YES | FLOAT64 | Forecasted incremental outcomes. | | incremental\_dv\_value\_base | YES | FLOAT64 | Base business outcome value. | | incremental\_dv\_value\_forecast | YES | FLOAT64 | Forecasted incremental outcome value. | | incremental\_return\_forecast | YES | FLOAT64 | Forecasted incremental return. | | max\_return\_forecast | YES | FLOAT64 | Maximum incremental return forecasted across all features. | | next\_yr\_cpc\_index | YES | FLOAT64 | Forecasted CPC index. | | next\_yr\_demand\_index | YES | FLOAT64 | Forecasted demand index. | | next\_yr\_value\_index | YES | FLOAT64 | Forecasted customer response index. |
# Schema This documentation describes the standard tables in your Bonsai data warehouse, enabling reliable access to core marketing and business data with consistent naming, data types, and performance. ## Overview These tables support controlled audience and geographic A/B testing within the Bonsai platform. They consolidate test configurations, performance metrics, and statistical lift results to quantify causal impact and determine whether marketing investments drive measurable business improvement. *** ### Performance Stats
inc_test_daily_stats_table schema

Description: The daily performance stats for business and marketing channels included in audience A/B tests measured by the Bonsai platform. | field\_name | is\_nullable | data\_type | definition | | --------------------- | ------------ | ---------- | -------------------------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | date | YES | DATE | The calendar date of the event. | | test\_id | YES | INT64 | The ID number for the test in the Bonsai platform. | | test\_group | YES | STRING | The test group assignment in the Bonsai platform. | | test\_period | YES | STRING | The test period designation in the Bonsai platform. | | test\_type | YES | STRING | The type of test. | | customer\_id | YES | STRING | The ad platform customer ID, where applicable. | | dma\_id | YES | STRING | Bonsai's DMA ID. | | impressions | YES | FLOAT64 | Ad impressions. | | clicks | YES | FLOAT64 | Ad clicks. | | cost | YES | FLOAT64 | Media ad cost. | | google\_impressions | YES | FLOAT64 | Ad impressions from Google Ads. | | google\_clicks | YES | FLOAT64 | Ad clicks from Google Ads. | | google\_cost | YES | FLOAT64 | Media cost from Google Ads. | | facebook\_impressions | YES | FLOAT64 | Ad impressions from Meta Ads. | | facebook\_clicks | YES | FLOAT64 | Ad clicks from Meta Ads. | | facebook\_cost | YES | FLOAT64 | Media cost from Meta Ads. | | metric1–metric10 | YES | FLOAT64 | Business-specific metrics (e.g., revenue, page views, conversions) associated with the test measurement. |
mmt_table schema

Description: Record of Incrementality Tests measured by the Bonsai Platform. | field\_name | is\_nullable | data\_type | definition | | --------------------- | ------------ | ---------- | ----------------------------------------------------------------------- | | client\_number | YES | INTEGER | An internal client identifier. | | test\_id | YES | INTEGER | The ID number for the test in the Bonsai platform. | | test\_desc | YES | STRING | | | test\_name | YES | STRING | | | test\_hypothesis | YES | STRING | | | methodology | YES | STRING | | | channels | YES | STRING | | | success\_metrics | YES | STRING | | | test\_dma | YES | STRING | | | control\_dma | YES | STRING | | | test\_pre\_date | YES | DATE | | | test\_pre\_end\_date | YES | DATE | | | test\_start\_date | YES | DATE | | | test\_end\_date | YES | DATE | | | iroi\_metric | YES | STRING | | | inc\_vpc\_metric | YES | STRING | | | aud\_ab\_test\_id | YES | INTEGER | | | live\_flag | YES | BOOLEAN | Denotes whether an Incrementality model is live in the Bonsai platform. | | metric1\_name | YES | STRING | | | metric2\_name | YES | STRING | | | metric3\_name | YES | STRING | | | metric4\_name | YES | STRING | | | metric5\_name | YES | STRING | | | metric6\_name | YES | STRING | | | metric7\_name | YES | STRING | | | metric8\_name | YES | STRING | | | metric9\_name | YES | STRING | | | metric10\_name | YES | STRING | | | metric11\_name | YES | STRING | | | metric12\_name | YES | STRING | | | metric13\_name | YES | STRING | | | metric14\_name | YES | STRING | | | metric15\_name | YES | STRING | | | metric16\_name | YES | STRING | | | metric17\_name | YES | STRING | | | metric18\_name | YES | STRING | | | metric19\_name | YES | STRING | | | metric20\_name | YES | STRING | | | mmt\_metric\_1\_type | YES | STRING | | | mmt\_metric\_2\_type | YES | STRING | | | mmt\_metric\_3\_type | YES | STRING | | | mmt\_metric\_4\_type | YES | STRING | | | mmt\_metric\_5\_type | YES | STRING | | | mmt\_metric\_6\_type | YES | STRING | | | mmt\_metric\_7\_type | YES | STRING | | | mmt\_metric\_8\_type | YES | STRING | | | mmt\_metric\_9\_type | YES | STRING | | | mmt\_metric\_10\_type | YES | STRING | | | mmt\_metric\_11\_type | YES | STRING | | | mmt\_metric\_12\_type | YES | STRING | | | mmt\_metric\_13\_type | YES | STRING | | | mmt\_metric\_14\_type | YES | STRING | | | mmt\_metric\_15\_type | YES | STRING | | | mmt\_metric\_16\_type | YES | STRING | | | mmt\_metric\_17\_type | YES | STRING | | | mmt\_metric\_18\_type | YES | STRING | | | mmt\_metric\_19\_type | YES | STRING | | | mmt\_metric\_20\_type | YES | STRING | | | accepted\_flag | YES | INTEGER | | | test\_type | YES | STRING | The type of test. |
### Lift Stats
mmt_difference_significance_python_table schema

Description: The lift statistics measured, by test, in the Bonsai platform. | field\_name | is\_nullable | data\_type | definition | | -------------- | ------------ | ---------- | ------------------------------------------------------------------ | | client\_number | YES | INT64 | An internal client identifier. | | test\_id | YES | INT64 | The ID number for the test in the Bonsai platform. | | test\_type | YES | STRING | The type of test. | | metric\_name | YES | STRING | The name of the business metric measured in the test. | | lift | YES | FLOAT64 | The test result lift metric for a Bonsai test. | | CI | YES | STRING | The confidence interval level for the test result. | | lower\_CI | YES | FLOAT64 | The lower bound of the lift result for the given confidence level. | | higher\_CI | YES | FLOAT64 | The upper bound of the lift result for the given confidence level. |
# Schema This documentation describes the standard tables in your Bonsai data warehouse, enabling reliable access to core marketing and business data with consistent naming, data types, and performance. ## Overview These tables operationalize predictive click valuation and bidding optimization. They capture modeled click-level value scores, upload activity to ad platforms, and tROAS adjustment logic, enabling more efficient media spend allocation based on predicted customer value rather than last-click outcomes. *** ### Google Ads Algorithm
pcv_troas_adjuster_table schema

Description: The specific tROAS changes applied (or suggested) for every campaign on pCV management. | field\_name | is\_nullable | data\_type | definition | | ------------------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | campaign | YES | STRING | The campaign name running on pCV. | | campaign\_id | YES | STRING | The ad platform campaign ID for the campaign. | | segments\_date | YES | DATE | The calendar date of the event. | | pcv\_flag | YES | INT64 | A binary flag. 1 = the campaign runs on pCV. 0 = the campaign does not run on pCV. | | impressions | YES | INT64 | Ad impressions. | | clicks | YES | INT64 | Ad clicks. | | spend | YES | FLOAT64 | Ad platform media spend. | | missed\_clicks | YES | FLOAT64 | Eligible ad clicks lost due to improper daily budget allocation, relative to tROAS bid setting. | | missed\_impressions | YES | FLOAT64 | Eligible ad impressions lost due to improper daily budget allocation, relative to tROAS bid setting. | | CPC | YES | FLOAT64 | Cost-per-click based on media spend. | | Optimized\_CPC | YES | FLOAT64 | The optimal available cost-per-click given existing media spend. | | efficiency\_improvement | YES | FLOAT64 | The difference between Optimized\_CPC and CPC. | | tROAS\_increase\_required | YES | FLOAT64 | The percentage increase required for a pCV campaign to achieve Optimized\_CPC. |
pcv_historical_table schema

Description: A historical record of Google Ads clicks scored by pCV. | field\_name | is\_nullable | data\_type | definition | | ----------------------- | ------------ | ---------- | -------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | gclid | YES | STRING | The Google Ads Click ID. | | date | YES | DATE | The calendar date of the event. | | country | YES | STRING | Utilized for Google Ads Conversion API acceptance. | | index | YES | FLOAT64 | The predicted click value from pCV. | | append\_datetime | YES | DATETIME | The date of the click upload to Google Ads. | | conversion\_event\_time | YES | INT64 | Utilized for Google Ads Conversion API acceptance. |
pcv_upload_table schema

Description: The pCV clicks and values uploaded into Google Ads, updated daily. | field\_name | is\_nullable | data\_type | definition | | ----------------------- | ------------ | ---------- | -------------------------------------------------- | | client\_number | YES | INT64 | An internal client identifier. | | gclid | YES | STRING | The Google Ads Click ID. | | date | YES | DATE | The calendar date of the event. | | country | YES | STRING | Utilized for Google Ads Conversion API acceptance. | | index | YES | FLOAT64 | The predicted click value from pCV. | | conversion\_event\_time | YES | INT64 | Utilized for Google Ads Conversion API acceptance. |
# Schema This documentation describes the standard tables in your Bonsai data warehouse, enabling reliable access to core marketing and business data with consistent naming, data types, and performance. ## Overview These tables provide standardized geographic reference data used across the Bonsai platform. They map postal codes, regions, cities, and DMAs while supplying demographic indices to enable consistent geographic segmentation, modeling, and reporting. *** ### Geo Mapping
dma_table schema

Description: A reference table of DMA data for the Bonsai platform. | field\_name | is\_nullable | data\_type | definition | | ----------- | ------------ | ---------- | ---------------- | | dma\_id | YES | INT64 | Bonsai's DMA ID. | | dma\_name | YES | STRING | DMA name. |
dma_demographics_indicies_data_table schema

Description: A reference table of DMA demographic and household indices for the Bonsai platform. | field\_name | is\_nullable | data\_type | definition | | ------------------- | ------------ | ---------- | ------------------------------ | | dma\_id | YES | INT64 | Bonsai's DMA ID. | | dma\_name | YES | STRING | DMA name. | | pop\_index | YES | FLOAT64 | US population index. | | tv\_index | YES | FLOAT64 | US TV household index. | | household\_index | YES | FLOAT64 | US household index. | | male\_index | YES | FLOAT64 | US male population index. | | female\_index | YES | FLOAT64 | US female population index. | | male\_1824\_index | YES | FLOAT64 | Male 18–24 population index. | | female\_1824\_index | YES | FLOAT64 | Female 18–24 population index. | | male\_2534\_index | YES | FLOAT64 | Male 25–34 population index. | | female\_2534\_index | YES | FLOAT64 | Female 25–34 population index. | | male\_3544\_index | YES | FLOAT64 | Male 35–44 population index. | | female\_3544\_index | YES | FLOAT64 | Female 35–44 population index. | | male\_4554\_index | YES | FLOAT64 | Male 45–54 population index. | | female\_4554\_index | YES | FLOAT64 | Female 45–54 population index. | | male\_5564\_index | YES | FLOAT64 | Male 55–64 population index. | | female\_5564\_index | YES | FLOAT64 | Female 55–64 population index. | | male\_65\_index | YES | FLOAT64 | Male 65+ population index. | | female\_65\_index | YES | FLOAT64 | Female 65+ population index. |
zip_to_dma schema

Description: A reference table mapping US Postal Codes to Bonsai DMA IDs. | field\_name | is\_nullable | data\_type | definition | | ----------- | ------------ | ---------- | ---------------- | | zip\_code | YES | STRING | US postal code. | | dma\_id | YES | INT64 | Bonsai's DMA ID. |
zip_to_region schema

Description: A reference table mapping US Postal Codes to US State/Region. | field\_name | is\_nullable | data\_type | definition | | ------------ | ------------ | ---------- | --------------------------------------------------------- | | zip\_code | YES | STRING | US postal code. | | region\_code | YES | STRING | Bonsai's region ID. | | region\_abbr | YES | STRING | Region abbreviation, typically the US state abbreviation. | | region\_name | YES | STRING | Region name, typically referring to US state. |
city schema

Description: A reference table of cities in the Bonsai platform. | field\_name | is\_nullable | data\_type | definition | | ----------- | ------------ | ---------- | ----------------- | | city\_id | YES | INT64 | Bonsai's city ID. | | city\_name | YES | STRING | City name. |
# Overview The Resources section provides educational documentation to help customers understand Bonsai’s data requirements, integrations, and technical standards. This content is designed to guide clients through onboarding, integrations, data preparation, activation, and troubleshooting with clarity and confidence. *** ### What you’ll find here * FAQs * Example data schemas for Ads, Analytics, and Business Data * Integration requirements and specifications * Connect Card walkthroughs and setup guides * Data formatting expectations * Technical documentation to support onboarding These materials are intended to help customers prepare their systems correctly and accelerate time to implementation and activation. *** ### Purpose The Resources section exists to: * Provide transparency into our data requirements * Reduce friction during onboarding * Empower customers to prepare clean, structured data * Support successful activation If you are preparing data for onboarding, configuring an integration, or launch activation, start here. # FAQs This FAQ page provides quick answers to common questions about Bonsai’s platform integrations, data onboarding requirements, and measurement capabilities. ## Platform Integrations ### Data Onboarding 1. **What types of data does Bonsai need to build Business Reporting?**\ Bonsai requires digital marketing data (ad platform performance and spend) and business / point-of-sale (POS) data (orders, revenue, customers). These datasets form the foundation of the Business Reporting product and enable accurate measurement of business outcomes alongside marketing activity. 2. **What types of data does Bonsai need to build Multi-Touch Attribution (MTA)?**\ Bonsai requires digital marketing data, analytics data (e.g., GA4 or Adobe Analytics), Google Merchant Center data, and business / point-of-sale (POS) data. Together, these sources enable Bonsai to construct customer journeys and assign fractional credit to marketing touchpoints that contributed to business outcomes. 3. **What types of data does Bonsai need to build Incrementality Modeling?**\ Bonsai requires digital marketing data, offline marketing data (e.g., TV, radio, OOH), business / POS data, and Google Search Console data. Incrementality modeling relies on a combination of marketing exposure signals and business outcomes to estimate causal impact beyond what can be observed through tracking-based attribution alone. 4. **What types of data does Bonsai need to build Algorithms?**\ Bonsai’s bidding algorithms require the same data inputs as Multi-Touch Attribution because algorithm training depends on attributed buyer behavior and outcomes. Bonsai requires digital marketing data, analytics data, and business / POS data in order to build the training audience and model the features associated with valuable customers. 5. **Do I have to pay per connector?**\ Pricing depends on your Bonsai plan and the integrations required to support your use case. Some plans include a standard set of connectors, while others may vary based on the number of platforms, data volume, refresh cadence, and optional integrations. Your Bonsai account team can confirm the pricing model for your deployment. *** ## Measurement ### Business Reporting 1. **Can I see both offline and digital sales on this page?**\ Yes. Bonsai can support visibility into both online (digital) and offline (in-store / POS) sales, based on what is included in your business source data. Sales are reflected according to the transaction records provided in your point-of-sale or ecommerce systems. 2. **Would you consider this a C-suite level report?**\ Yes. Business Reporting is designed to provide an executive-ready view of core business performance, including revenue, customer growth, and high-level marketing efficiency. It is intended to support leadership reporting and decision-making with trusted, business-outcome-based metrics. 3. **Are my analytics metrics shown on this page?**\ No. Business Reporting focuses on point-of-sale/order outcomes and marketing platform performance. Analytics data is primarily used for customer journey development, attribution, and other measurement products rather than being a core component of the Business Reporting view. 4. **Why are “new customers” at a business level more important than “new users” in analytics or ad platforms?**\ Business-defined new customers are based on first-party purchase behavior and represent the most reliable source of truth. Analytics and ad platforms rely heavily on cookie/device identifiers that can reset or expire (often within 30–90 days), which makes long-term identity and new customer measurement less accurate—especially as privacy constraints continue to limit tracking. 5. **Can I export this data?**\ Yes. Bonsai supports export functionality and allows you to download reporting data as a CSV file for offline analysis or internal reporting workflows. 6. **How long does it take to see business data populated once I onboard my data?**\ Business data is typically the first dataset configured because it is the foundation for Bonsai measurement products and often requires the most customization. In many cases, Business Reporting can be live within approximately five business days after required access and data delivery are in place. 7. **Can I see lifetime value (LTV) and purchase frequency?**\ Yes. Bonsai supports configurable business metrics, including lifetime value, repeat purchase rate, and purchase frequency. These metrics can be added and configured through the Business Metrics Configuration settings based on the fields available in your business data. 8. **Is there any data Bonsai cannot or will not configure?**\ Yes. Bonsai does not populate critical business KPIs using third-party conversion tracking when it conflicts with validated first-party outcomes. Business KPIs should be derived from authoritative business systems (POS, ecommerce, ERP, CRM) rather than ad platform conversion estimates. 9. **Can my team own the data and query it for our own reporting?**\ Yes. The Bonsai platform is powered by a data warehouse in Google Cloud Platform (GCP). Clients can either allow Bonsai to own and manage the warehouse while granting query access, or ownership can be transferred to the client at any time. ### Multi-Touch Attribution (MTA) 1. **What do I use MTA for?**\ Multi-Touch Attribution is best used to evaluate the effectiveness of digital marketing channels. Bonsai builds customer journeys and assigns fractional attribution across marketing touchpoints that contributed to outcomes, allowing teams to understand the relative contribution of channels beyond last-click reporting. 2. **How do I configure MTA KPIs?**\ MTA KPIs are configured using the business metrics defined in Business Reporting. Any business metric configured in the platform (e.g., orders, revenue, new customers) can be selected as an attribution KPI. 3. **Can I still use Bonsai if I don’t get 100% traffic consent to analytics?** Yes. Like all modern analytics and attribution platforms, Bonsai can only directly measure and attribute activity from users who have provided the required consent. In practice, most businesses see less than 100% consent rates, which means a portion of traffic will not be available for user-level attribution. Bonsai’s measurement products are built to maximize data quality and matching within the consented and observable traffic across channels and brands. While the non-consented portion of traffic cannot be directly attributed due to privacy requirements—and there is no technical workaround for this across the industry—Bonsai enables full-funnel measurement through complementary statistical methods such as incrementality testing. This approach allows teams to understand true marketing impact across their entire business, even when direct attribution is limited by consent. 4. **How does Bonsai join advertising, analytics, and business/point-of-sale data to build attribution?**\ Bonsai uses analytics data as a linking layer between advertising platforms and business or POS systems. Ad identifiers such as click IDs are first matched to analytics events, and a separate unique identifier is then used to connect analytics data to downstream revenue or POS records. Bonsai does not join advertising data directly to point-of-sale systems — analytics serves as the intermediary that enables accurate attribution and measurement. 5. **Why is my attributed sales number lower than my actual sales reported by finance?**\ Not every sale can be attributed back to a measurable digital marketing touchpoint. This is expected and typically results from customers purchasing without clicking an ad, limited tracking coverage, incomplete analytics history, or privacy-related loss of identity signals. 6. **How can I view more granular results?**\ You can drill down into attribution using customizable categories based on your campaign mapping and grouping configuration. Bonsai supports grouping campaigns into meaningful buckets so that performance can be interpreted at a level aligned with your internal reporting structure. 7. **How do I read attributed sales?**\ Attributed sales represent the outcomes credited back to ad clicks that occurred on a specific date. For example, if the platform shows $338K attributed sales on August 25, 2025, this means users who clicked ads on that date eventually generated purchases totaling $338K in fractional credit. 8. **How long is the attribution window?**\ Bonsai MTA is windowless and looks back across all available history. The primary constraint is how far back analytics data is available, because Bonsai relies on first-party analytics data to build customer journeys. 9. **Is this the same as Google’s data-driven attribution (DDA)?**\ No. Bonsai MTA differs from Google DDA because Bonsai supports true business / POS outcomes, is not biased toward any one advertising platform, and is designed to unify attribution across multiple channels. Google DDA is constrained to the Google ecosystem and does not provide the same cross-channel, business-outcome-driven view. 10. **Why does it look like attribution is going down while business cost is increasing?**\ This can occur when incremental efficiency declines due to audience saturation, competition, spend shifting into lower-performing tactics, or tracking coverage changes. It can also indicate an increasing share of spend going to placements that do not produce measurable click journeys. In these scenarios, Incrementality Modeling is often the best method to validate true causal impact. 11. **How do I use Detailed Order Attribution?**\ Detailed Order Attribution is used to view attribution based on when an actual sale occurred rather than when a click occurred. This is useful for answering questions such as which marketing channels contributed to the sales that occurred in a specific reporting month. 12. **How granular can I view MTA data?**\ Granularity depends on the attribution view. In the Attribution page, you can typically view results at the campaign level. In Detailed Order Attribution, you can view campaign-level performance and further drill down by landing page, creative, or any other analytics tag available in the dataset. 13. **How is the attribution weighting scheme determined? Does it change over time or by customer?**\ Bonsai employs a linear attribution model that allows for custom weighting based on touchpoint type, touchpoint number, and other factors. However, Bonsai always starts with a purely linear (unweighted) model in order to maintain MTA as a truly deterministic tool — meaning we don't inject assumptions about what's impactful and what isn't. Any weighting customization is applied on top of that foundation and is configured per client based on their specific needs. 14. **Does journey length affect how attribution credit is allocated?**\ Bonsai's attribution model is windowless. An ad click that first brought a new prospect to your site will continue to receive fractional credit for all subsequent purchases in that customer's journey, regardless of how much time has passed. The only practical limitation is data availability — how far back analytics history exists. 15. **Are high-consideration products treated differently in MTA?**\ The windowless nature of Bonsai's MTA makes it particularly well-suited for measuring marketing's impact on products with long consideration times and many touchpoints. Because there is no attribution window cutoff, early-funnel touchpoints are not penalized for purchases that occur months later. 16. **Are there any adjustments made to avoid retargeting bias?**\ Bonsai's MTA inherently reduces retargeting bias by only crediting touchpoints for purchases that occurred *after* the click. We find that the very first click in a customer's journey is more accurately valued in Bonsai's MTA results compared to models like Google's DDA, which tend to devalue the initial "acquisition" touchpoint and overvalue the final "conversion" touchpoint due to attribution window constraints. 17. **How does Bonsai handle channel correlations in MTA?**\ The customer journey dataset that powers MTA can be queried to understand whether certain channels tend to work together to drive outcomes. More importantly, Bonsai uses the results of its ridge-regression marketing mix models — which measure and account for channel collinearity — to populate the iROI values displayed on the MTA page. 18. **How does Bonsai's MTA approach compare to logistic regression or Markov-chain attribution models?**\ Bonsai takes a two-pronged approach rather than choosing a single model type: MTA serves as the deterministic, campaign-level (and more granular) optimization tool, while Marketing Mix Modeling serves as the probabilistic measure of marketing's full incremental impact. These two methods complement each other. MTA also has an additional powerful application as a training dataset for Bonsai's predictive buying algorithms. 19. **Has Bonsai empirically validated its MTA results with incrementality testing?**\ Yes. Each time Bonsai deploys its MTA-powered predictive buying algorithm for a new customer, an incrementality test (Matched Market Test) can be run to measure lift on business outcomes using a Difference-in-Differences methodology. This provides an empirical proof point for the algorithm's impact and, by extension, the quality of the MTA signals used to train it. ### Marketing Mix Modeling 1. **What is a Marketing Mix Model?** \ Bonsai's marketing-mix models are built using ridge regression models, which are statistical analysis tools that measure the causality between many independent variables (including all marketing tactics, plus external factors like seasonality, category demand, promotions, etc) and one dependent variable (for example, sales, new customers, etc). The output of the model is an answer to how causal each independent variable is on the dependent variable, and how much business would have been lost if that particular element were turned off. 2. **What do I use Incrementality Modeling for, and how is it different from MTA?**\ Incrementality Modeling estimates causal impact at an aggregate level, answering what would have happened if a marketing channel were turned off. It does not use individual customer journey data or rely on attribution of any kind. Incrementality is especially important for offline media and upper-funnel channels where click-based tracking is incomplete. 3. **What questions can I answer with Bonsai’s Incrementality Model?**\ Bonsai’s Incrementality Model helps identify which channels truly drove revenue, how much lift each channel generated, and what the true ROI is by tactic. It also supports questions around seasonality, diminishing returns, spend optimization, budget shifting scenarios, undervalued or overinvested channels, and forecasting outcomes under different spend levels. 4. **What is a feature?**\ A feature is a configurable subset of marketing activity. Features can represent a channel subset, tactic type, campaign grouping, or a highly granular campaign-level segment depending on how your taxonomy is configured. 5. **What does “incremental” mean?**\ Incremental outcomes are results that would not have occurred without the marketing activity. This represents the true lift driven by marketing beyond baseline demand. 6. **What does “base” mean?**\ Base represents the expected outcomes with no marketing investment, driven by underlying demand such as brand equity, seasonality, category demand, and external macro factors. Over time, base can decay if marketing remains off for an extended period. 7. **What does “base+” mean?**\ Base+ represents lift from drivers that influence demand but are not scalable with spend, such as Brand Search or Email. These drivers can elevate results beyond baseline, but they cannot be increased linearly through budget increases. 8. **Why do my results on MTA look different from Incrementality?**\ Differences are expected because the methodologies measure different concepts. MTA attributes results based on observed click journeys, while Incrementality predicts causal lift and estimates what would have happened without marketing. It is common for results to differ at campaign or feature level.
### Incrementality Testing 1. **What is a Matched Market Test?** \ A matched market test is accomplished by deploying a certain marketing or loyalty tactic in one set of markets, and continuing business-as-usual in a set of historically similarly performing markets. 2. **How do you measure success?**\ Bonsai measures test success using lift percentage derived from a Difference-in-Differences (DiD) method. This compares changes in test markets pre/post against changes in control markets pre/post, helping isolate the impact of a strategy even when markets are not perfectly matched and external factors influence performance. 3. **How does Bonsai measure the return on an incrementality test?**\ Bonsai calculates incremental ROI (iROI) by comparing the revenue driven by the tested strategy against the spend required to generate it — both measured using the same Difference-in-Differences methodology. This gives a clear, apples-to-apples view of whether the strategy delivered a positive return, independent of baseline performance differences between markets. 4. **Does seasonal demand (like holidays) affect incrementality test results?**\ No. External demand factors like holiday seasonality affect all markets equally. If a test shows +10% lift during the holiday season, it means sales increased *even more* in the test markets relative to control markets — the lift figure isolates the strategy's impact above and beyond any broad demand changes. 5. **What if my test and control markets have different baseline demand levels?**\ The Difference-in-Differences method accounts for this. If one market naturally outperforms another year-round, the DiD calculation still isolates lift by measuring *change* in each market relative to its own pre-test baseline — not by comparing absolute sales levels between markets. 6. **How should I interpret the confidence range shown on the Incrementality Testing page?**\ The confidence range reflects the range within which the true lift likely falls, not a pass/fail threshold. For example, a result showing 70% confidence that lift is between 26% and 54% means you can be reasonably confident that a meaningful positive lift exists — even if the precise number is uncertain. A wide range typically indicates more data or a longer test period would sharpen the estimate. 7. **How do I calculate incremental ROI (iROI) from a test?**\ iROI is calculated by dividing incremental revenue by incremental spend. Incremental revenue is the lift percentage multiplied by pre-test baseline outcomes and their value (e.g., LTV). Incremental spend is calculated the same way as lift — applying the DiD method to spend rather than sales, then multiplying the spend lift percentage by the pre-test baseline spend. 8. **How is it possible to see positive lift when test market sales actually declined during the test?**\ Lift is relative, not absolute. If control market sales declined 20% while test market sales only declined 10%, the DiD calculation yields a positive lift — because without the tested strategy, the test market would have also declined 20%. The strategy effectively "saved" sales that would have otherwise been lost. 9. **What if test markets received more spend than control markets — does that invalidate the results?**\ Not at all. In a matched market test, the test markets are intentionally run with a new strategy or investment level — that's the point of the test. The Difference-in-Differences method isolates the lift attributable to the strategy by comparing each market's *change* relative to its own baseline, so differences in spend level are accounted for. What matters is whether the incremental spend generated a positive return, and that's exactly what the test is designed to measure. 10. **What goes into designing a matched market test?**\ A well-designed test defines six things upfront: the test and comparison time periods, a clear hypothesis and decision criteria for what you'll do based on results, the success metric you're measuring, which markets will serve as test and control groups, the investment level being tested, and the specific campaigns involved. Getting these right before the test begins is what makes results actionable. 11. **How long should an incrementality test run, and what should I measure?**\ It depends on your conversion timeline. For businesses where marketing drives an immediate or near-term action (like an online purchase), a 30-day test measuring that outcome directly is often sufficient. For businesses with longer sales cycles — such as leads that convert to sales over 30–45 days — you can either measure the leading indicator (leads) over 30 days, or measure actual sales over a longer window. Bonsai works with you to select the approach that fits your business. *** ## Activation ### Predictive Buying Algorithms 1. **What is a Predictive Buying Algorithm?** A Predictive Buying Algorithm is a machine learning model that scores the predicted value of ad clicks in real time and feeds those scores back into ad platforms like Google Ads, Microsoft, Meta, TikTok, etc to guide bidding toward higher-value users. Rather than optimizing toward conversions equally, the algorithm helps ad platforms prioritize clicks that are most likely to result in high-value customers — based on your actual first-party business data. The result is a smarter bidding system that reflects what a valuable customer looks like for your specific business, not just who is likely to click or convert. 2. **What data does Bonsai need to build the predictive bidding algorithm?** The algorithm draws on three primary data sources: website analytics data, ad platform data (such as Google Ads), Google Merchant Center data, and order or transaction data. These are unified to reconstruct the full customer journey from purchase back through marketing interactions, which becomes the training dataset for the model. 3. **How does the algorithm determine which clicks are most valuable?** Bonsai begins by unifying your analytics, ad platform, and transaction data to reconstruct the full customer journey from purchase back through every marketing interaction. From there, a multi-touch attribution model evaluates more than 40 signals related to customer behavior and value — including purchase frequency, order value, repeat purchases, and long-term customer lifetime behavior. Each click is then scored based on how closely it resembles the patterns associated with your most valuable customers historically. Those scores are sent back to ad platforms daily as predicted dollar values, training the ad platforms's smart bidding system to find more users who match that high-value profile. 4. **How does Bonsai send its signals back to ad platforms?**\ On a daily basis, Bonsai sends ad platforms a feed containing each Click ID paired with a predicted dollar value based on the algorithm's scoring model. Each ad platform's smart bidding system then uses those signals to find and prioritize similar high-value clicks going forward. 5. **How does this differ from Google’s native smart bidding?**\ Bonsai's algorithm runs alongside Google's bidding system, not instead of it. Rather than replacing Google's smart bidding, Bonsai enhances it by supplying better training signals. Where Google's native smart bidding optimizes around conversion events, Bonsai assigns predictive value to clicks using your first-party customer data and feeds those values back through click IDs — allowing Google to optimize toward higher-quality users, not just conversions. The typical process: existing campaigns are cloned for the test, a short learning period runs on CPC bidding, campaigns then transition to tROAS bidding, and Bonsai's algorithm continuously feeds value signals back into Google to guide optimization. 6. **Can the model increase or decrease the value of conversions?**\ Yes. The algorithm can amplify the value signal of conversions that indicate higher customer value. For example, a conversion may be assigned a higher value if the system predicts that user is particularly valuable. Earlier approaches attempted to send zero-value signals for low-value clicks, but testing showed stronger performance when focusing only on positive value signals. 7. **Can the algorithm factor in business constraints like inventory or pricing?**\ Yes. Additional business inputs can be incorporated into the model, including product inventory levels, pricing, out-of-stock status, seasonality signals, and product feed data. These signals help the algorithm adjust bidding aggressiveness based on real-time business conditions and product availability. 8. **Will implementing the algorithm require restructuring our campaigns?**\ No. The algorithm is designed to work with your existing account structure — we clone your current campaigns and configure them for the test markets. If structural issues are identified during the process (such as overly restrictive negative keyword lists or constraints limiting audience discovery), any recommended changes would be discussed and agreed upon collaboratively with your team. 9. **How often does the algorithm change bidding targets?**\ Adjustments are most frequent during the first few days while the system stabilizes. After the initial learning period, changes become much less frequent. If performance indicators suggest missed opportunity or inefficiency, the system provides dashboard guidance to adjust targets in collaboration with the marketing team. 10. **How long does it take to get the algorithm up and running?**\ The typical timeline is approximately 30 days to ingest data and train the model, followed by approximately 30 days running the live test to measure lift. Most tests reach statistical significance within that 30-day window, though some may run longer depending on data volume. 11. **What kind of performance improvement can we expect?**\ Clients implementing Bonsai's predictive bidding algorithm typically see around a 30% performance lift, though results vary depending on the account, data quality, and inputs. Every new algorithm deployment is validated with an incrementality test so results are measured against a true control, not just a before-and-after comparison. 12. **What is a feature?**\ A feature is a measurable attribute of a click or user interaction. Examples include device type, search query characteristics, hour of day, geography, landing page behavior, operating system version, and other signals available through your marketing and analytics datasets. 13. **What does fit score mean?**\ Fit score represents the relative predicted value of a feature segment. In general, a higher fit score indicates that traffic with that feature profile is expected to be more valuable based on historical buyer patterns. 14. **How do I read the scatter plots for each feature?**\ Scatter plots show how expected value changes across feature values. They are used to interpret which segments of a feature correlate with stronger outcomes and where performance varies across distributions. 15. **Is this a replacement for conversion data?**\ Bonsai algorithm conversion data is intended for ad buying optimization rather than serving as official purchase conversion reporting. In many cases, teams can reduce reliance on platform conversion tracking for bidding while still using Bonsai measurement products (MTA and Incrementality) to validate business lift and channel impact. 16. **Can I test the algorithm before scaling across the whole channel?**\ Yes. Bonsai validates new algorithms using Incrementality Testing (Matched Market Testing). A subset of markets are selected as test markets where the algorithm runs, while matched control markets remain unchanged, and lift is measured using a Difference-in-Differences method. 17. **What is `bds_pcv_conversion` and why is it higher than official purchase conversions in Google Ads?**\ `bds_pcv_conversion` is a conversion goal used for ad buying purposes to support Bonsai’s algorithm training and optimization. It identifies an attributed buyer audience and trains a model to score new clicks (GCLIDs) based on similarity to historical valuable buyers using signals such as search queries, landing page views, time-of-day patterns, and geography. The score represents predicted downstream value (often modeled as predicted LTV), which is why it may not align with official purchase conversion counts and values. 18. **Why are we seeing reduced spending on listing group placements in PMax?**\ This can occur when Performance Max reallocates spend toward placements and inventory it predicts will meet the optimization goal more efficiently. Common drivers include feed eligibility changes, asset performance shifts, competitive auction dynamics, or algorithm learning that prioritizes other placement types based on predicted conversion likelihood. 19. **Why do we see such a high proportion of brand traffic in Google campaigns like PMax?**\ Google’s systems naturally optimize toward high-intent users, which frequently includes people searching for brand terms. Since brand traffic is more likely to convert, PMax often prioritizes these auctions, increasing the share of brand-driven traffic. Bonsai’s modeling and campaign structure are designed to rebalance this behavior and drive more incremental non-brand growth over time. ### Budget Planner 1. **What is the Budget Planner?** The Budget Planner is a forecasting tool that helps you model performance and business outcomes across different spend scenarios — before committing budget. You can use it to identify the allocation that maximizes profit, estimate expected revenue at a given spend level, and understand how shifting budget across channels may impact next-month performance. It transforms your historical marketing data into forward-looking guidance, so budget decisions are driven by predicted outcomes rather than intuition. 2. **How much data does a channel need before it can be used in the Budget Planner?** For reliable Budget Planner forecasting, twelve months of data is ideal — enough to capture seasonality and long-term performance patterns. A minimum of three months is recommended before including a new channel in Incrementality Modeling, which feeds into the planner's spend-response curves. If you've recently launched a new channel and don't yet have sufficient history, Bonsai's Incrementality Testing can provide early signal on that channel's lift and impact while the longer data history builds. # Connect Cards Connect Cards are Bonsai’s pre-built integrations that securely connect your marketing, analytics, and business data sources to the Bonsai platform. Once a Connect Card is enabled and authenticated, Bonsai automatically ingests data into your dedicated cloud data warehouse on a scheduled cadence—eliminating manual file transfers and supporting faster onboarding, validation, and reporting across all Bonsai products. {% embed url="" %} # Marketing Ad Platform APIs Overview Bonsai ingests marketing performance and metadata from paid media platforms via each platform’s advertising API. While the exact available fields vary by channel, most platforms support a consistent reporting structure: account → campaign → ad group/ad set → ad/creative, with performance metrics provided by date and optional breakdowns. ## Common data ingested across platforms: **Identifiers & hierarchy**\ account\_id, campaign\_id, ad\_group\_id/ad\_set\_id, ad\_id, creative\_id **Time segmentation**\ date / date\_start, date\_stop, hour **Core performance metrics**\ impressions, clicks, spend/cost, ctr, cpc, cpm **Conversion metrics**\ conversions, conversion\_value/revenue, roas; breakdowns by action type (varies by platform) **Targeting/segment dimensions (optional)**\ device, geo, audience, placements, demographic pivots, etc.   ## Google Ads API documentation: This connector uses the [Google Ads Big Query Data Transfer Service](https://docs.cloud.google.com/bigquery/docs/google-ads-transfer?_gl=1*10mulal*_ga*NjIyMTk5MjkwLjE3NDI2MTYxNDk.*_ga_WH2QY8WWF5*czE3Njg0MzAwODckbzEzMyRnMSR0MTc2ODQzMDA5OCRqNDkkbDAkaDA.#console) **Typical ingested entities:** * Customer/account * Campaigns, ad groups, ads, keywords * Search terms (when enabled/available) * Assets (extensions), product listing groups (Shopping/PMax depending on access) **Typical fields ingested:** * customer\_id, campaign\_id, ad\_group\_id, ad\_id, campaign.name * impressions, clicks, cost\_micros, ctr, average\_cpc * conversions, conversion\_value, all\_conversions * segments.date, segments.device, segments.network * gclid ## Meta Ads (Facebook/Instagram) API documentation: This connector uses [Graph API version v23.0](https://developers.facebook.com/docs/graph-api/changelog/version23.0) **Typical ingested entities:** * Ad Accounts * Campaigns → Ad Sets → Ads * Creatives * Insights reporting at multiple levels **Typical fields ingested:** * account\_id, campaign\_id, adset\_id, ad\_id (+ names) * impressions, clicks, spend, reach, frequency * actions, action\_values, attribution windows ## Microsoft Advertising (Bing) API documentation: This connector uses [Microsoft Advertising API version 13.0](https://learn.microsoft.com/en-us/advertising/guides/get-started?view=bingads-13) **Typical ingested entities:** * Accounts * Campaigns, ad groups, ads, keywords * Performance reports (report “types” / column sets) **Typical fields ingested:** * AccountId, CampaignId, AdGroupId, AdId, KeywordId * impressions, clicks, spend, CTR, average CPC * conversions, revenue (depending on tracking setup) * msclkid ## TikTok Ads API documentation: This connector uses [TikTok Ads API v1.3](https://business-api.tiktok.com/portal/docs?id=1740579480076290) **Typical ingested entities:** * Advertiser account * Campaigns → Ad Groups → Ads * Creative / video engagement metrics **Typical fields ingested:** * advertiser\_id, campaign\_id, adgroup\_id, ad\_id * impressions, clicks, spend, ctr, cpc * video engagement metrics (views, quartiles; platform dependent) ## LinkedIn Ads API documentation: This connector uses [LinkedIn Marketing API version 202503](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/ads-overview?view=li-lms-2025-03) **Typical ingested entities:** * Accounts * Campaign groups / campaigns * Creatives * Ad analytics pivots (incl. professional demographics) **Typical fields ingested:** * account, campaign, creative identifiers * impressions, clicks, spend, engagement metrics * optional pivots: job title, company size, job function, seniority (privacy thresholds may apply) ## Amazon Ads API documentation: This connector uses [Amazon Ads API v1](https://advertising.amazon.com/API/docs/en-us/reference/api-overview?utm_source=chatgpt.com) **Typical ingested entities:** * Sponsored Products / Sponsored Brands / Sponsored Display reporting * Campaigns, ad groups, ads, keywords/targets * DSP reporting (if applicable) **Typical fields ingested:** * campaign/ad group/ad IDs (varies by ad product type) * impressions, clicks, cost * attributed purchases, sales, units, ROAS (varies by report type) ## Pinterest Ads API documentation: This connector uses [Pinterest Ads API v5](https://developers.pinterest.com/docs/api/v5/) **Typical ingested entities:** * Ad accounts * Campaigns, ad groups, ads (Pins) * Analytics reporting endpoints **Typical fields ingested:** * ad\_account\_id, campaign\_id, ad\_group\_id, ad\_id * impressions, clicks, spend * conversion metrics depending on configured tag/events # Business Data & Point of Sale (POS) Requirements To accurately measure marketing performance and connect it to real business outcomes, Bonsai requires access to your Business data such as Point of Sale (POS), Online Orders, and/or In-store orders. This document outlines what data is needed, why it matters, and how to prepare it — whether your data lives in Azure SQL, Snowflake, BigQuery, Redshift, or another data warehouse. *** ### **Overview** Bonsai uses your business data to connect customer actions (seen in your analytics platforms like GA4) with business outcomes (recorded in your POS or order management systems). This enables: * **Multi-Touch Attribution (MTA):** attributing revenue to the marketing interactions that led to it. * **Incrementality Measurement:** quantifying the lift caused by marketing campaigns. * **Customer Insights:** tracking lifetime value (LTV), retention, and cross-channel behavior. To make this work, Bonsai needs transaction-level data that can be matched to your marketing analytics data using a **shared unique identifier** (such as a transaction\_id or order\_id). *** ### **How Marketing & Business Data Connect** When a customer completes a purchase — online or in-store — the transaction ID should appear in both: 1. Your business data (e.g., POS, CRM, or OMS systems), and 2. Your analytics data (e.g., GA4, Adobe Analytics, etc.) via a “purchase” or “business outcome” event. Bonsai uses this shared ID (sometimes referred to as a cookie match dimension) to tie web and ad interactions to real sales. Without this shared key, marketing touchpoints and sales data remain disconnected — making true ROI analysis impossible. {% hint style="info" %} Bonsai uses analytics data as a linking layer between advertising platforms and business or POS systems. Ad identifiers such as click IDs are first matched to analytics events, and a separate unique identifier is then used to connect analytics data to downstream revenue or POS records. Bonsai does not join advertising data directly to point-of-sale systems — analytics serves as the intermediary that enables accurate attribution and measurement. {% endhint %}
*** ### **Data Domains & Requirements** POS and order data is typically organized into several domains. The schemas below are platform-agnostic examples of the fields Bonsai uses to support measurement, modeling, and attribution. **Order Level Sales is required** for Bonsai products and represents the minimum dataset necessary to enable core attribution and modeling workflows. The required fields may be delivered as a single table or distributed across multiple tables, provided keys and relationships are maintained. All additional domains (e.g., Sales Detail / Line Items, Customer, Retail Store) are optional and enable enhanced functionality and reporting, including: * Product-level attribution and SKU/service performance (requires Sales Detail) * Audience Analytics and customer segmentation (requires Customer) * Store/location-level reporting and geographic cuts (enhanced by Retail Store) **Privacy / PII Handling** Bonsai does not require raw personally identifiable information (PII) values. If preferred, PII fields (e.g., email address, phone number, street address) may be anonymized prior to delivery. Bonsai supports hashed identifiers (SHA-256 or SHA-512 preferred) for privacy-preserving identity matching. Contact your Bonsai Customer Engineer to align on hashing standards and expected formats. #### **1. Order Level Sales** Represents each unique transaction or order. | Field | Required | Description | Example | | ------------------------- | -------- | ------------------------------------------------------------------------- | ----------------------------- | | **transaction\_id\*** | Y | Unique ID for the transaction/order | 2025-05-22-ATL-000982 | | **store\_zip** | N | Store location: can be zip, dma, city, state | 06831 | | **store\_id** | N | Unique store or location id for the business | store123 | | **customer\_id** | Y | Links to customer table (nullable) | CUST-9981 | | **customer\_zip** | Y | Customer location: can be zip, full address, city, state | 123 Main Street, Chicago, IL | | **customer\_phone** | Y\*\* | Customer phone number | 800-300-9089 | | **customer\_phone2** | N | Alternative customer phone number | 800-400-2356 | | **transaction\_datetime** | Y | Timestamp of sale (UTC) | 2025-05-22T19:45:00Z | | **updated\_at** | Y | Timestamp of when the sale or transaction status or customer data changed | 2025-06-22T18:45:00Z | | **subtotal\_amount** | Y | Total before tax/discount | 350.00 | | **discount\_amount** | Y | Total discounts applied | -10.00 | | **tax\_amount** | Y | Tax collected | 21.00 | | **total\_amount** | Y | Final transaction total | 361.00 | | **payment\_type** | N | Tender method (cash, credit, gift card, etc.) | Credit Card | | **status** | Y | Transaction status | Completed / Voided / Returned | \*Commonly used as the connection between your analytics (GA4) data and point of sales/transactions. This may be called something different depending on the business. \*\*Phone numbers are only required for businesses that rely on call tracking or phone-based lead attribution (e.g., service or appointment-driven businesses). For retail or e-commerce businesses where purchases occur directly online or in-store, phone fields are optional. #### **2. Sales Detail (Line Item Level)** Breaks down each order into its component products or services. | Field | Required | Description | Example | | -------------------- | -------- | ----------------------------------- | --------------------- | | **transaction\_id** | Y | Foreign key linking to Sales Header | 2025-05-22-ATL-000982 | | **line\_id** | N | Unique line within the transaction | 1 | | **sku\*** | Y | Product SKU | TIRE-A123 | | **quantity** | Y | Units sold | 4 | | **unit\_price** | Y | Price per unit | 80.00 | | **line\_discount** | Y | Discount at item level | 5.00 | | **extended\_amount** | Y | Quantity × unit price | 320.00 | \*This can be a traditional product SKU (retail inventory item) or a service identifier for non-inventory line items (e.g., labor, installation, membership, diagnostic fee). #### **3. Customer** Captures the buyer’s identity and key attributes. | Field | Required | Description | Example | | ------------------ | -------- | ----------------------------- | ------------------------ | | **customer\_id** | Y | Unique ID per customer | CUST-8821 | | **customer\_name** | N | Customer name | John Doe | | **email** | Y | Customer email | 9b74c9897b... | | **phone\_number** | Y | Customer phone number | 800-330-9089 | | **phone\_number2** | N | | | | **address** | Y | Customer address | 123 Main St, Chicago, IL | | **postal\_code** | Y | Customer ZIP or postal code | 63110 | | **created\_at** | N | Customer record creation time | 2023-02-05T00:00:00Z | **Privacy Note:**\ If hashed or anonymized identifiers are preferred for compliance and security (SHA-256 or SHA-512 is preferred), please reach out to your Bonsai Customer Engineer to share which hash function you use. #### **4. Retail Store** Details for each retail location. | Field | Required | Description | Example | | ------------------ | -------- | ---------------- | ---------------- | | **store\_id** | Y | Unique store key | STL01 | | **store\_name** | Y | Store name | Bonsai - Chicago | | **store\_zip** | Y | Zip code | 60007 | | **address\_city** | Y | City | Chicago | | **address\_state** | Y | State | IL | *** ### **Data Delivery Guidelines** Bonsai’s preferred method for onboarding business data is through our prebuilt Connect Cards, which provide secure, out-of-the-box integrations for most major cloud data warehouses and business systems. Please review the Business Point of Sale Connect Cards to begin onboarding your data. If you have a preferred method of data sharing, Bonsai can share Google Cloud Storage Bucket or Google Big Query table destination information for data transfers. **Preferred cadence:** Daily incremental loads\ **Required history:** At least 24 months\ **Minimum viable dataset:** Order Level Sales *** ### **Data Quality & Validation** Bonsai requests raw, untransformed data to ensure full transparency and control over joins, transformations, and validations. Clients are encouraged to review the validation checklist and provide a data dictionary or lookup table with key field definitions and business logic notes. This enables accurate validation during the proof-of-concept build. Once the initial connection is complete, Bonsai automates all data ingestion and quality checks, requiring no ongoing client effort. Bonsai validates all incoming data against a core checklist: | Category | Validation Item | Action | Expected Outcome | | ------------------------------ | --------------------------- | ------------------------------------------------------------------------- | -------------------------------------- | | **Incremental Logic** | Incremental Key Present | Identify columns used for delta loads (updated\_at, modified\_date, etc.) | Key consistently populated and updated | | | Incremental Key Behavior | Identify column updates on inserts/updates (no nulls or static values) | Timestamp updates on all modified rows | | **Data History** | History Coverage | Earliest and latest transaction dates | ≥ 24 months available | | | Archive Data | Check if history tables exist beyond live data | Archive accessible if needed | | **Volume Profiling** | Average Daily Volume | Count of daily transactions | Consistent daily volume; note peaks | | | Volume Consistency | Identify outliers (batch imports, missing days) | No unexplained gaps/spikes | | **Reconciliation** | Reconciliation Method Known | Client’s internal totals process (register, ERP, etc.) | Reconciliation source identified | | | Daily Totals Match | Bonsai-calculated totals vs client control totals | Within ±0.1% variance | | **Timezone Standardization** | Timestamp Source | Determine if timestamps are UTC or local | Timezone clearly defined | | | Normalization Plan | Plan for UTC normalization | UTC normalization strategy confirmed | | **PII Handling** | Sensitive Columns | Inspect Customer data for names, emails, phones | | | | Hash Verification | Validate hash pattern and determinism, if applicable | SHA-256 or equivalent confirmed | | **Status & Transaction Flags** | Status Field Present | Check for Completed, Voided, Returned flags | Status column exists and consistent | | | Returns Handling | Identify how returns are logged (negative, linked, or separate) | Return logic documented | | **Financial Metrics** | Margin % | Verify cost or margin fields (margin\_pct, cost\_amount) | Present and logical (0–90%) | | | Mechanical Margin % | For service clients, check labor/service margin | Present and logical if applicable | | | Tax & Discount Logic | Verify tax\_amount, discount\_amount formulas | Totals reconcile to invoice header | | **Data Relationships** | Foreign Keys Valid | Confirm joins: SalesDetail → SalesHeader → Customer/Store | ≥99.9% join coverage | | | Null Keys | Identify orphaned or missing FK values | Minimal or no nulls in key fields | | **Data Freshness** | Latest Transaction Date | Check most recent transaction\_datetime | Data ≤ 24h old | | | Update Frequency | Confirm daily/hourly ingestion feasible | Agreed frequency documented | | **Schema & Field Standards** | Data Types Consistent | Verify type alignment (e.g., decimal vs int) | Matches expected schema | | | Naming Conventions | Confirm lowercase + underscores naming pattern | Consistent and documented | | **Discounts & Promotions** | Discount Source | Identify where discounts are stored (header, detail, promo table) | Confirm structure and logic | | | Promo Codes | Check for promo\_id or promo\_code linkage | Fields present and valid | | **Store Metadata** | Store Info Complete | Confirm store\_id, store\_name, region, timezone | All stores covered with metadata | | | Region Consistency | Verify region and timezone alignment | Stores grouped correctly | | **Completeness & Quality** | Null / Blank Checks | Identify columns with excessive nulls | <5% null rate on required fields | | | Duplicate Keys | Detect duplicates in transaction\_id, line\_id, customer\_id | No duplicates in key fields | | **Documentation** | Data Dictionary Provided | Confirm client provided schema reference | Available and up to date | | | Business Rules Confirmed | Document how returns, voids, discounts work | Notes captured for modeling | *** **Need Help?**\ Reach out to your Bonsai Customer Engineer for a quick data readiness review. # Google Cloud Storage (GCS) File Upload Guide This guide defines the requirements for uploading files to our Google Cloud Storage (GCS) bucket to ensure reliable, automated processing as an alternative to using Bonsai's Connect Cards. #### **Supported File Types** * Preferred: .csv, .csv.gz, .parquet * Not supported: Excel files (.xlsx, .xls), files with formulas, unapproved JSON formats * Encoding: UTF-8 only #### **File Naming Convention** Required format ``` __. ``` Example ``` shopify_orders_20250301.csv ``` #### **Rules** * Lowercase only * Use underscores (\_), no spaces or special characters * Include a date for time-based data * Do not overwrite files unless explicitly instructed #### **File Structure** * Single header row required * One record per row * No totals, summaries, or footers * One dataset per file only #### **Schema & Columns** * Column names must be lowercase snake\_case * Column order must remain consistent * Data types must not change over time * Use blank or NULL values for missing data * Do not use placeholders like N/A, unknown, or 0 unless required #### **Dates & Timestamps** * Use ISO-8601 formats * Date: YYYY-MM-DD * Timestamp: YYYY-MM-DDTHH:MM:SS * Use UTC for all timestamps #### **Schema Changes** Please notify us before: * Renaming or removing columns * Changing data types * Changing file structure Allowed with approval: adding new nullable columns\ Breaking changes may require versioned files or folders. #### **Delivery Expectations** * Upload files on the agreed cadence (daily, weekly, ad hoc) * Files must be complete at upload time * Late or corrected data must follow the agreed backfill process # ETL Overview for Analytics Data ## Overview Bonsai ingests raw, event-level first-party analytics data — including GA4, Adobe Analytics, Heap, or custom 1P tracking implementations — and standardizes it into a unified customer journey dataset for marketing attribution, incrementality modeling, and campaign analytics. ## Analytics Platforms ### GA4 BigQuery Export The GA4 BigQuery Export provides raw event-level analytics data (sessions, events, traffic source metadata, device data, and commerce events) in BigQuery. Bonsai uses this export as an upstream source of truth for web and app behavioral touchpoints. **API documentation:** This connector leverages the [Google Analytics BigQuery Export Integration](https://support.google.com/analytics/answer/7029846?hl=en) ### Adobe Analytics Data Feed The Adobe Analytics Data Feed provides raw, hit-level event data (page views, custom events, eVars, props, traffic source metadata, device data, and commerce events) delivered via cloud storage or API extraction. Bonsai uses this raw export as an upstream source of truth for web and app behavioral touchpoints. **API documentation:** This connector leverages the [Adobe Analytics Data Feed and Reporting APIs](https://experienceleague.adobe.com/docs/analytics/export/analytics-data-feed/data-feed-overview.html) ### Heap Data Export Heap provides raw, event-level behavioral data (user interactions, page views, custom events, properties, traffic attribution metadata, and user identifiers) via warehouse sync or API export. Bonsai ingests this event-level export as a first-party behavioral source to construct standardized customer journey paths. **API documentation:** This connector leverages the [Heap Warehouse Sync and API Export](https://developers.heap.io/docs) ### Custom First-Party Tracking (1P Event Stream) Custom first-party tracking implementations (including proprietary event pipelines, server-side tracking, or custom 1P cookie frameworks) provide raw event-level behavioral data such as sessions, user identifiers, traffic source parameters, and commerce events. Bonsai ingests this structured event stream via secure file transfer or warehouse connection and transforms it into a standardized customer journey dataset. **API documentation:** Integration specifications are provided directly by the client. Data must meet Bonsai’s event schema requirements (event timestamp, user identifier, session identifier, event name, traffic source metadata). ## Transformation (ETL) Summary Bonsai runs a daily ETL pipeline that normalizes any analytics event data and enriches it with campaign, geographic, device, and conversion attributes. The output is a unified touchpoint dimension table that represents each event in the customer journey. Key transformation steps include: * Extract event-level records from analytics export tables. * Normalize identifiers (cookie/device ID, user ID, session ID) to support journey stitching. * Flatten and map traffic source fields into standardized source/medium/campaign fields. * Derive geographic and device dimensions from analytics event metadata. * Join commerce-related events to transaction\_id and item details when available. * Parse / extract click identifiers (gclid, dclid, fbclid, etc.) for paid attribution. * Generate derived date dimensions (day of week, week, month, year). * Apply client-defined touchpoint dimensions (dim1–dim10) and matching flags. * Write consolidated records into the Bonsai touchpoint table. ### Output Table #### Table: event\_touchpoint\_dim\_table This table consolidates customer journey data, linking key interactions to subsequent events such as orders. It serves as a single source of truth for understanding how different marketing touchpoints contribute to customer purchase. **Table metadata:** * Description: A comprehensive table that records a customer's journey, including touchpoints, campaign data, and attributed metrics, to facilitate marketing effectiveness analysis. * Update Frequency: Updated daily via an ETL process that aggregates data from various source systems. * Partitioning: This table is not currently partitioned. * Example Use Case: Analyze the custom attributed metrics against each campaign in any DMA. **Field Definitions:** | Field Name | Type | Description | | -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | client\_number | INTEGER | An internal client identifier. | | key | STRING | A primary key for the specific interaction or event within the journey. | | cookie\_id | STRING | Unique identifier assigned to a browser or device via cookie tracking. | | user\_id | STRING | Unique identifier associated with a known or logged-in user. | | event\_name | STRING | Name of the event captured (e.g., page\_view, purchase, click). | | journey\_time | INTEGER | The timestamp of the event or interaction within the journey. | | session\_id | INTEGER | Unique identifier for the user’s session, grouping related events together. | | continent | STRING | Geographical dimension related to the user's location. Used for broad geographic segmentation. | | sub\_continent | STRING | Geographical dimensions related to the user's location. Used for more granular geographic grouping. | | country | STRING | Geographical dimensions related to the user's location. Used for national-level data segmentation and filtering. | | region | STRING | Geographical dimensions related to the user's location. Can represent a state, province, or a collection of postal codes. Used for more specific location-based targeting. | | metro | STRING | Geographical dimensions related to the user's location. A metropolitan area, which includes a city and its surrounding suburbs. Used for local-level targeting and analysis. | | campaign | STRING | An organized effort to promote a product or service. Used to group and track performance data. | | source | STRING | The origin of a user or event. Used to identify where traffic or conversions came from. | | medium | STRING | The category of the source. Used to classify the type of channel that drove traffic (e.g., CPC, organic, email). | | operating\_system | STRING | User operating system | | operating\_system\_version | STRING | User operating system version. | | deviceCategory | STRING | Category of the device used (e.g., desktop, mobile, tablet). | | mobile\_brand\_name | STRING | Brand name of the mobile device. | | mobile\_model\_name | STRING | Model name of the mobile device. | | mobile\_marketing\_name | STRING | Marketing name of the mobile device. | | dayofweek | INTEGER | Numeric representation of the day of the week (1–7). | | week | INTEGER | Week number of the year. | | month | INTEGER | Month number of the year. | | year | INTEGER | Four-digit year value. | | date | DATE | Date of the event (YYYY-MM-DD). | | transaction\_id | STRING | Unique identifier for the transaction or purchase event. | | item\_category | STRING | Primary category of the item purchased or viewed. | | item\_category2 | STRING | Secondary category of the item. | | item\_category3 | STRING | Tertiary category of the item. | | item\_category4 | STRING | Fourth-level item category. | | item\_category5 | STRING | Fifth-level item category. | | product\_sku | STRING | Product SKU or stock keeping unit identifier. | | netsalesquantity | INTEGER | Quantity of items sold (net of returns). | | product\_brand | STRING | Brand name of the product. | | product\_name | STRING | Name or title of the product. | | product\_category | STRING | Overall category or type of the product. | | net\_sales\_amount\_usd | FLOAT | Total net sales amount in U.S. dollars. | | referrer | STRING | Referring URL or source that directed the user. | | gclid | STRING | A Google click ID used by Google Ads. | | dclid | STRING | A click ID used by DoubleClick. | | fbclid | STRING | A click ID used by Facebook and Instagram Ads. | | gbraid | STRING | A Google click ID used for iOS campaigns, specifically for app-to-web measurement on browsers that do not support third-party cookies. (Google Brand Referrer ID) | | ko\_click\_id | STRING | A click ID used by TikTok for its advertising campaigns | | li\_fat\_id | STRING | A click ID used by LinkedIn. | | twclid | STRING | A click ID used by Twitter (X) for its advertising platform. | | ttclid | STRING | TikTok click identifier used for ad attribution tracking. | | wbraid | STRING | A Google click ID for iOS campaigns, used for web-to-app measurement. | | dim1-10 | STRING | Client-defined custom 1st-party touch point dimensions | | cookie\_match\_dim1 | STRING | | | flag1-10 | STRING | | | cookie\_match\_flag | INTEGER | | | key\_interaction\_flag | INTEGER | A flag indicating if the event was a key interaction. | | key\_interaction\_weight | INTEGER | A value representing the weight or importance of a key interaction. | # Predictive Buying Algorithms {% embed url="" %} # How to Set Up Conversions for Bonsai's Buying Algorithms This guide walks through how to configure conversions or pixel and campaign structure to enable Bonsai’s buying algorithms using a controlled test vs. control framework. The goal is to: * Introduce a Bonsai-optimized purchase conversion or pixel * Isolate algorithm performance in test markets * Prevent incremental spend during the testing period *** {% stepper %} {% step %} **Grant Access to Bonsai** Add your Bonsai Activation Lead to your Google Ads account with standard or admin permissions. {% hint style="info" %} This allows Bonsai to create and configure the required conversion actions. {% endhint %} {% endstep %} {% step %} **Bonsai Creates the PCV Conversion** Bonsai will: * Create a new conversion action (example: `bds_pcv_conversion`) * Configure it as a Purchase conversion and set it as a Secondary conversion This ensures: * Your existing optimization remains unchanged * Bonsai can measure and optimize independently during testing {% endstep %} {% step %} **Duplicate Existing Campaigns for the Test** Duplicate the campaigns that will participate in the test based on the test design doc created by your Bonsai Activation Lead. {% hint style="success" %} Use naming convention "{existing\_campaign\_name} - Bonsai Trial” for duplicated campaigns. {% endhint %} {% endstep %} {% step %} **Pause Test Campaigns (Temporarily)** After duplication: * Leave the new Bonsai Trial campaigns paused * Final activation happens after market targeting is complete {% endstep %} {% step %} **Assign Test Markets (DMAs) to Trial Campaigns** Apply geo-targeting so only the selected test DMAs based on the test design doc created by your Activation Lead receive spend from the Bonsai Trial campaigns. {% endstep %} {% step %} **Exclude Test Markets from Control Campaigns** In your original (control) campaigns: * Add the same DMAs as negative targets This ensures: * No overlap between test and control * Clean incrementality measurement {% endstep %} {% step %} **Set Budgets on Test Campaigns** Activate Bonsai Trial campaigns using the recommended daily budgets based on the test design doc created by your Activation Lead. Guidelines: * Bonsai uses historical market spend as the baseline {% endstep %} {% step %} **Reduce Control Campaign Budgets** {% hint style="success" %} **To prevent incremental spend:** Reduce control campaign daily budgets by the exact amount allocated to test campaigns. **This keeps:** Total spend = flat during the test period. {% endhint %} {% endstep %} {% endstepper %} ## Launch Checklist Before going live: * [x] Bonsai PCV conversion created & set as secondary * [x] Campaigns duplicated with correct naming * [x] Test DMAs applied to trial campaigns * [x] Test DMAs excluded from control campaigns * [x] Budgets shifted ## What Happens Next Once live, Bonsai will: 1. Optimize bidding using the Bonsai's buying algorithm 2. Measure performance in test vs. control markets 3. Quantify true incremental lift and efficiency gains *** ## Best Practices * Avoid changing creatives or targeting mid-test * Let tests run a minimum of 4 weeks (volume dependent) # Audience Segmentation {% embed url="" %} # Troubleshoot # Release Notes

What's new and improved.

Click Here for Platform Updates

Keep up with Bonsai's latest features, improvements, and bug fixes. We also share the occasional "Did you know?"

# System Status {% hint style="success" %} **We're Fully Operational** We're not aware of any issues affecting our systems. {% endhint %} {% embed url="" %} # Trust & Compliance Learn about our security practices, compliance certifications, and data protection standards.

Visit Bonsai's Trust Center

:shield: Security & Compliance at Bonsai


Our Trust Center provides transparency into how we protect customer data, maintain compliance, and manage risk.

What you’ll find:

  • SOC 2 compliance reports
  • Security policies & controls
  • Risk and vendor management
  • Continuous monitoring

:badge: Compliance