What are the customer field mappings between Tabs and HubSpot?

Last updated: January 5, 2026

HubSpot Customer Field Mapping

Overview

This document outlines the exact field mappings between HubSpot Company records and Tabs Customer records when syncing customers from HubSpot to Tabs.

Sync Direction: HubSpot → Tabs (one-way sync from HubSpot to Tabs)

Standard Field Mappings

Company-Level Fields

Tabs Customer Field

HubSpot Company Property

Notes

externalId

Id

HubSpot Company ID (used as external ID)

name

name

Company name

companyName

name

Company name

country

billing_country or 

country

Falls back to country if 

billing_country is not available

updatedDate

hs_lastmodifieddate

Last modified date from HubSpot

Contact Information Fields

Contact information is synced from associated HubSpot Contacts (not Company properties).

Tabs Contact Field

HubSpot Contact Property

Notes

firstName

firstname

From first associated contact

lastName

lastname

From first associated contact

primaryEmail

email

From first associated contact

Contact Sync Behavior:

  • All contacts associated with the HubSpot Company are synced

  • The first contact in the list becomes the primary contact (isPrimaryContactForSource: true)

  • Contacts are matched by email address

  • Contacts are marked with source: DataSource.HUBSPOT

  • Contacts removed from HubSpot are soft-deleted in Tabs (deletedAt is set)

Billing Address Fields

Billing address fields are only synced if syncCustomerAddressFromCrm is enabled in the CRM configuration.

Tabs Billing Address Field

HubSpot Company Property

Fallback Property (if main property is empty

addressLine1

billing_address

address

city

billing_city

city

state

billing_state

state

zip

billing_zip

zip

country

billing_country

country

Address Sync Behavior:

  • Only billing addresses are synced (shipping addresses are not synced from HubSpot)

  • Addresses are validated using address validation service (in production)

  • Invalid addresses cause the customer to be skipped during sync

  • Addresses are converted to Alpha-2 country codes (e.g., "US" instead of "United States")

Fields NOT synced

The following Tabs customer fields are NOT synced from HubSpot:

  • phone - Always empty string

  • shippingAddress - Always undefined

  • defaultCurrency - Always defaults to USD

  • isActive - Always true

  • Custom fields (unless explicitly mapped via custom field mappings, see below)

Custom Field Mappings

In addition to standard fields, custom fields can be mapped between HubSpot and Tabs:

How Custom Field Mapping Works

  1. HubSpot Custom Fields: Custom properties on HubSpot Companies can be synced

  2. Tabs Custom Fields: Merchant defines custom fields in Tabs on any customer record

  3. Mapping: Custom fields are mapped via the CRM configuration UI (see the bottom of this article for details)

Custom Field Sync Process

  1. Custom fields are fetched from HubSpot Companies

  2. Values are stored in the Tabs backend

  3. If a mapping exists to a Tabs custom field, the value is also populated to the mapped customer field

Note: Custom fields are synced separately from standard fields.