Field mappings & write policies

Every object ships with a base mapper that fills the common HubSpot properties for you — a Stripe customer’s name, domain, address; a price’s amount; a subscription’s status and dates. You don’t have to configure anything for those to flow. This page covers the layer on top: routing extra Stripe data into HubSpot, translating dropdown values, and protecting fields from being overwritten.

All of this lives on the Mappings screen, one card per Stripe object. See What syncs to what for the object routing this builds on, and Custom fields for creating the stripe_* properties these can target.

Base mappers vs custom field rules #

The base mapper produces a set of properties; your field rules are applied on top, and a rule’s value overrides the base value for the same property. Use rules to:

• push Stripe data the base mapper doesn’t cover (e.g. a metadata key), or
• redirect an existing value onto a different HubSpot property.

A rule is just a Stripe source → HubSpot property pair (plus a type, and an optional value map for dropdowns).

Mapping a Stripe source to a HubSpot property #

In Custom field rules, click + Add rule. Each rule has two halves:

The Stripe source (a dotted path) #

Type the path to the value on the Stripe object, using dots to walk nested fields. The most common case is a metadata key:

metadata.plan_tier

The path is resolved against the raw Stripe object, so email, address.city, or metadata.account_id all work. If the path doesn’t resolve, the rule is skipped for that record — nothing is written.

The HubSpot property (searchable / creatable) #

Pick the target with the HubSpot property combobox. It’s searchable across the object’s standard and custom properties (custom ones are tagged custom), and it’s creatable — if you type a property name that isn’t in the list, you can choose Use “…” to target it directly. The property’s type is read from HubSpot, so you don’t set it by hand.

Enum value maps #

When the target property is an enumeration (a dropdown / select), a small value-map editor appears under the rule. Stripe’s raw values rarely match HubSpot’s option values exactly, so you map them:

Unmapped enum values are skipped. If a Stripe record has a value with no row in the table, the property is left unwritten for that record rather than sending a value HubSpot would reject. Add a row for every Stripe value you expect.

Per-field write policies #

Under Write protection, each property the object writes gets a write policy that decides whether a sync may set it:

The motivation is simple: don’t clobber HubSpot-owned fields. If your team curates a company’s name or description by hand, set that field to Only if empty or Never write so a backfill or nightly reconcile can’t overwrite their work. For if_empty, the sync reads the current HubSpot value first and only fills it when blank.

The Stripe id join key (e.g. stripe_customer_id) is always written regardless of policy — it’s what keeps the record matchable on the next sync.

Company matching (dedup) #

On the Customers card, Company matching (dedup) controls how a Stripe customer adopts an existing HubSpot company instead of creating a duplicate:

• off — one company per customer; never merge.
• domain (default) — match an existing company by email domain.
• name + domain — match on both (stricter).

Shared-company caveat (B2B): with domain matching, multiple Stripe customers that share an email domain collapse onto one HubSpot Company. That’s the right behavior for account rollups, but if you expect exactly one company per customer, choose off instead.

Where to next #

• Custom fields — create the stripe_* properties your rules and stripe_mrr / stripe_arr figures write to.
• What syncs to what — the object routing these mappings sit on top of.