What syncs to what
This page is the authoritative map of how each Stripe object lands in HubSpot. Understanding the routing here explains most “why did it sync there?” questions.
Customers → Companies and/or Contacts #
A Stripe Customer is routed by the names present on it:
| Stripe customer has… | Becomes in HubSpot |
|---|---|
| a business name | a Company |
| an individual name | a Contact |
| both | a Company and a Contact, associated |
| neither | a Company (fallback) |
Company matching (dedup) #
To avoid creating duplicate companies in an established portal, customers are matched before they’re created. The matching key is configurable per organization on the Mappings screen:
- off — never match; always create.
- domain (default) — match an existing company by email domain.
- name + domain — match on both.
Heads-up: with
domainmatching, multiple Stripe customers that share an email domain collapse onto one HubSpot Company (B2B account rollup). This is intentional, but worth knowing if you expect one company per customer.
Subscriptions → native Subscriptions #
A Stripe Subscription becomes a HubSpot native Subscription object (not a
Deal). Status, billing frequency, dates, and payment rollups are mapped to the
standard hs_* subscription properties, with stripe_mrr / stripe_arr and a
few other figures written to custom properties.
Native Subscriptions require Commerce Hub. If your portal doesn’t have it, connect anyway — every other object still syncs.
Prices → Products #
Each Stripe Price becomes a HubSpot Product. Subscription and invoice line items link back to the synced product where one exists.
Invoices → native invoices and/or rollups #
Invoices support two strategies (default: both):
- Native invoice objects — a draft, non-billable tracking invoice per Stripe
invoice, with the real figures in
stripe_*properties. Available on all hub tiers. - Company rollup — aggregate totals written onto the Company.
Line items #
Line items are a first-class, mappable object derived from subscription items and invoice lines. They’re deduplicated by their Stripe id and associated reciprocally to their parent subscription or invoice.
How records are named #
Each synced record gets a human-readable name derived from your Stripe data —
falling back to an opaque id only when nothing better exists. Naming is purely
cosmetic: identity and de-duplication always run off the stripe_* id, so a
record’s name never affects matching or create-vs-update.
For each record, the first available value wins:
| HubSpot record | Name (first available wins) | Example |
|---|---|---|
| Company | business name → name → email → Stripe customer id | Acme Mortgage |
| Contact | first / last name (from the customer’s name); shown by email when unnamed — never an id | Jane Smith |
| Product | product name → price nickname → Stripe price id | Enterprise Plan |
| Subscription | Subscription for {customer} ({subscription id}), where customer is its name, description, or email |
Subscription for Acme Mortgage (sub_1a2B3c…) |
| Subscription line item | price nickname → product name → Stripe item {id} |
Enterprise Plan |
| Invoice line item | Stripe’s line description → price nickname → product name → Invoice line {id} |
1 × Enterprise Plan (at $250.00 / month) |
| Native invoice | Invoice {number} → customer name → Stripe invoice |
Invoice INV-0042 |
For example, a subscription belonging to the Stripe customer Acme Mortgage
(cus_9x…) on subscription sub_1a2B3c… becomes the HubSpot Subscription
Subscription for Acme Mortgage (sub_1a2B3c…), and its line item — a price
under the Enterprise Plan product with no nickname — is named Enterprise Plan after the product rather than the raw Stripe item si_… id.
Why a record might show a bare id (e.g. a line item reading
Stripe item si_…): the source had no better label and its parent product hadn’t synced yet. Because products sync before subscriptions and invoices, a full backfill or the nightly reconcile resolves these names automatically on the next pass.
Custom fields and field rules #
Beyond the built-in mapping, you can map any Stripe source path to any
standard or custom HubSpot property on the Mappings screen, with optional
per-field write policies (always, if_empty, on_create, never) so syncs
never clobber values your team owns in HubSpot.
How records stay in sync #
Every synced record is tracked in a local id mapping, which is the source of truth for idempotency. That’s what lets a backfill, a real-time webhook, and the nightly reconcile all touch the same record without creating duplicates.