Connecting your data
Everything The AI CMO knows about your customers flows through the Data page – sources on the left of the journey, your event vocabulary in the middle, and the warehouse it all lands in. This manual covers each door in, and how to confirm your data arrived.
The Data page
Data in the sidebar opens these tabs – the first two are the two directions your data can move:
- Push – everything you send us: CSV imports, the Website SDK at a glance, the address your own systems post to, the keys they use, and recurring file feeds.
- Pull – everything we fetch for you on a schedule: Shopify, Stripe, ad platforms, and tables in your own database, each with a freshness status.
- Events – the vocabulary of custom events your site and systems can send (see below).
- Catalog – the products, offers and other items your events refer to.
- Activity – the record of everything that has moved, in either direction (see below).
- Warehouse – totals, every event type as it streams in, and the meter showing how much of your plan's included volume you've used.
If you want to explore the platform before wiring anything real, Load demo data on the Push tab fills the account with a sample business you can safely play with and remove later.
The fastest start: one CSV
The Add your data (CSV) card accepts one file and works out what it is:
- Purchase history – a customer, a date, an amount per row. The moment it imports, the Overview tab has your revenue numbers.
- Ad performance – a date, a platform, a spend per row. Platform names are standardized automatically (GADS, PPC, and Google Ads all become Google Ads), and ROAS and CAC go live on Overview.
- A contact list – any file with an email column becomes an audience segment in Customer Intelligence → Audiences. A consent column in it (see Marketing consent of the people your data brings in below) sets each new person's e-mail marketing consent; the confirmation step says whether one was found.
- A combined file – one file with a
record_typecolumn can carry purchases and ad rows together. There's a sample CSV to download on the card.
You map the columns in a quick confirmation step, extra columns are always kept as customer attributes, and files up to 100,000 rows are accepted. Re-importing the same file is safe – the warehouse never double-counts an order it has already seen. Every import appears in the Uploads list, where it can also be deleted.
How numbers are read
Every way in – a file, a scheduled file, a database or API pull, the
webhook – reads numbers the same way, whatever the format: 1 000,
1,000.00, 1.000,00, 1 234,50 Kč, (100) and −100 are all read
as the numbers they are.
- Each column decides for itself. How a column writes its numbers
is read from all its values:
12,50in a column tells us its comma is the decimal mark, so1.250in the same column is one thousand two hundred and fifty. Only when a column's values cannot tell (it holds nothing but values like1.250) does your brand's own way of writing decide: its currency, its website's country, its language. The webhook and an API pull read JSON, where a lone dot is a decimal point: there1.250is 1.25 (unless that connection has written the comma as its decimal mark before: the webhook, below), and next to12,50in the same field of one request or page it is stored as written and counted as unread. - A currency written with an amount counts.
1 234,50 Kčis 1,234.50 Czech koruna: when the row names no currency of its own, that is its currency; when it names another one (an amount in Kč on a row in EUR), the amount is not counted, kept as written and said. - A number that cannot be read is never counted as 0. It is stored with no number, kept exactly as written, and the import says how many there were and in which column (a scheduled file's delivery history says the same). The rest of the file is imported as usual, and an event is never turned away because of its amount.
- What the data says wins. Nothing is guessed. If a column is written two ways, or a value could be read two ways and nothing in the file or your brand settles it, it is left unread and said, never read one way on a hunch.
- A field is read one way, decided once. The first time a field holds
a value whose reading matters (a value like
1.250), the platform decides how that field writes its numbers: from its values, a currency written with them, then your brand's language and country. From then on the field is always read that way. New data does not change it, and neither does a later change of your brand's language, country, currency or website. Numbers already stored are never read again or rewritten. - There is nothing to set. How numbers are read is the platform's standard way for every brand: no one, owner or admin included, chooses or changes it. You hear about numbers only when something is wrong: the import says which values could not be read, and Data → Push lists the fields that hold values that can't be read as numbers.
Connecting your apps
Integrations in the sidebar connects The AI CMO to the tools you already use. The page is organized by job:
- Publish – Journeys and chat post here for you: Facebook, Instagram, Reddit, LinkedIn, X, TikTok, YouTube, Snapchat, WordPress. Facebook, Instagram, Reddit, TikTok, YouTube and Snapchat connect through our publishing partner's approved apps: you authorize, pick the account, and publishing works right away – nothing to review or approve on your side. A Facebook connection is one Page: the flow asks which Page, and a second Page is a second connection. Instagram connects the Business or Creator account directly, no Page needed; the composer's Instagram panel adds a Story instead of a feed post, a Reel cover, up to three collaborators, a first comment posted right after publishing, the AI-generated label and comments on or off. LinkedIn connects the profile or the organization you choose. TikTok publishes from the composer, where you choose who can see the video, allow comments, duet and stitch, and confirm the preview – TikTok requires the creator to make those choices, so chat will send you there. Reddit takes a subreddit and a title in the composer, and the moment you name the community the panel reads its rules, whether it requires a flair (and which), and which kinds of post it takes, so a post is refused on our side with the fix named rather than removed by a moderator later. YouTube takes one video per post with a title, who can see it and tags – the text is the description, and a vertical video of three minutes or less becomes a Short; Google asks which account or Brand Account to connect. Snapchat is coming: it connects a Public Profile and posts a Story (24 hours), a Saved Story (the text is its title) or a Spotlight (the text is its description) – one vertical photo or video each – and opens the day our publishing partner releases it.
- Measure – spend and results land in your analytics automatically: Google Analytics, Google Ads (from the account you choose for the brand – see Google Ads: the brand's account and its conversions below), Amazon Ads. Meta Ads, TikTok Ads and LinkedIn Ads connect through the same partner – Meta as a Business Login on your business portfolio – and their spend by campaign syncs nightly into your warehouse, the same funnel your ads CSV feeds. Post performance for everything published this way syncs daily into What's Working. Google Search Console (read only) shows what your site earns in Google – clicks, impressions and average position for each search and page – in Keyword Research, the SEO Meta Generator, Link Building, chat and your SEO Strategist's work. Google grants every property on the account you sign in with; the one that matches the brand's website is used, and the card names it.
- Reach & alert – talk to your customers and your team: email sending, HubSpot, Slack.
- App stores – optional keys for App Store Optimization and the Helpdesk: App Store Connect, Google Play and Apple Ads. App Store Optimization reads the public stores without them; see The app store keys below.
- Commerce – your sales land in your warehouse on their own: Shopify orders and products, Stripe payments. Each card has a Sync now button, so your numbers start the moment you connect; the nightly sync keeps them current and finishes any large backfill. Each new buyer or payer also becomes a contact of the brand – never someone erased on request – with the store's own e-mail marketing consent (see Marketing consent of the people your data brings in below). A Stripe restricted key belongs to the one Stripe account it was created in, so for each brand create the key inside that brand's Stripe account and connect it under that brand; the card names the account it reads.
Connecting is one click: Connect opens a secure sign-in window for that platform, you approve, and you're done. A connection belongs to one brand: if your account runs several, you are asked which brand the account is for before the sign-in window opens, with your current brand preselected. Integrations shows the connections of the brand you are working in; switch brands in the header to see another's. Connected to the wrong brand? Move to… on the connected card re-files it, and its data lands under the new brand from then on. Once an ad platform is connected, its spend syncs into your analytics on its own – no import needed. Google Ads is the one exception: its spend syncs once the brand's account is chosen (below).
Google Ads: the brand's account and its conversions
- One account per brand. Under Connections → Google Ads → Account, choose the Google Ads account that runs this brand's ads. Its ad spend syncs from that account only – never from every account your Google login reaches – and nothing syncs until one is chosen. If your login reached exactly one account, it may already be recorded; the dialog says so until you confirm it. Don't use an account stops using it for the brand.
- Conversions are defined here. Under Data → Events → Conversions, pick the events that count as a win for the brand – a registration, a payment, a lead – from the events it already collects, and mark one as the main conversion.
- Sending them to Google Ads is off until you turn it on. In the same dialog, Send conversions to Google Ads creates one action per conversion, named "AI CMO – <its name>", as a secondary action: it is reported under All conversions and is not used for bidding unless you add it to a goal in Google Ads. Each conversion is sent with the person's own Google ad click on your site, and the dialog says how many were sent and why the others were not.
- What Google is told about consent. Each click is sent as consented. Where your cookie banner passes the visitor's choice to our tracker, that choice is what counts: a visitor who refused marketing has no click kept, and one who refuses later is not sent. Where your site has no cookie banner, or its banner is not connected to our tracker, the tracker cannot see the visitor's choice and allows marketing by default – so those clicks are sent as consented too: that is your site's tracker setting, and it is what Google is told. If visitors who refuse cookies must not be sent, connect your banner to the tracker – see Consent and privacy.
- Which campaign each Google ad click came from. A Google ad click
reaches your site with Google's click ID and, unless your ads are
tagged, nothing that names the campaign. With the brand's account
chosen, Google is asked each night which campaign every click belonged
to. Without that access – or for what it could not read – upload
Google's click report in the same dialog, under Google's click
report – which campaign each click came from: a .csv or
tab-separated file of up to 4 MB with one line per click. Google Ads
has no ready-made report with one line per click, so How to download
it from Google Ads gives you a short Google Ads script to paste:
in the brand's own Google Ads account (not a manager account) choose
Tools, then Bulk actions, then Scripts; press +, choose
New script, paste the script over what is there, press
Authorize and then Run. It reads the last 90 days of clicks,
changes nothing in the account, and saves the file (in parts for a
large account) to your Google Drive; download it and upload it as it
comes. A file made another way is read too when its columns are named
in English: "Google Click ID", and "Campaign" or "Campaign ID"; "Ad
group", "Keyword", "Match type" and "Day" are read when they are
there. (For developers: a file with Google's own field names as its
columns –
click_view.gclid,campaign.id,campaign.name… – is read as well.) Each click on your site then carries its campaign, ad group and keyword, and new customers are credited to that campaign. The dialog says how many clicks were matched, how many Google's own answer had already named (those keep it), how many are not among your site's visits of the last 90 days, and which lines were refused and why. The file is matched only to the brand's own visits and is not kept.
You can also connect from chat. When something you ask for needs a platform that isn't connected yet, chat holds that step, says so in a small card and offers Connect, which runs this same sign-in for the brand the chat is working for. The step waits, uncharged, until you've connected and said yes. (An audit of an ad account only finds out when it reaches the account; its credits are then returned.)
The app store keys
The three cards under App stores take a key instead of a sign-in window. Connect asks which brand the key is for when you run several, then opens a dialog with the steps. The key is checked live with the store before it is saved, and it is stored encrypted. Manage takes a new key; when a store stops accepting one, the card says so, with Replace the key. Nothing changes in either store unless someone on your team sends it – a listing from App Store Optimization, a reply from the Helpdesk.
App Store Connect takes a Team key with Admin access, made in App Store Connect under Users and Access › Integrations › App Store Connect API › Team Keys (an Individual key does not work; only an Admin key can request the App Store analytics reports). Enter its Issuer ID and Key ID and choose the .p8 file Apple offers once. When the key works, pick which of the account's apps belong to the brand. It adds your real listing – the private keyword field too – your App Store reviews in the Helpdesk, and App Store analytics. Nothing is submitted for review.
Google Play takes a Google Cloud service account's JSON key. Turn on the Google Play Android Developer API in its project, then in Play Console invite the service account's e-mail under Users and permissions with View app information and download bulk reports, Reply to reviews and Manage store presence for the app – Google shows a listing to a key only through a draft edit, which is deleted straight after reading. Name the app's package, like com.example.app (several apps: separate them with commas). Also read the monthly store reports adds the reports bucket (gs://pubsite_prod_…, from Download reports › Statistics › Copy Cloud Storage URI): the store listing visitors, installs and the searches that brought visitors. Google opens the bucket only to a user whose View app information permission covers the whole account. Play Console can take a few hours to apply a new user's permissions.
Apple Ads signs in with a key pair made for the brand: Create the key, then have an Apple Ads account admin invite an API user (API Account Read Only is the narrowest role). Signed in as that user, paste the public key under Account Settings › API, and enter the client ID, team ID and key ID Apple Ads shows there. It adds Apple's own search popularity, 0–100, for your searches. Read only – no campaign is created or changed.
Platform feeds
There are two ways data arrives, and they live in different places because only one of them holds passwords to your other accounts.
- You send it to us – your own systems, or a file. No connector, no setup: see Sending data from your own systems below.
- We fetch it for you – Shopify, Stripe, Google Ads, Meta, or a table in your own database. These need access to those accounts, so they are set up by your workspace admins in the admin portal. The Pull tab shows each one and how fresh it is; everyone can see the status.
We pull straight from your database
If the data you want in your warehouse already sits in a PostgreSQL or MySQL database – an orders table, a customer list, a product catalogue – you can skip exports entirely. Give us read-only access to that one table and we collect new rows on a schedule you choose.
Your admins set it up in the admin portal under Data Sources → Add Data Source → We pull from your database:
- Create a read-only database user. We only ever read – a user that can do nothing else is the right shape for this.
- Enter the connection – host, port, database, username, password. The password is stored encrypted, is never shown again, and never appears in any response. Your database must be reachable from the internet; if it sits behind a firewall, your team allowlists our address.
- Say what to pull – the table, and a column that only ever grows
(an id, or an
updated_attimestamp). Each collection continues from where the last one stopped instead of re-reading everything. Leave the column blank and we re-read the whole table each run. - Say what the rows are – events (orders, transactions), your customer roster, or a catalogue. Same choice as a CSV import, and the same rules apply afterwards.
- Press Test connection. It proves the credentials work and the table is readable before anything is saved, and shows you the table's columns.
From then on it runs on the schedule from the Settings tab – hourly, daily or weekly – and Sync now collects on the spot. A row we have seen before replaces itself rather than double-counting, so neither re-runs nor overlapping collections can inflate your numbers. Every run is recorded on Data → Activity, and the source's freshness shows on the Pull tab like every other feed.
Blocks from your database. On a customer table, a column can be mapped to Exclude – all messages or Exclude – marketing. Your database is then the truth about who is blocked, in both directions, as the Data push API is:
- Someone whose row reads as set goes on the Blacklist, on that source's own list for the table, by your key for them, their e-mail and their phone, before their row lands. A value that cannot be read plainly as not set blocks too.
- Someone whose row is read in a run with every mapped exclusion column
plainly not set (
0,false,no, empty) is let back in from that source's lists, and only from them. - Nobody is let back in because a row is missing from a read, a read was short or failed, or a column is no longer mapped. A column removed from a tier keeps everyone it put on the Blacklist: once a tier is mapped to fewer columns than before, everyone already on its list stays until removed by hand, and people added after that are judged as usual.
- The brake judges one whole read of a view: a large view read over several runs counts as one read. Once more than 25 people would be let back in from a list during that read, and they are more than 10% of the people on it, nobody more is let back in until the next read, and the run says so: if it is right, remove them on the Blacklist page. A view read by its new rows only is judged run by run. Someone taken off the marketing list while their row still sets Exclude – all messages stays blocked from everything, so the brake never counts them.
- Someone let back in whose number was already sent to the brand's SMS gateway list stays blocked for marketing texts and WhatsApp until removed by hand at the gateway, or from that gateway's list on the Blacklist page.
- A block your team added, the person's own unsubscribe, STOP or complaint, and what the data push or a file added are never lifted by a pull, and nothing about a person erased on request is let back in.
Snowflake is on the source list and our team makes the connection – add it and the config page tells you what we need. Other warehouses are arranged with us; ask and we will tell you what is involved.
We pull from your API
Many systems have no export and no webhooks, but do have an API – a CRM, a booking engine, a loyalty platform, an SMS gateway's list of people who replied STOP. Give us the endpoint and we fetch it on a schedule, the same way we pull from a database.
Your admins set it up in the admin portal under Data Sources → Add Data Source → We pull from your API:
- The endpoint. The URL, GET or POST, and how we sign in – a bearer token, a key in a header or in the query string, or basic auth. The key is stored encrypted, never shown again and never appears in any response. Extra headers go in a small list of their own.
- How we read the answer. Where the records sit in the JSON (for
example
data.items, or nothing when the response is the list itself), and how to ask for the next page – a page number, an offset, a cursor the response hands back, or a next-page link. If the API can return only what changed after a time, name that parameter and each run asks just for what is new. - What the records are. Events, your customer roster, a catalog – the same choices as a file – or an opt-out list: say which field holds the person (a phone number, an e-mail or your own customer id) and what the list means: marketing opt-out, block everything, or a watch list. Opt-outs land straight in that brand's suppression lists and every send checks them from then on.
- After import, optional. We call your API back for every record we now hold – typically to delete it at your end. That is how an SMS gateway's STOP list stops being permanent: the opt-out lives with us, where a person can be lifted again, instead of in a list nothing on your side ever clears. A record is only called back once it is safely on our side.
- Press Fetch a sample. It runs one request with what you typed, shows the first records and their fields, and fills the field pickers from your real data – before anything is saved.
From then on it runs on the schedule from the Settings tab, and Sync now fetches on the spot. Records we have seen before replace themselves, an opt-out already on the list is skipped, every run is on Data → Activity with the after-import count in its receipt, and the source's freshness shows on the Pull tab. Our requests only ever go to public addresses, so an API on a private network needs to be exposed to us first.
Sending data from your own systems
If your data lives in systems of your own (a customer database, an order system, a nightly export), Data → Push is where you wire them in. Nothing about them needs to be modern: anything that can make an HTTPS request, or produce a file, can feed The AI CMO.
Where it lands. One endpoint, whichever warehouse you are on. If you move to a dedicated cluster later, the same address follows you – there is nothing to re-point and no second URL to learn. The Push tab tells you which warehouse it is landing in right now.
The address. One address takes what happened (events), who your
customers are (customers, with their marketing consent and their blocks)
and what else you keep (records), up to 1,000 rows of each in one
request, and your plans and actuals (below). The brand is the key's own,
or the one the request names. Every event carries your own event_id
with its type in front (payment:90071): sending the same id again
replaces the event rather than adding a second, so retries, restarts
and re-sending yesterday's events never inflate your revenue. Every
field, answer and code is in the
Data push API reference.
Amounts. Send amount as a JSON number (1250.5) where you can.
Text is read too: "1250.50", "1 250,50", "1.250,50 Kč", "(100)".
An amount that cannot be read never turns the event away: the event is
stored with no amount, the amount is kept as you sent it, and the answer
says how many (amounts_unread, with a line in amounts_note).
Other fields. The event's other fields, at its top level and inside
its properties object, are read the same way when they hold text with a
digit, all of one request's events of a type together: "subtotal": "1 250,50" is stored as the number 1250.5, with what you sent kept beside
it. A JSON number stays a number, and a value that is an object or a list
is kept as you sent it, unread. A field becomes a number only when its
writing is certain. These stay exactly as you sent them:
- codes and words: values with a leading zero (
"00123"), codes like"A-1250", and any field whose name says it is an identifier (order_id,zip_code,app_version,telefon,variabilni_symbol) or starts with_; - phone numbers written with a
+("+420777123456") and postcodes written with a space ("110 00"); - a whole number sent as text, like
"777123456"or"4711", until values with a decimal mark show the field holds numbers: in the same request, earlier through this connection, or in your brand's readings of that field (from a file or a database pull, for example). Send counts as JSON numbers; - a field that this connection, or your brand's readings, show to hold codes;
- percentages (
"15 %"), dates and times.
In amounts and fields alike, a lone dot is a decimal point, the way JSON
writes numbers: "1.250" is stored as 1.25, with what you sent kept
beside it. Once this connection's earlier values have written the comma
as the decimal mark ("1.234,50"), an amount "1.250" is read as 1250
and a field "1.250" is stored as you sent it. A value that looks like a
number but cannot be told apart ("1.250" in a field where the same
request also writes "12,50", or "777 123 456") is stored as you sent
it, and the answer says how many (properties_unread, with a line in
properties_note). One request reads at most 100 fields of an event type,
the most frequent first, and no field whose name is longer than 64
characters: the rest are stored as you sent them, and the answer counts
them (properties_not_read, with a line in properties_note). If your brand's number settings cannot
be read at that moment, every field is stored as you sent it and
properties_note says so.
The keys. Issue one key per system, named after that system. A key is issued for the brand open on the page. Two things are worth knowing:
- A key is shown once, when you create it. We store only a fingerprint, so nobody – including us – can read it back to you. If it goes missing, revoke it and issue another.
- A key can only send data in. It cannot list or export your customers
and cannot erase a brand's data. It replaces the brand's event stored
under an
event_idit sends, updates the customers and records it sends, and adds or lifts entries on the brand's push block lists, which every key of the brand shares.
You can pin a key to the fixed IP addresses your systems send from, and give it an expiry date. Revoking one takes effect immediately and affects nothing else.
Daily files. The same key works for file uploads, so a scheduled job can post your nightly export directly instead of someone opening a browser to drag it in. A roster file makes a contact per row (by e-mail, else by its id) with the consent its columns state; a flag column in a file blocks nobody. Send blocks in the customers list of the Data push API, or connect the database they live in.
Sending plans
The same address and key take your budget, forecast and target
too, so a finance system can keep the Flash Report's plans current without
anyone retyping them. The brand is named as for every list: the key's
own brand, or ?client_id=<brand id> (the
Data push API has the whole rule). Send a
plans list – up to 2,000 rows in one request, on their own or beside
events:
{
"plans": [
{ "plan_type": "budget", "metric_key": "revenue", "year": 2027, "month": 1, "value": 120000 },
{ "plan_type": "forecast", "metric_key": "ad_spend", "year": 2027, "quarter": 1, "value": 36000 },
{ "plan_type": "target", "metric_key": "revenue", "year": 2027, "month": 1, "value": 40000, "channel": "paid_search" },
{ "plan_type": "forecast", "metric_key": "revenue", "year": 2027, "month": 2, "value": null }
]
}
plan_typeisbudget,forecastortarget.- The period is a
month(1–12), aquarter(1–4) or"period_type": "annual". A quarter or a year is spread evenly across its months for totals such as revenue and spend; a rate such as ROAS applies to each month as it is. - Sending the same plan, metric, period and channel again replaces the value.
"value": nullremoves it. metric_keyis one of your plan lines – the key shown when you click a line's name in Plans (gross_margin,net_revenue,fees_10_net…) – or one of the report's own measures:revenue,ad_spend,roas,purchases,aov,new_customers,total_customers,returning_customers,reactivated_customers,lapsed_customers,customer_continuity,revenue_per_customer,impressions,clicks,ctr,cpcandclick_to_purchase;costandconversionsare understood too.- A value can be negative – a line that plans a loss.
- An approved budget cannot change, so budget rows for a month an approved budget covers are refused – send new expectations as a forecast.
A value someone types in Plans on the Flash Report takes the place of a loaded one, and the plans editor shows the loaded values in grey.
Sending actuals
Some plan lines are your own accounting (gross margin, net revenue,
refunds, licence fees), and only your systems know the figure. Send it with the same address and key,
as an actuals list (up to 5,000 rows, on their own or beside events and
plans), and the Flash Report compares each line with its plan:
{
"actuals": [
{ "metric_key": "gross_margin", "date": "2026-11-03", "value": 104250.50 },
{ "metric_key": "net_revenue", "year": 2026, "month": 11, "value": 2114040 },
{ "metric_key": "gross_margin", "date": "2026-11-03", "value": null }
]
}
metric_keyis the line's key, as shown in Plans.- Send a
datefor one day, or ayearandmonthfor the whole month. Daily figures add up across the period and are compared with the plan up to the last day you sent; a whole month's figure is compared once the month has ended. Rates and levels (ARPU, active customers) are sent per month. - Sending the same line and day or month again replaces the figure;
"value": nullremoves it. A figure can be negative. - The report never works these lines out from other data. Until a figure arrives, the line reads not reported yet.
How we know it is the same person
It does not matter which door the data came through – a CSV, a file feed, the Website SDK, a webhook from your own systems, a pull from your database, a store sync. Every one of them registers the identifiers it carries against the same person.
- A person is keyed on the identifier you give us – your own customer ID or their e-mail, whichever your data carries; when both are known they are kept together as one person. The anonymous visitor ID the website gave them comes last, until they identify.
- Every other identifier we see for them is kept alongside it, so someone who arrives first as a cookie and later as an e-mail ends up as one record rather than two.
- Matching is exact. Nothing is guessed, and two people sharing a laptop stay two people.
- What you upload wins. A name, a status, a lifetime value or a "customer since" date from your roster survives the website traffic that arrives afterwards.
- Your own system's newest details win. When a database we pull from, or
the customers list of the Data push API, names a
person by your customer ID and carries an e-mail, a phone or a name that
differs from their contact's, the contact takes the new one. A new
e-mail or phone starts with the consent that same row states, else
"Not granted"; a no on that row reaches the old address too; and a
block on the person keeps applying. What the person did themselves
goes with them: if they unsubscribed or complained at the e-mail
address it replaces, the new address is unsubscribed too, and if they
sent STOP or complained at the phone it replaces, the new phone
carries the same opt-out, whatever the row states; a yes on that row,
or a later one, does not lift it. If that cannot be checked just now,
the contact keeps the e-mail or phone it held: the push API asks your
system to send the request again, and on a pull it is tried again the
next time the pull reads that row. A database we pull from does this
only from a row that names the person by your customer ID, in a view
with one row per person, and only with a valid value: an e-mail
address, a phone written in international form, a name with a letter
in it; a national phone number only fills an empty one. A placeholder
never replaces what a contact holds: an e-mail such as
n/a, a phone such as0, a name such as-,?orn/a. When the new e-mail is already held by another contact of the brand, nothing of that row changes, except that a no to marketing still applies when that other contact has no customer ID (a sign-up, a form, a file): on a pull it reaches the new address and the one the person's contact holds; through the push API, only what the person's contact holds. Merge the two contacts on the Customers page to update them. When the new e-mail belongs to another customer ID, the row is not applied: one e-mail is one person. A no to marketing on that row still applies to the e-mail and phone the contact of its own ID holds. A file fills only what a contact is missing. - E-mail and your own ID are treated as hard identifiers – each belongs to one customer within a brand. What to do when two records turn out to be one person is under Customer Intelligence.
If you can put an e-mail and your own ID in the same file, do. It is the single thing that makes every other door line up behind it.
Marketing consent of the people your data brings in
A person your data adds to your contacts starts as "Not granted" for marketing e-mail unless the data itself says they agreed – nothing is assumed. "Not granted" stops marketing e-mail only; service e-mail (a journey set to Service) still reaches them, and the person's record shows it under Compliance. It changes when consent is given – the Marketing e-mail box on their record, or your landing page's consent box.
- Files (the Add your data card, customer rosters, event files). A
consent column is read for each new person: a yes (
true,1,yes,ano,áno,subscribed,opted_in,confirmed_opt_in…) is recorded as their consent, with the file it came from; a no or a blank cell leaves them "Not granted". A column counts when its name says both that it is consent and which channel it is for, for exampleemail_consent,email_opt_in,email_marketing_consent,marketing_consent,accepts_marketing,newsletter_opt_in,Email Subscribed,Email Subscription Status, and Shopify's own customer export columns Accepts Email Marketing and Accepts SMS Marketing. A baresubscribed,opt_inornewslettercolumn is not read as consent (it often means a paid plan or a product setting), nor is a column holding a date, an IP address or an opt-in level. A column about ads – remarketing, retargeting, ad personalisation, Customer Match, for exampleemail_ads_consentorRemarketing consent– is never read as e-mail or SMS consent: consent to ads is not consent to be e-mailed or texted. It is kept like any other column. On an event file, the person's newest row that answers decides. A file without such a column adds everyone new as "Not granted". Phone numbers in the Add your data card follow the same rule for marketing texts: ansms_consent,sms_opt_inor Accepts SMS Marketing column is read for each new number, and without one a new number starts "Not granted" for marketing SMS and WhatsApp. - A database we pull from. On a customer table, a column mapped to
Email consent or SMS consent is read for each new person as a
file's is: a plain yes (
1,true,yes) is recorded as their consent, and anyone else new starts "Not granted". For people you already have, your database goes further than a file – see Consent in a database we pull from, below. - The data push API. A customers row's
email_consentandsms_consent(trueorfalse) are read for each new person: only a true is recorded as their consent, and anyone else new starts "Not granted", as does everyone an event or a record names. For people you already have, the push goes as far as a database does – see Consent sent by the data push API, below. - Scheduled file drops. The people in a drop become contacts when an audience finds them (below), so they start "Not granted"; a consent column in the drop file is not read for them.
- Shopify. A new buyer whom Shopify has as subscribed to your e-mail marketing is recorded with that consent; any other status – not subscribed, pending confirmation, unsubscribed – or none starts "Not granted".
- Stripe. A payment carries no marketing consent, so a new payer starts "Not granted".
- Audiences built from your data. A person an audience finds in your warehouse – identified on your website, logged in, signed up – who was not yet a contact is added as "Not granted". So is an e-mail an audience adds to a contact you had only by your customer ID.
Someone already in your contacts keeps what they had, with one exception
that matches your landing page's consent box: when the only thing
stopping marketing to them is this "Not granted" – they never
unsubscribed and never withdrew consent – a "yes" from your data (a file's
consent column, Shopify's subscribed status, the journey trigger API's
consent: { email: true }) is recorded and they become reachable. A "no"
in a later file, or a later Shopify status, is never read as a
withdrawal, and an unsubscribe is never overridden. Consent they gave you
before (on their consent history) is never undone when their record is
created again.
Consent in a database we pull from
A file is read once and may be out of date, so its "no" changes nobody. A database you connect keeps being read, so it is treated as the truth about the consent it holds, in both directions:
- A no withdraws. For someone already in your contacts, a mapped
Email consent or SMS consent column that now reads no (
0,false,no) withdraws marketing on that channel the next time their row is pulled. Marketing e-mail, or marketing texts and WhatsApp for the SMS column, stop for that person. Service messages still reach them, and the withdrawal is on their consent history with the other consent changes. - A later yes gives it back. When the same database says yes again, the person is reachable for marketing on that channel again. A yes from another way you load data – a file, a store, the data push, the journey trigger API – does not undo the withdrawal.
- The person's own no still stands. An unsubscribe, a STOP, a bounce or a complaint is never overridden: a yes in your database does not bring that person back.
- An empty cell changes nothing, and neither does a row for someone who is already not reachable on that channel.
- The row has to be read again. A pull that continues from a column
that only grows (an
updated_attimestamp) reads a row again when that column has moved, so a consent change should move it too. A pull with no such column reads the whole table every run.
Consent sent by the data push API
The customers list of the Data push API follows the same rule as a database: your system is the truth about the consent it sends, in both directions.
- A false withdraws. For someone already on the brand,
"email_consent": falsewithdraws marketing e-mail, and"sms_consent": falsemarketing texts and WhatsApp, for the address on the row and for the address their contact holds. - A later true gives it back, for what the push withdrew, whichever of the brand's keys sent the no. A no that came another way stands.
- The person's own no still stands. An unsubscribe, a STOP, a bounce, a complaint or a withdrawal your team made by hand is never overridden.
- Left out or
nullchanges nothing.
Files, scheduled drops, store syncs and the journey trigger API keep the rule above: a later no from them withdraws nothing. To stop marketing to people listed in a file, import them as a blacklist list set to Suppresses marketing – see Unsubscribes, opt-outs, and the blacklist.
What you can load
The warehouse takes more than orders. Anything you can export as a file has a home:
- Events – anything that happened. Purchases, payments, refunds, payouts,
renewals, sign-ups. Include an
event_typecolumn and we keep your words: a payout stays a payout, and is never counted as revenue. - Customers – who they are. A roster with status, tier, lifetime value, and any other column you send. Re-sending the whole file updates people rather than duplicating them, so a nightly full export is exactly the right shape. A roster file makes a contact per row (by e-mail, else by its id) with the consent its columns state; a flag column in a file blocks nobody. Send blocks through the Data push API, or connect the database they live in.
- Catalogues – what they buy or use. Products, services, offers. Each catalogue is named, and its items carry whatever attributes you have.
- Ad performance. A date, a platform, a spend per row.
- Plans – your budget, forecast and target. Sent by your systems (see Sending plans above) or uploaded as a spreadsheet in the Flash Report's Plans.
Extra columns are never dropped. Whatever you send that we don't recognise is kept as an attribute, appears in the Data Manager, and can be used for segmentation.
Telling us what counts as revenue
We do not assume it. A payment, a premium, a commission and a subscription are all somebody's revenue, and a payout carries an amount without being any of them – so guessing would mean quietly counting money you paid out as money you took in.
In Data → Events, each event type you send has a Money setting:
- Counts as revenue – amounts on this event roll up into your revenue figures and ROAS.
- Paid out – money going the other way. Never counted as revenue.
- Not money – the event has an amount that is not a payment at all.
Anything left undeclared contributes nothing to revenue. That is deliberate: a missing number you can see beats a wrong number you cannot.
Subscriptions and MRR
If you sell subscriptions, give each payment event a detail that says how
often it bills – for example billing_period with monthly or annual. The
name is yours to choose; values such as quarterly, weekly, year or
P1M work too. With it, your AI team – and chat, on plans with the data
warehouse – calculates MRR, ARR and how MRR moved (new, expansion,
reactivation, contraction and churned), paying customers and logo churn, by
week, month or quarter.
- A plan detail such as
planortiersplits MRR by plan. - An event whose name says cancel or churn, such as
subscription_cancelled, marks a cancellation: the customer leaves MRR when the period they paid for ends. - A renewal up to seven days late is not counted as a churn and a comeback.
- An annual payment counts as a twelfth of its amount each month.
Without an interval detail, MRR is not calculated: you get revenue, orders and paying customers instead, and the answer says why.
Sending the same file every day
Yes, and it does the right thing in each case – but the safest shape is worth knowing.
Best: include an id column. A transaction_id, booking_id or order_id
makes each row permanently identifiable. Send a new day's transactions and they
add; re-send a corrected version of yesterday's and each row replaces itself.
Nothing double-counts, and correcting a single wrong amount is just re-sending
the file with it fixed.
Without an id column, we identify a row by its contents. That still behaves correctly: a genuinely new day's rows are new, an accidental second send of the same file changes nothing, and re-sending a rolling window (say the last seven days, every night) updates those days rather than duplicating them – even if the rows come back in a different order. The one thing it cannot tell apart is two byte-identical rows in the same file; those are kept as two events, which is usually what you want for a repeated payment or a repeated purchase.
Customer and catalogue files are a snapshot, and that is fine. A full nightly roster updates the people in it and holds their current state. Segment movement does not depend on it: lifecycle stages are computed from your event history, so how customers move between segments is fully reconstructible from the events you send – no snapshots required, and re-sending a roster never disturbs it. What a roster does not give you is a history of your OWN attributes: if you want "customer moved from silver to gold" to be visible as an event, send it as one.
Ad performance is keyed by day, platform and campaign. Re-sending a day replaces that day.
If the wrong data arrives
Nothing is frozen. Three ways to correct it, and each correction is recorded alongside the original load:
- Re-send the file. A repeat delivery replaces that load rather than adding to it, so fixing a bad export is a matter of sending the good one. For customer and catalogue files this updates the records in place – a full nightly export is exactly the right shape.
- Delete a single load. Every upload is listed under Data → Push with its row count and time; removing one takes its rows with it.
- Clear a profile. Removes everything loaded for that business profile.
The activity log itself can never be edited or removed, including by an owner – it is the record of what happened, not the data.
Files that arrive on a schedule
A one-off CSV drops straight on the Push tab. An export that repeats – your nightly customer file, a weekly finance extract – should be a feed, further down the same tab.
Give it a name and say how often it should arrive. From then on:
- It remembers your columns. You map them once, on the first file. Every delivery after that is loaded the same way, so nobody re-maps the same export every night.
- It tells you when a file doesn't turn up. This is the real reason to use a feed. A nightly export that quietly dies is wrong numbers for a week before anyone notices; a feed raises it the morning it happens.
- It works by hand or by machine. Drop a file on the feed here, or have a scheduled job send it with an ingestion key – same feed either way, and the history shows which was which.
If you'd rather not commit to a schedule, leave it on Detect the rhythm. We watch the first few deliveries, work out the pattern, and offer it back to you to confirm – we never invent a schedule you didn't agree to. Pausing a feed stops the overdue alerts without deleting anything.
Activity. Underneath is the record: every file loaded, every batch received, every mapping changed, every deletion – who or what did it, from which address, how many rows moved, and whether it worked. Failures are recorded too, so "the nightly load stopped three days ago" is a question you can answer. Nothing can edit or remove an entry, including an account owner.
Giving your data team their own access
If the people who wire up your systems are not the people who run your marketing, invite them as a Data engineer.
That seat sees the Data page – sources, connection, keys, activity, the event catalog and the warehouse – and nothing else. No campaigns, no journeys, no audiences, no billing. They can load data, map it, correct a bad file, and issue their own keys, without ever seeing the marketing side of the account.
To be precise about one thing, because it matters for regulated businesses: they can see the data they load, and that includes customer identifiers, because inspecting it is the job. What they cannot do is act on it – no campaign, no journey, no export to an ad platform, no message to anyone.
Two things they deliberately cannot do: erase all data for a business profile, and see anything outside the Data page. Purging a profile stays with owners and admins.
Invite them from admin.theaicmo.com → Team, choosing Data engineer as the role. It takes a seat like any other member.
Your website
The Website SDK is one script tag that brings visits, conversions, and revenue from your site into the warehouse – and it's how website messages from Journeys reach your pages. It has its own manual: Website SDK. The Push tab shows its status at a glance, and the SDK page itself flips to "Receiving data" the first time an event arrives.
Your event vocabulary
The Events tab is where you define the business moments that matter – a payment, a booking, a quote request. Register an event name and you get three ready-to-paste ways to capture it: a JavaScript call, an HTML attribute, or a server webhook. You can also set up no-code capture – point the event at a button, form, or URL on your site and the SDK fires it without any code change, even reading the value straight off the page.
Two details worth knowing:
- Events your site sends that aren't registered yet show up as seen from your site, not registered – one click registers them.
- An event can be marked as a suppression event: anyone who fires it is blacklisted from all contact. Built for a person's own request not to be contacted.
Registered events appear in the Warehouse tab as they stream in, can trigger journeys ("someone fires this event" enrolls them within about a minute), and can define audience segments.
Included events and what happens at the ceiling
Every plan includes a set volume of warehouse events – one event is one order, one payment, one conversion, one pushed event. The meter on Data → Warehouse names the number for your account ("Included events – X of Y on your plan") and turns amber as you approach the ceiling. Your plan page lists the volume that comes with each plan, and that page is the one to trust – it is the number the import checks against. If you expect to load more history than your plan includes, tell us before you start and we will size it with you.
On the built-in warehouse, each change to a customer's e-mail, phone, names or attributes is kept on their history as an event, and it counts toward your plan's events like any other event. Resending values that did not change counts nothing. A first customer file or customers push that changes many people can use a large part of a plan with a fixed number of events. Records and blocks are not events.
The rules at the limit are deliberately one-sided:
- CSV imports pause – an import that would pass your included volume is declined with the exact numbers, and your file is untouched. Upgrade, or trim the file, and import again.
- On a contract, live streams never stop. On an account with a contract number or a dedicated warehouse, website events, the data push and store syncs keep flowing past the volume: rejecting live data would destroy it, so we don't.
- On a plan with a fixed number of events, nothing is stored past it. Once the account holds that number, new events from the website, the data push and store syncs are not stored, and the data push says so in its answer. Change the plan on the Billing page to go on.
You get a bell notification at 80% and at 100%.
Higher plans include a dedicated warehouse of your own, which you switch on yourself under Data → Warehouse; it lifts the file-size limit on imports and is built for far larger books. It still has an included volume. Capacity beyond that – a cluster sized to millions of events a month – is arranged with us.
How to know it worked
- A CSV import confirms immediately and tells you where to look – purchases light up the Overview numbers on the spot.
- A contact import names the segment it created in Customer Intelligence → Audiences.
- The Website SDK page tells you where the install stands: "Installed – the tag is on your site" once the snippet is found in your page, "Script loaded" when the script reports in by itself (a tag manager, most likely), and "Receiving data" with your page views once events arrive. Check again re-reads the site on the spot.
- The Warehouse tab lists every event type the moment it streams in – including your registered custom events.