# Integrations: Salesforce, Stripe, product data and data sync Facts checked against HubSpot's live docs on 2026-10-17. Deep troubleshooting of an existing sync belongs to the crm-sync-and-field-ownership skill if installed; this file covers what to decide before switching one on. ## The integration record Write one record per integration before connecting it: ```yaml integration: billing_to_hubspot direction: one_way_source_to_hubspot objects: - source: billing customer hubspot: company match_key: acme_account_id # unique-value property create_if_no_match: false # unmatched goes to the review queue writes: # permitted-field list; nothing else - subscription_status - recurring_revenue_monthly - billing_observed_at - billing_synced_at blank_input: preserve_existing_and_flag explicit_clear: allowed_only_for_verified_cancellation stale_update: reject_if_source_version_older replay_test: same_delivery_twice_creates_nothing failure_queue: owner revops, reviewed daily during launch deletion_policy: source deletion sets status, never deletes the HubSpot record credential: stored in the integration platform; type recorded, value never ``` The values are illustrative. Every field must be answered before the integration writes to production. ## Generic data sync apps For HubSpot's data sync apps: - You choose a direction and a default app that wins discrepancies. The default app does not override the direction. - If the default app has no value, nothing changes in the other app. Check this against the meaning of a blank in your property register. - Sync filters only limit which records sync initially. Once a record syncs, it keeps syncing on the mappings. A filter is not an ongoing exclusion. - Default matching: email for contacts, name or domain for companies, with case and punctuation ignored for names. Name matching can merge two different companies' data; prefer a key you control where the app allows it. - Custom property mappings need a paid Data Hub subscription. If the design depends on a non-default field, confirm the entitlement in step 2. - At setup, all existing records in both apps pass through the sync engine; large databases can take days. Saving the sync configuration restarts the initial sync, so every later save is another full pass. Before any save, pause workflows that react to the mapped fields, and turn them back on only after the initial sync completes (HubSpot emails when it does). - In most cases data sync only associates invoices with contacts automatically. Plan how invoices or billing summaries reach the company. - "Two-way" with "HubSpot wins" is not a field ownership policy when different fields have different owners. Use separate mappings, one-way fields, or a controlled custom integration. ## Salesforce Prerequisites: - HubSpot Professional or Enterprise on a listed hub, and Account Access permission. - A Salesforce edition with API access, or Salesforce Professional. - The connected Salesforce user is a system administrator; that user's permissions decide what HubSpot can do. - One Salesforce org per HubSpot portal. Several portals can connect to one org by installing in each. - Turn off all Smart Transfer sync connections first. Running both creates duplicates in both systems. Smart Transfer does not transfer custom objects. - Turn off "Create and associate companies with contacts". HubSpot does not recommend it with this integration because it can create duplicate companies. - Name a Sync Health owner, and turn on email notifications for integration suspension (the suspension errors page links to the notification settings). Common suspension causes are the Salesforce API limit, the HubSpot API allocation running out, and missing object or field permissions for the integration user. - Define how records are reassigned when an owner leaves. A record owned by an inactive Salesforce user raises the "Inactive Salesforce owner" error until it is reassigned to an active user. How records enter HubSpot when Salesforce stays connected: - Records that exist in Salesforce enter through the integration: install, then the integration's own Salesforce import or a segment resync, in batches within the "Allocated to HubSpot" budget. - CSV import is only for records with no Salesforce counterpart. The live import pages do not document how a CSV-created company pairs with an existing Salesforce account, so do not rely on it. - The crosswalk carries the Salesforce record ID for every record that has one. - The Salesforce import covers leads, contacts, accounts, opportunities, tasks, a campaign, cases, events and custom objects, and large imports can take hours. For leads and contacts only the email syncs at import, then a sync fills the other fields. - Segment resync needs Marketing Hub Professional or Enterprise, and HubSpot asks for at least three Salesforce API calls per segment member to be available. Verify both on the live page before planning a resync. Behaviour to plan for: - Installation does not sync existing records. Import or resync deliberately, in batches, within API capacity. - A single contact sync can take up to four Salesforce API calls. Sync Health (Settings > Integrations > Connected Apps > Salesforce > Data sync tab) shows calls used in the last 24 hours, the Salesforce limit, and an "Allocated to HubSpot" field you can set. Plan resyncs against what other Salesforce integrations need. - Field rules for standard objects: Prefer Salesforce unless blank, Always use Salesforce, Two-way (most recent value wins, clears propagate both ways), Don't sync. Check the current company and deal sync versions for any extra rules. - Custom object sync needs Enterprise. Each field is Two-way, Always use Salesforce or Always use HubSpot (no "Prefer Salesforce unless blank"), and each association syncs two-way or in one chosen direction. The HubSpot custom object must exist first, and existing records need a separate import. The flexible seats-and-credits supplement describes different entitlements; confirm the programme before promising two-way. - A change to a Salesforce formula field alone does not trigger a sync. A change to a mapped field used in the formula does; inputs from other records do not. Test a formula-driven field by changing its input field. - Owner mapping is always two-way, and owners sync only when they match an active Salesforce user's name and email. - New mappings do not backfill existing values. Resync or import to populate. - On the first sync of a field with no sync history, the current Salesforce value is the baseline and can overwrite a newer HubSpot value. Decide which side holds the truth for each mapped field before the first pairing. - The inclusion segment controls HubSpot-to-Salesforce eligibility. It must be an active segment; selecting it does not push existing members; mapped fields can update a Salesforce record before the HubSpot record joins the segment; every new pairing is treated as an initial sync. It is an operational filter, not a security boundary. - Check inclusion criteria for circular dependencies. HubSpot cannot evaluate the criteria until the record exists and has synced, so a rule that depends on a Salesforce value only available after the first sync never admits the record. - Salesforce-to-HubSpot selective sync exists for custom objects, tickets, companies on the new company sync, deals on the new deal sync, and activities. Contacts are not on that list. - Lifecycle: the integration only moves lifecycle forward, and its automatic lifecycle transition setting applies to all contacts associated with the same company. - HubSpot owner rotation can fight Salesforce owner sync: Salesforce may write the previous owner back. Pick one system to assign owners. Field ownership for the pair: write each mapped field's originating system, rule, blank meaning, first-sync behaviour and every other writer (workflows, imports, enrichment). Give marketing qualification its own field instead of sharing the sales stage. Test records before enabling: - One eligible, one missing a required field, one excluded by the segment. - One already in Salesforce with a different value: expect the per-field baseline rule. - One account already loaded by CSV, then synced: expect one company. A second company means the CSV path must close for Salesforce records. - One formula-driven field, changed through its input. ## Stripe and billing Four different jobs, documented separately by HubSpot: - Payment processing: HubSpot revenue tools collect payments through a connected Stripe account. - Subscription migration: moving management of existing Stripe subscriptions into HubSpot. - Switching processors. - Data sync without payment processing. On 2026-10-17 the documented mapping was: Stripe customers to contacts (bi-directional); invoices to invoices, products to products (one-way from Stripe); subscriptions and payment transactions to custom objects (one-way); Stripe data to Data Studio (one-way). Conditions checked on 2026-10-17 (verify live; app listings change without notice): - Subscription sync into custom objects needs Enterprise, per the Stripe Data Sync app listing. Without it, sync summaries onto the company instead. - Data sync associates invoices with contacts only, in most cases. A Stripe customer that represents a company needs its own path to the company record. - Saving the sync configuration restarts the initial sync. Pause workflows on mapped fields before each save. - The native subscriptions object depends on collecting payments through HubSpot payments or Stripe payment processing. Check that before planning it. Decisions before connecting: - Which system owns subscription creation, plan changes and entitlements. If the product owns them through Stripe Billing, sales visibility alone does not justify migration. - Whether a Stripe customer is a person or a company. A billing email often belongs to finance or a shared inbox; it is a poor company key. Plan how the company association and account key are set. - Whether subscription-level records are needed in HubSpot (and whether the entitlement exists), or whether company summaries are enough. - The company summary rule when an account has several subscriptions, for example: status by precedence (active, then past_due, then trialing, then cancel_scheduled, then ended), and renewal as the next upcoming renewal across active subscriptions. - The MRR definition. An invoice total includes tax, one-time charges, credits and prorations; it is not MRR. Name the definition in `metrics.md`. - Separate fields for cancellation scheduled, subscription ended, payment overdue, and account with no active subscriptions. One "churned" flag cannot hold them. - A historical backfill must not restart onboarding or open payment-recovery cases. Guard those workflows on an observed date, not on the field changing. - If HubSpot sends payment reminders, agree with finance how they sit next to Stripe's own recovery emails, so a customer does not get both. - Include the Stripe account and live or test mode in keys when several Stripe accounts or environments exist. ## Product data - Sync summaries tied to a decision, not raw events. Starting set for a trial account: `trial_started_at`, `first_value_at`, `active_users_7d`, `subscription_status`, `product_refreshed_at`. - Define each one in `metrics.md` (qualifying activity, window, excluded users). - Keep missing distinct from zero. A failed sync must not make an active customer look inactive: show `product_refreshed_at`, and have workflows check freshness before acting. - Routes: a reverse ETL tool, a small service, or the CRM batch upsert endpoint (`POST /crm/objects/2026-09/{objectType}/batch/upsert`), which matches on an `idProperty` whose values are unique. Inspect per-record errors in the response; a 200 response does not mean every input succeeded. Associations are a separate operation. - Respect API versions: date-based versions are released each March and September and become unsupported 18 months after release. - Credentials: new private apps cannot be created in existing accounts after 26 October 2026; system-to-system integrations use service keys from developer platform projects 2026.09 or later. Store keys in the integration platform's secret store. ## Gate for every integration - One controlled source change traced to the HubSpot record, then to the view or workflow that uses it. - The same delivery replayed: no new record, no second task, no second enrolment. - A deliberately excluded record stays excluded in both directions. - A blank and an explicit clear behave as the register says. - A connector reporting a successful job is not evidence; the record is. - Inside 14 days of the first write, a Super Admin knows how to run Restore CRM changes filtered to this integration.