HubSpot associations

As records sync from Stripe, we don’t just create them in isolation — we link them together in HubSpot so a company’s subscriptions, invoices, and line items all hang off the right records. This page lists every association we create.

There are two kinds of HubSpot associations, and we use both:

Default (unlabeled) — HubSpot’s built-in primary association between two object types (v4 default). Most links are these.
Labeled (typed) — a specific association type id when HubSpot models the relationship as a distinct label. We use these where HubSpot defines a dedicated type.

The full map #

From	To	Type	Created when
Contact	Company	Default	A customer maps to both a Company and a Contact
Subscription	Company (or Contact)	Default	A subscription syncs — linked to its customer’s record
Subscription	Line item	Labeled (`301`)	Line items are created for a subscription
Line item	Subscription	Labeled (`302`)	Reciprocal of the above
Invoice	Company	Default	An invoice syncs — via its customer mapping
Invoice	Subscription	Labeled (`622`)	The invoice belongs to a synced subscription
Invoice	Contact	Default	The invoice has a recipient contact
Invoice	Line item	Default	Line items are created for an invoice

The 301 / 302 / 622 values are HubSpot’s standard association type ids (subscription↔line item, invoice→subscription). Everything else uses HubSpot’s default primary association.

How it fits together #

A typical synced customer ends up shaped like this:

Company
├── Contact                    (contact → company)
├── Subscription               (subscription → company)
│   └── Line items             (subscription ↔ line item, 301/302)
└── Invoice                    (invoice → company)
    ├── → Subscription         (invoice → subscription, 622)
    ├── → Contact              (invoice → contact)
    └── Line items             (invoice → line item)

Where the customer is mapped to a Contact instead of (or as well as) a Company — see What syncs to what for the routing rules — the subscription/invoice links point at that record accordingly.

Things worth knowing #

Idempotent. Associations are created with HubSpot’s upsert semantics, so re-running a backfill or reconcile re-asserts the same links without creating duplicates.
Best-effort, non-blocking. If an association call fails (e.g. a transient HubSpot error), the underlying records still sync — the run won’t fail just because one link didn’t land. A later reconcile re-asserts it.
Batched. Backfills and reconciles create associations in bulk (HubSpot v4 batch endpoints) rather than one call per pair, to stay well under HubSpot’s rate limits.
Line items are derived. They’re never synced on their own — they’re created and associated alongside their parent subscription or invoice.

For the field-level detail of what data lands on each record, see Field mappings & write policies.