Back to blog
Link the Same Customer Across Stripe, Postgres and Notion

This blog is written by AI for SEO

Link the Same Customer Across Stripe, Postgres and Notion

HelixDB8 min read

To link customer records across systems, pick a few reliable match keys, normalise them, link records by exact match first, queue the doubtful cases for a person, and keep the source of every value so you can trace any answer back. You can do all of that by hand with SQL and a spreadsheet, and this guide shows how. Then it shows how Helix Foundry, HelixDB's open-source app for building one connected ontology over your tools, drafts the links for you to review.

The pain is familiar. Stripe knows "Acme Corp" as cus_9sK2 with billing@acme.com. Your Postgres app database knows it as account 4417 with a different admin email. A Notion page called "ACME (Enterprise pilot)" holds the notes your success lead wrote last quarter. Reports and agents need one record. Nobody wants to build it twice.

The job: one customer, three systems, three different names

The job is to decide, for every row and document, which real-world customer it describes, and to record that decision somewhere both people and software can read. Each system built its own idea of a customer for its own purpose. Stripe's customer is a billing identity. Your Postgres row is a product account with users hanging off it. A Notion page is a human narrative about a company, written whenever someone needed it.

That is why the same customer shows up under different names, emails and ids. It is also why a naive join fails: there is no column all three systems share. You have to build the linkage yourself, and the quality of that linkage decides whether anything downstream, from MRR reports to a support agent, can be trusted.

Treat the result as links between records, not a merge. Leave each source untouched, and add a layer that says "these three things are one customer, and here is why we think so." That framing makes every later step easier, especially conflicts and audits.

Pick match keys before you pick a tool

Pick match keys by how strong they are, then apply them in order from strongest to weakest. Four keys cover most Stripe, Postgres and Notion setups.

1. Stripe customer id stored in Postgres. If your app saved the Stripe id when it created the customer, you already own the best key there is. Join your accounts table to Stripe on that column and you are done for every customer created through your product. Check for nulls: customers created by hand in the Stripe dashboard, or before the integration existed, will not have it. Treat Stripe ids and your own ids as source-specific identifiers. They only link across systems when one side stores the other's id.

2. Normalised email. Trim whitespace and lowercase. Strip plus-tags if your users use them. Exact-match on the result. It is high confidence for a person, but it misses everyone who signed up with a different address in each system.

3. Email domain as a blocking key. The domain (acme.com) is not an identity. Plenty of people share one, and free-mail domains like gmail.com group strangers. Use it to shrink the candidate set instead: only compare records that share a domain, then decide with a second signal such as name or company. Exclude free-mail domains from blocking entirely.

4. Company name normalisation. Lowercase, drop punctuation, and strip suffixes like Inc, Ltd, LLC and Corp so "Acme Corp." and "ACME" compare equal. Notion page titles usually need this, since they are free text with parentheticals and project names. Fuzzy-match what is left and score each pair. Auto-link only the high-confidence ones and route borderline pairs to a person.

A workable order: exact match on the stored Stripe id, then exact match on normalised email, then domain-blocked fuzzy match on company name. Write down every link with the rule that produced it. You will need that column later.

Handle conflicts and keep provenance: what to do when systems disagree

When systems disagree, don't pick a winner silently. Record both values with their sources and decide by an explicit rule or a person. Conflicts are guaranteed. Postgres says the plan is "Team", Stripe's subscription says "Enterprise", and the Notion page says the customer is "moving to Enterprise in Q3". All three can be true at different moments.

Three rules keep this sane by hand:

  • Rank sources per field, not per system. Stripe wins on billing status and amounts. Your app database wins on product usage and seat counts. Notion wins on context and intent. A single "system of record" for everything is how wrong values get blessed.

  • Keep a provenance column. For every value you load into the unified record, store the table, row id or document, and the exact quote or cell it came from. If you can't say where a value came from, you can't defend it in a meeting.

  • Queue true ties for review. If two high-ranked sources disagree on the same field, don't average or overwrite. Put it in a review list with both values and their evidence.

By hand this means a spreadsheet of links, a second sheet of conflicts, and discipline. It works for a few hundred customers. It decays the moment someone edits a source and nobody reruns the script.

Helix Foundry does the same job with the same logic, but it handles the drafting and bookkeeping. You connect sources, an ontology agent drafts the types, links and mappings, you review, and you make a version current.

1. Run Foundry. On your own machine, with Docker Compose v2 and ports 3000 and 8333 free:

git clone https://github.com/helixdb/helix-foundry.git
cd helix-foundry
docker compose up -d --wait

Then open http://localhost:3000. The local install is single-user on your own computer with no sign-in, so keep it on localhost. Or use Helix Cloud at foundry.helix-db.com and choose Set up with your agent. Details are in the Foundry README.

2. Connect your sources. For this job that is Stripe, PostgreSQL and Notion. Add each source, test it and sync its tables, as covered in the Foundry docs.

3. Generate the ontology. A generation sends your synced sources to Foundry's agent. The agent drafts a version: types such as Customer, Subscription and Account, the links between them, the mappings from your tables, and rules. Drafts are saved as separate versions, so nothing is live yet. If you want the Postgres side in more detail, see Map Postgres Tables to an Ontology for AI Agents.

4. Review. Open the draft and check the proposed links against your match keys. Does it join Stripe customers to Postgres accounts on the stored Stripe id? Does it treat the Notion page as describing the same Customer? Fix what is wrong, then make the version current. Only the current version is used for a load, and older versions can be restored.

The review step is where your judgement goes. You aren't writing joins. You're approving or correcting them.

How Foundry keeps provenance, flags disagreements for review and syncs only what changed

Foundry keeps provenance as a property of every loaded value, not as a column you have to remember to maintain. Each value keeps where it came from: a row in a source table, or a quote in a document. Click a customer's plan and you see the Stripe row behind it. Click a claim from a Notion page and you see the sentence it was read from. That is the audit trail you would otherwise build in a spreadsheet.

When sources disagree, Foundry doesn't quietly pick one. Facts that documents disagree on wait in Needs review, where a person sees the competing values with their evidence and decides. That matches the third rule above: queue true ties instead of overwriting them.

Syncs read only what changed. Your linked record stays current as the sources move, and the same review flow applies to new conflicts.

Two more properties matter for ops leads. Foundry never writes to your sources, so it can't damage Stripe or Postgres. And access follows the sources: a user who can't see a source can't see anything in the ontology grounded by it. See Ontology Access Control: Who Sees What Your Agents Know.

Honest trade-offs: where Foundry helps and where you still make the calls

Foundry helps most where the work is repetitive and the evidence is scattered: drafting links across many tables, reading documents for claims, tracking where each value came from, and picking up changes without a full reload. It turns weeks of join-writing and spreadsheet upkeep into a review task.

It doesn't decide your business rules for you. You still choose which source wins which field, whether a subsidiary and its parent are one customer, and what counts as a duplicate. The agent proposes and you approve. A draft that looks plausible can still link two different companies with similar names, so read the links, especially the fuzzy ones.

Also expect to bring clean-enough inputs. If Postgres never stored the Stripe id and emails are blank, the agent has fewer strong keys to work with, and more links will land in review. That is the right behaviour, but it costs you more time. Fixing the key at the source, by storing the Stripe customer id on the account row going forward, beats any amount of downstream matching.

Finally, Foundry is the app and HelixDB is the database it loads into. If you only need a one-off dedupe of a few hundred rows, a script is fine. Foundry earns its place when the sources keep changing and agents or reports need to trust the result. For the wider picture, compare Ontology vs Knowledge Graph.

Start with one customer and the draft Foundry makes of it

Do the manual version on ten customers first: write down your match keys, rank sources per field, and note every conflict. Then clone helix-foundry, connect Stripe, Postgres and Notion, and compare its draft links against your list. Where they differ, you have found either a gap in your rules or a mistake in the draft, and both are worth knowing. Star the repo at github.com/helixdb/helix-foundry and try it on your own data.

Build with HelixDB

Give your coding agent the setup prompt, or sign up and deploy a database.

Sign up