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

# Setup Requirements

> Prerequisites, OAuth scopes, and provisioning for the WeGive HubSpot integration

## Prerequisites

* A HubSpot account where you have **Super Admin** or equivalent permissions. These are required to authorize the OAuth scopes below and to let WeGive create custom properties and pipelines.
* A WeGive organization with the HubSpot integration enabled. Contact [support@wegive.com](mailto:support@wegive.com) if the integration is not visible in your dashboard.

<Note>
  HubSpot's free tier supports a single Deal pipeline. On the free tier, one-time and recurring donations share one pipeline. See [Integration Nuances](/external/onboarding/hubspot/integration-nuances#pipeline-limit-on-hubspot-free-tier). Paid tiers get separate pipelines.
</Note>

## OAuth scopes

When you authorize WeGive, HubSpot requests the following scopes. All are required.

| Scope | Why WeGive needs it |
| - | - |
| `oauth` | Base OAuth grant |
| `crm.objects.contacts.read` | Pull HubSpot Contacts into WeGive as supporters |
| `crm.objects.contacts.write` | Push WeGive supporters to HubSpot |
| `crm.objects.companies.read` | Pull HubSpot Companies into WeGive as companies and households |
| `crm.objects.companies.write` | Push WeGive companies and households to HubSpot |
| `crm.objects.deals.read` | Pull Deal records to sync transaction state |
| `crm.objects.deals.write` | Push transactions and recurring donations as Deals |
| `crm.schemas.contacts.read` | Read the Contact property schema |
| `crm.schemas.contacts.write` | Create the custom `wegive_*` properties on Contacts |
| `crm.schemas.companies.read` | Read the Company property schema |
| `crm.schemas.companies.write` | Create the custom `wegive_*` properties on Companies |
| `crm.schemas.deals.read` | Read the Deal property schema |
| `crm.schemas.deals.write` | Create the custom `wegive_*` properties on Deals |

<Note>
  HubSpot also requests 5 **optional** scopes during authorization — `crm.objects.line_items.read`/`write`, `crm.schemas.line_items.read`, and `crm.objects.products.read`/`write`. These back fund-allocation line-item sync (most installs never need it) and can be declined without blocking the connection; a portal that declines them simply never syncs fund allocations as deal line items.
</Note>

## Connect the integration

<Steps>
  <Step title="Connect">
    In the WeGive dashboard, go to **Settings > Integrations > HubSpot** and click **Connect**.
  </Step>

  <Step title="Authorize">
    You are redirected to HubSpot. Sign in, choose the HubSpot account to connect, and approve the scopes listed above. HubSpot redirects you back to WeGive. Your refresh token is stored encrypted and rotated automatically.
  </Step>

  <Step title="Provision">
    On the integration settings page, click **Provision**. This one-time step creates everything WeGive needs in your HubSpot account (see below).
  </Step>

  <Step title="Enable">
    Turn on the **Enabled** toggle. WeGive begins pushing existing supporters, households, transactions, and recurring plans on the next sync.
  </Step>
</Steps>

## What provisioning creates

| Item | Detail |
| - | - |
| Custom properties | `wegive_*` properties on Contacts, Companies, and Deals. See [Data Mapping](/external/onboarding/hubspot/data-mapping/overview). |
| Donations pipeline | Deal pipeline with stages Success, Attempted, and Failed. |
| Recurring Donations pipeline | Deal pipeline with stages Active, Paused, Cancelled, Ended, In Arrears, Missing, Archived, Expiring Soon, and Ending Soon. Paid tiers only. |
| Soft Credits pipeline | Deal pipeline with a single "Soft Credits" stage, used for soft-credit gift attribution. On free accounts, this stage is added to the account's shared default pipeline instead of a dedicated one. |
| Household association label | Contact to Company. |
| Recurring Plan association label | Deal to Deal, linking generated gifts to their parent recurring deal. |

## Re-running provisioning

Provisioning is safe to re-run. WeGive only creates properties and pipelines that do not already exist and never deletes anything in HubSpot. Re-provision after upgrading from a free HubSpot tier to a paid tier to get the separate Recurring Donations pipeline.

## First sync

Initial sync of an existing supporter base takes several minutes to several hours depending on volume. WeGive batches API calls (100 records per request) and respects HubSpot's rate limits. Progress is visible in the integration log in the dashboard.

## Next steps

1. [Configuration Options](/external/onboarding/hubspot/configuration-options)
2. [Data Mapping Overview](/external/onboarding/hubspot/data-mapping/overview)
3. [Integration Nuances](/external/onboarding/hubspot/integration-nuances)


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