How do I configure the HubSpot integration with Luminous, including authorization steps, data flow triggers, and field mapping?

Overview

Luminous connects to HubSpot via OAuth. Once authorized, data flows in both directions: HubSpot contacts and companies sync into Luminous as Contacts and Business Accounts, while Luminous invoices sync back to HubSpot deals. Sales reps can also create and edit Luminous invoices directly inside any HubSpot deal through the Luminous CRM Card.

Step 1 — Create a HubSpot App Integration Account

Click your name in the top-right corner and choose Settings / Integrations.
Click + Add Integration to open the integration catalog.
Click the HubSpot tile.
Give the connection a name, then click Save and authorize. This saves the record and sends you to HubSpot to authorize. The account has empty credentials until you finish OAuth authorization.

Step 2 — Authorize via OAuth

Open the HubSpot integration account you just created.
Click Connect HubSpot. Luminous will open a new browser tab or window pointing to HubSpot's OAuth consent screen.
Log in to HubSpot (if prompted) and click Connect app to grant the following permissions:
- Read/write Contacts, Companies, and Deals
- Read/write Line Items
- E-commerce
After you approve, HubSpot redirects back to Luminous. Luminous stores the access and refresh tokens automatically and records your HubSpot Portal ID on your account.
Back in the integration account form, click Test Credentials to confirm the connection is live. A success banner confirms the credentials are valid and the CRM Card redirect is properly configured.

Tip: If Test Credentials warns about a missing Portal ID or primary domain, contact Luminous support — these are account-level settings that need to be set once during onboarding.

Step 3 — Configure Settings

After authorization, two checkbox options and four JSON mapping fields appear in the integration account form:

Setting	What it does
Create Items in HubSpot	When checked, Luminous automatically creates HubSpot Product records for invoice line items that don't already have a match.
Sync Line Items	When checked, invoice line items (quantity, unit price, product name) are pushed to HubSpot deal line items every time the invoice is updated in Luminous.
Status Mapping (JSON)	Maps Luminous invoice/order statuses to your HubSpot deal stage IDs.
Deal Field Mapping (JSON)	Maps Luminous invoice fields to HubSpot deal properties.
Business Account Mappings (JSON)	Maps HubSpot company properties to Luminous Business Account fields.
Shipping Address Mappings (JSON)	Maps HubSpot company properties to the default shipping address on the Luminous Business Account.

Default Mapping Values

Copy the blocks below into the corresponding fields. Advanced users can extend them with additional HubSpot property names on the left and Luminous field names on the right.

Status Mapping

The keys inside "invoice" are Luminous order/payment statuses; the values are your HubSpot pipeline stage IDs. Replace the example IDs with the real stage IDs from your HubSpot account.

{
  "invoice": {
    "DRAFT": "<your-draft-stage-id>",
    "ACTIVE": "<your-active-stage-id>",
    "Paid": "<your-paid-stage-id>",
    "COMPLETED": "<your-completed-stage-id>",
    "Partially_paid": "<your-partially-paid-stage-id>",
    "inProduction": "<your-in-production-stage-id>"
  }
}

To use a custom deal stage field (instead of the default dealstage), add "dealStageField": "your_field_name" at the top level of the JSON object.

Deal Field Mapping

Left side = Luminous invoice field name; right side = HubSpot deal property name.

{
  "total_amount": "amount",
  "id": "description",
  "total_units": "total_quantity"
}

Business Account Mappings

Left side = HubSpot company property name; right side = Luminous Business Account field name. The mapping includes both HubSpot standard address fields and dedicated billing-address fields — if a billing-specific field is present it overwrites the standard one.

{
  "companyId": "hubspot_company_id",
  "name": "business_name",
  "address": "business_address",
  "address2": "business_address_line_2",
  "city": "business_city",
  "state": "business_state",
  "zip": "business_zip",
  "country": "business_country",
  "billing_address": "business_address",
  "billing_address_2": "business_address_line_2",
  "billing_city": "business_city",
  "billing_state_region": "business_state",
  "billing_postal_code": "business_zip",
  "billing_country_region": "business_country",
  "phone": "phone",
  "ein__c": "fein"
}

Country codes: If HubSpot sends a full country name (more than 2 characters), Luminous will default the value to US. Make sure your HubSpot company records use ISO 2-letter country codes.

Shipping Address Mappings

Left side = HubSpot company property name; right side = Luminous shipping address field name.

{
  "address": "address",
  "address2": "address_line_2",
  "city": "city",
  "state": "state",
  "zip": "postal_code",
  "country": "country",
  "shipping_address": "address",
  "shipping_address_2": "address_line_2",
  "shipping_city": "city",
  "shipping_state_region": "state",
  "shipping_postal_code": "postal_code",
  "shipping_country_region": "country",
  "name": "company_name"
}

As with Business Account Mappings, shipping-specific fields (e.g. shipping_address) override the standard fields when both are present in HubSpot.

Data Flow Triggers

HubSpot → Luminous (real-time webhooks)

HubSpot sends a webhook to Luminous whenever:

HubSpot event	What Luminous does
Contact created	Creates or updates a Contact record in Luminous
Contact property changed	Updates the matching field on the existing Contact
Company created	Creates or updates a Business Account in Luminous
Company property changed	Updates the matching field on the existing Business Account and its default shipping address

A special case: when the num_associated_contacts property changes on a Company, Luminous re-syncs all HubSpot-linked contacts to that Business Account and sets the first contact as the primary billable contact if none exists.

HubSpot → Luminous (manual full sync)

From the integration account page, you can trigger a Sync Data job. This queues a background job that pages through all HubSpot contacts and companies and updates (or optionally creates) matching Luminous records. Use this for initial data migration or periodic reconciliation.

Luminous → HubSpot (invoice sync)

Whenever a Luminous Invoice that has a linked HubSpot Deal ID is created or updated, Luminous automatically queues a background job that:

Updates the deal's amount and any other fields in your Deal Field Mapping.
Updates the deal stage based on the invoice's current order/payment status and your Status Mapping.
- If the invoice has associated production purchase orders and is not yet Completed, the deal moves to the inProduction stage.
If Sync Line Items is enabled, creates or updates HubSpot line items for every invoice line.

The job retries up to 5 times (every 10 seconds) if HubSpot is temporarily unavailable.

Luminous CRM Card (in HubSpot)

Once authorized, a Luminous card appears inside HubSpot deals. From there, sales reps can:

Create a new Luminous invoice linked directly to the deal.
View or edit an existing invoice without leaving HubSpot.

Assigned Sales Rep — Current Limitation

There is currently no supported mapping between the HubSpot deal or contact owner and the Luminous Assigned Sales Rep field.

Luminous stores Assigned Sales Rep as a curated-text custom dropdown on the Business Account — it is not a native user-account relationship. The HubSpot integration's Business Account Mapping only supports Luminous core fields (name, address, phone, FEIN, and the internal HubSpot company ID). There is no mapping key today that routes a HubSpot owner ID or owner name into that dropdown.

If you need owner-to-rep mapping, please contact Luminous support to discuss a custom field mapping approach for your account.

Troubleshooting

Symptom	What to check
Test Credentials returns a warning about CRM card redirects	Contact support — the primary domain or Portal ID needs to be configured on your account.
Companies/contacts not syncing from HubSpot	Confirm the webhook subscription is active in your HubSpot app settings and that the integration account is authorized.
Deal stage not updating when invoice status changes	Verify your Status Mapping JSON contains an entry for the relevant status and that the stage IDs match your HubSpot pipeline.
Country field saved as "US" unexpectedly	HubSpot is sending a full country name instead of a 2-letter ISO code. Update your HubSpot company records to use ISO codes.