Connecting a WooCommerce store to HubSpot looks like a setup task. It's really a data design decision — and the projects that go wrong are almost always the ones that skipped writing it down. An integration specification document is the agreed plan for exactly what data moves between WooCommerce and HubSpot, in which direction, on which trigger, and what happens at every edge case — written before anyone connects the two systems. Get it on paper first and the build is boring. Skip it and you'll be untangling duplicate contacts and mismatched orders for weeks. Here's the practitioner's read on what the spec needs to cover.
Why write a spec at all instead of just connecting the two?
Because the integration is only as good as the agreement behind it — and most of the cost of a bad integration is fixing data nobody decided how to handle. WooCommerce and HubSpot model the world differently. WooCommerce thinks in customers, orders, and products; HubSpot thinks in contacts, companies, deals, and properties. Without a spec, those mismatches get resolved on the fly by whoever builds it — and their guesses become your data model. The spec forces the hard questions up front: what's a contact, what's a deal, when does an order create a record, and what do we do when the same customer appears twice. Worked example: deciding before launch that a guest checkout with no account still creates a HubSpot contact keyed on email — so you don't discover months later that half your buyers were never captured.
What objects and fields should the spec map?
Every WooCommerce entity that matters, mapped to a specific HubSpot object and property, with the field type and unique key written down. At minimum: WooCommerce customers map to HubSpot contacts (keyed on email), orders map to deals or to a custom object, and products map to line items or a product library. For each mapping, the spec records the source field, the destination property, the data type, and whether the property already exists in HubSpot or needs creating. This is where most silent failures start — a field that exists on one side with no home on the other gets dropped, and nobody notices until a report comes up empty. Writing the map down turns those gaps into decisions instead of surprises.
What sync rules and triggers does it need to define?
Direction, trigger, and frequency for every data flow — because "keep them in sync" is not a specification. For each mapping the spec answers three questions: which way does the data move (one-way to HubSpot, or two-way), what event triggers it (new order, status change, refund), and how often (real-time, or batched). A new paid order might create or update a deal in HubSpot immediately; a product catalog might sync nightly. Crucially, the spec defines the unique identifier that prevents duplicates — email for contacts, order ID for orders — so a returning customer updates their existing record instead of spawning a new one. Without these rules written down, the integration does something — just not necessarily the thing you wanted.
What edge cases will break it if you don't plan for them?
Refunds, cancellations, guest checkouts, duplicate emails, and deleted records — the cases that are rare individually and inevitable in aggregate. A spec that only covers the happy path will work in the demo and fail in production. Document what happens when an order is refunded (does the deal move stage, or close lost?), when a customer checks out as a guest (do you still create a contact?), when two orders share an email but different names, and when a record is deleted on one side. This is the order we follow with clients: map the objects, define the sync rules, then spend real time on the edge cases — because that's where data integrity is actually won. A clear edge-case section is the difference between an integration you trust and one you babysit.
The IV-Lead take
The integration spec is the cheapest insurance you'll buy on a HubSpot–WooCommerce project. An hour spent agreeing what data moves, in which direction, on which trigger, and what happens at every edge case saves weeks of untangling later. The build is the easy part; the agreement is the work. As a HubSpot Gold Solutions Partner, we write the spec before we touch the connection — because a clean integration is something you design, not something you debug.
Connecting a store or another system to HubSpot? Book a 30-minute portal audit — we'll help you map the data and spot the edge cases before they become support tickets. For the full picture, see how we approach integrations.
Frequently asked questions
Do I really need a spec for a small store?
Yes — the smaller the team, the less time you have to clean up a bad integration. A short, clear spec for a small store still prevents duplicates and dropped data, and it takes far less time to write than to fix.
What's the most common mistake in a HubSpot–WooCommerce setup?
Not defining the unique identifier, which leads to duplicate contacts and orders. Decide your keys (email for contacts, order ID for orders) before anything syncs.
Should WooCommerce orders become deals or a custom object in HubSpot?
It depends on how you sell. If orders move through a sales process, deals fit; if they're transactional records you want to report on, a custom object is often cleaner. The spec is where you make that call deliberately.
One-way or two-way sync?
Start one-way (WooCommerce into HubSpot) unless you have a clear reason to write back. Two-way sync multiplies the edge cases and the failure modes, so only take it on when the business case justifies the extra complexity.
