> ## Documentation Index
> Fetch the complete documentation index at: https://zenskar.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot

HubSpot is a CRM and CPQ integration. It synchronizes customer, product, and
contract records between a HubSpot portal and Zenskar. Each object type is
configured independently, and each direction of sync is opt-in.

## Concepts

### Objects

Zenskar maps three of its objects to HubSpot objects. Each is configured on its
own tab in the connector settings and enabled independently.

| Zenskar object | HubSpot object |
| :- | :- |
| Customer | Company |
| Product | Product |
| Contract | Deal |

A Zenskar contract is assembled from a HubSpot deal together with the deal's line
items and one of its associated companies.

### Sync direction

Each object has an independent sync direction.

| Direction | Behavior |
| :- | :- |
| Import only | Records flow from HubSpot into Zenskar. |
| Export only | Records flow from Zenskar into HubSpot. |
| Import & Export | Records flow in both directions. |

All three values are available for every object, but each one defaults to a
particular direction in practice:

| Object | Default direction | Notes |
| :- | :- | :- |
| Contract | HubSpot → Zenskar | Export only works for a contract imported from a deal; Zenskar never creates a deal in HubSpot |
| Customer | HubSpot → Zenskar | Or linked to an existing company |
| Product | HubSpot → Zenskar | Or linked to an existing product |

> [!NOTE]
>
> A HubSpot connection binds to exactly one portal. The Connections page has no
> New Connection action for HubSpot.

***

## How-to guides

### Connect

This procedure connects one HubSpot portal and configures object sync. Complete
the steps in order.

#### Prerequisites

* A HubSpot account with permission to authorize app installations for the target
  portal.
* A Zenskar account that can manage integrations.
* At least one Zenskar business entity. A connection cannot be activated until a
  business entity is assigned to it. The business entity assigned to the
  connection must be the default business entity in Zenskar.

***

#### Step 1: Create the contract date properties in HubSpot

Zenskar sets a contract's start and end dates from properties on the HubSpot
deal, which has no native contract-date property. Skip this step if you aren't
syncing contracts.

1. In HubSpot, open the **Settings** menu from the top navigation bar.

2. In the left sidebar, select **Properties**.

3. In the **Select an object** dropdown, choose **Deal properties**, then click
   **Create property**.

   ![HubSpot deal properties, with Select an object set to Deal properties and Create property highlighted](https://assets.zenskar.com/20240301/crms-and-cpqs-hubspot-deal-properties.png)

4. Create the following two properties. For each, set **Field type** to **Date
   picker** and enter the **Property label** exactly as shown, then click
   **Create property**.

   | Property label | Field type | Internal name HubSpot generates |
   | :- | :- | :- |
   | Contract Start Date (Zenskar) | Date picker | `contract_start_date__zenskar_` |
   | Contract End Date (Zenskar) | Date picker | `contract_end_date__zenskar_` |

The connector's default field mapping looks for deal properties with these exact
internal names. If you instead map Start Date and End Date to different deal
properties in the [Contracts tab](#contracts-tab) (Step 4, General Fields), this
default no longer applies and any date property works.

***

#### Step 2: Connect the HubSpot portal

Connecting authorizes Zenskar to access one HubSpot portal through OAuth 2.0. No
API key or secret is entered into Zenskar.

1. In the Zenskar sidebar, open **More > Integrations**.

2. On the **Integrations** tab, select the **CRM** category.

3. On the **HubSpot** card, click **Connect**.

   ![The Integrations page, with More > Integrations, the CRM category, and Connect on the HubSpot card highlighted](https://assets.zenskar.com/20240301/crms-and-cpqs-hubspot-integrations-connect.png)

4. In the confirmation dialog, click **Connect**.

5. Sign in to HubSpot with an account that can authorize app installations, and
   approve the requested access.

6. HubSpot redirects back to Zenskar. The connection appears on the
   **Connections** tab with the status **Pending Configuration**.

***

#### Step 3: Assign a business entity

Each connection maps to exactly one Zenskar business entity. The connection
cannot be configured until one is assigned.

1. On the **Connections** tab, locate the connection.
2. Click **Select Business Entity** and choose the Zenskar business entity that
   this portal represents.

![The Connections tab before a business entity is assigned, showing the banner and the Select Business Entity button](https://assets.zenskar.com/20240301/crms-and-cpqs-hubspot-entity-not-configured.png)

***

#### Step 4: Configure object sync

Open the configuration screen and, for each object type, set its sync direction
and field mapping. The three tabs are saved together.

1. On the **Connections** tab, click **Edit** on the connection. The
   configuration screen opens with the **Customers**, **Products**, and
   **Contracts** tabs.
2. On a tab, set the **Sync** toggle to **Sync ON**.
3. Select a **sync direction**: **Import only**, **Export only**, or **Import &
   Export**.
4. On the **Products** and **Contracts** tabs, optionally add **Sync Condition
   Filters**. Each condition is a **field**, an [**operator**](#condition-operators),
   and a **value**; multiple conditions are combined with **AND**. For
   contracts, a deal is imported only when every condition is satisfied.
5. Under **Field Mapping**, open each group in the left sidebar and map its rows.
   Each row binds a **Zenskar field** to a **HubSpot field**, with an optional
   **default value** applied when the HubSpot field is empty. The HubSpot field
   list is read from the connected portal, so custom properties are selectable.
6. Repeat steps 2 through 5 for the other tabs, then click **Save Configuration**.

The connection status changes to **Configured**.

![The Customers tab of the configuration screen, with Customer Sync, Sync Direction, Select Zenskar Entity, and Field Mapping](https://assets.zenskar.com/20240301/crms-and-cpqs-hubspot-configure-sync.png)

The Customers tab is shown above as a representative example. Products and
Contracts follow the same pattern, with a Sync Condition Filters section and
different Field Mapping groups. See the full layout of each tab below.

> [card] [Customers tab](#customers-tab)

> [card] [Products tab](#products-tab)

> [card] [Contracts tab](#contracts-tab)

***

#### Step 5: Verify the sync

1. In HubSpot, make a qualifying change: create or update a company, or move a
   deal into a state that satisfies the contract filters.
2. In Zenskar, open **More > Integrations**, select **HubSpot**, and open the
   **Logs** tab.
3. Confirm a sync event with the status **Success** for the record. Select the
   event to inspect its **Request** and **Response**.
4. If an import event has the status **Failed**, open it to read the error
   reason. After resolving the cause, click **Retry** to reprocess the event.

The Logs tab is also where sync activity is monitored after go-live.

***

### Disconnect

1. On the **Connections** tab, click **Disconnect** on the connection.
2. In the confirmation dialog, which states that all resource mappings will be
   deleted, click **Delete**.

Disconnecting:

* Removes the connection and the resource mappings linking Zenskar records to
  their HubSpot counterparts.
* Leaves the Zenskar records and the HubSpot records intact.
* Triggers HubSpot to notify the portal that the app was uninstalled, with a
  reinstall link sent to its super admins.

Reconnecting requires repeating this guide from Step 2.

> [!NOTE]
>
> There is no separate re-authenticate action. HubSpot access tokens refresh
> automatically in the background; if that stops working (for example the portal
> revoked Zenskar's access, or a scope changed), disconnecting and reconnecting is
> the only recovery path.

***

## Reference

### Field Mapping columns

Every group under **Field Mapping** is a table with three columns.

| Column | Meaning |
| :- | :- |
| **Zenskar field** | The Zenskar field being set. Fixed list per tab, see below. |
| **HubSpot field** | The HubSpot property it reads from or writes to. Selected from the connected portal's properties. |
| **Default value** | Optional. Applied when the HubSpot field is empty. |

### Customers tab

| Section | Details |
| :- | :- |
| Customer Sync | Toggle. While enabled, a customer syncs whenever its HubSpot company is created or updated. |
| Sync Direction | Import only, Export only, or Import & Export. No option is pre-selected. |
| Select Zenskar Entity | The business entity for this connection. |
| Field Mapping → General Fields | Connector default: Customer Name, Address (Line 1, Line 2, City, State, Postal Code, Country), Phone. Email and Tax ID are not in the default map; add them as field-mapping overrides if you need them. |
| Field Mapping → Business Entities | One field / operator / value rule per Zenskar business entity. An imported company that satisfies a rule is assigned to that entity. |

The Customers tab has no Sync Condition Filters section.

### Products tab

| Section | Details |
| :- | :- |
| Product Sync | Toggle. |
| Sync Direction | Import only, Export only, or Import & Export. No option is pre-selected. |
| Sync Condition Filters | Optional. Each condition is a field / operator / value; multiple conditions are combined with AND. |
| Field Mapping → General Fields | Name, Description, SKU. |
| Field Mapping → Pricing Models | Click + Add Pricing Model, select a model, and map its rows. Available: Percent Pricing, Per Unit Pricing, Matrix Pricing, Package Pricing, Flat Fee. |
| Field Mapping → Features | Click + Add Feature, select a feature, and map its rows. Available: Discount, Tax, Free Units, Commitment, Grants, Consumptions. |

### Contracts tab

| Section | Details |
| :- | :- |
| Contract Sync | Toggle. |
| Sync Direction | Import only, Export only, or Import & Export. No option is pre-selected. |
| Sync Condition Filters | Optional. A deal is imported only when every condition is satisfied. |
| Associated Deal Sync | When enabled, a HubSpot deal that is associated with another deal which already produced a Zenskar contract is linked to that contract instead of creating a new one. The field / operator / value rules identify which associated deals this applies to. |
| Field Mapping → General Fields | Name, Description, Start Date, End Date, Currency, Anchor Date. |
| Field Mapping → Features | Click + Add Feature, select a feature, and map its rows. Available: Discount, Tax, Commitment, Consumptions, Payment Terms, Service Fees. |

Each pricing model or feature added brings its own set of mapping rows.

### Condition operators

Used in Sync Condition Filters, Business Entity rules, and Associated Deal Sync
rules.

| Operator | Meaning |
| :- | :- |
| Equals | The field value matches the given value. |
| Not Equals | The field value does not match the given value. |
| Greater Than or Equal | The field value is greater than or equal to the given value. |
| Less Than or Equal | The field value is less than or equal to the given value. |
| Contains | The field value contains the given text. |
| Does Not Contain | The field value does not contain the given text. |
| In List | The field value is one of the values in the given list. |
| Not In List | The field value is not in the given list. |

### Connection statuses

Shown on each connection card on the **Connections** tab.

| Status | Meaning |
| :- | :- |
| Pending Configuration | The connection is authorized but not fully set up. Either no business entity is assigned, or the configuration has not been saved. |
| Configured | The connection has a business entity and a saved configuration. Objects sync according to their per-tab settings. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.