HubSpot
Synchronisation scope
Accounts (from HubSpot companies)
HubSpot → Younium
Scheduled, as the Import HubSpot accounts job, or on demand from the integration settings
Subscriptions (orders and order charges)
Younium → HubSpot
Scheduled, as the Export Orders to Hubspot job, or on demand from the integration settings
Deals to orders and change orders
HubSpot → Younium
On demand, from the Younium card on a HubSpot deal
Deals to quotes
HubSpot → Younium
On demand, from the Younium quote card on a HubSpot deal
Deal amount and line items
Younium → HubSpot
When charges are added, changed or removed in the Younium product selector on a deal, or when a deal is updated from its linked Younium quote
Change deals for existing subscriptions
Younium → HubSpot
On demand, from the Younium card on a HubSpot company
Account, order and quote details
Younium → HubSpot
When a company or deal is opened in HubSpot, shown as Younium cards on the record
Paywall contact-sales leads (contacts, companies and deals)
Younium → HubSpot
When a visitor submits a contact-sales request on a Paywall
Not in scope: invoices, products, payments.
Overview
The HubSpot integration connects Younium subscription management to HubSpot CRM at the legal entity level. Sales and customer success teams work from HubSpot companies and deals while Younium remains the system of record for subscriptions, billing, and revenue metrics.
The integration supports account import from HubSpot companies, deal-driven order and quote creation, embedded CRM cards on HubSpot records, and export of subscription orders and charges to HubSpot custom objects. OAuth authorises each legal entity to a HubSpot portal; a private access token is additionally required for custom object export and schema operations.
Authentication
You connect Younium to HubSpot by authorising it from HubSpot itself. Saving the integration settings produces an authorisation link; following it takes you to HubSpot, where you sign in and approve the access Younium asks for — the companies, deals, contacts, line items, custom objects, owners and timeline entries it reads and writes. HubSpot returns you to Younium and the connection is live.
The connection is made per legal entity, and each legal entity connects to one HubSpot account. Younium keeps the connection alive on its own, renewing its access before each import and export, so nobody has to reauthorise it on a schedule. The integration settings show whether the connection is currently valid.
Exporting orders to HubSpot custom objects needs one thing the authorisation does not provide: a private app token, which you generate in HubSpot and paste into the integration settings. Without it, order export stops and tells you the token is missing. Everything else — companies, contacts, deals and line items — works on the authorised connection alone.
Activation
Approving the connection in HubSpot is what activates the integration. From that point Younium can read and write the HubSpot records covered by the integration.
Activation creates nothing on either side. The HubSpot properties and custom object schemas the integration needs are created when they are first needed — during property sync, a deal workflow, or an export — not at the moment you connect. Younium's own integration custom fields on Account, Order and Quote are created the same way (see Custom fields).
Deactivation
Disconnecting clears everything Younium held for the legal entity: the authorisation, the private app token, and the record of when each sync last ran. Imports and exports stop.
Nothing is removed in HubSpot. The properties, custom objects and records the integration created stay exactly as they are — they are simply no longer maintained from Younium.
Save and Setup
Saving settings updates connection and synchronisation options without re-running OAuth:
PrivateAccessToken
PAT for custom object APIs
AccountCustomFieldsMapping
Comma-separated HubSpot company property names mapped to Younium account custom fields (legacy; spaces stripped on save)
DealCustomFieldsMapping
Comma-separated deal properties for quote mapping (legacy; spaces stripped on save)
SyncToInvoiceAccount
When true, export and account resolution use invoice account instead of order account
InvoiceAccountAssociationLabel
HubSpot association label used to pick invoice company when multiple companies are on a deal
UpdateAddresses
When true, account import updates invoice address from HubSpot when country is present
OnlySynchNewAccounts
When true, batch import only creates new accounts; existing linked accounts are not updated
HubspotDealAmountValue
Controls which deal amount field drives quote/deal amount updates
HideUpdateDealAmount
Hides deal amount update behaviour in UI when configured
LastAccountSynchronize
Writable from settings; used as incremental filter for company search
On first save, if HubspotAccessAuthorizationUrl is null, Younium builds the OAuth authorisation URL (client ID, redirect URI, scopes, state).
Custom Fields Created by the Integration
Integration-owned custom fields use the naming pattern integrationHubspot + description (spaces and punctuation removed). Do not rename or delete these fields.
Account
Company Id
integrationHubspotCompanyId
HubSpot company ID
Order
Hubspot Deal Id
integrationHubspotHubspotDealId
HubSpot deal ID
Quote
Hubspot Deal Id
integrationHubspotHubspotDealId
HubSpot deal ID
Quote
Hubspot Deal
integrationHubspotHubspotDeal
Link field to deal URL (created when quote is created from deal)
Eligibility and Scope
Legal entity
Connection, settings, CRM cards, and synchronisation run per legal entity. Company and deal properties include younium_legal_entity (format: {legalEntityId},{tenantId}). Import batch processing skips companies whose younium_legal_entity does not match the integration’s legal entity. Post-import, companies with empty legal entity receive the current legal entity value written back to HubSpot.
Account import (batch)
HubSpot company search uses OR filter groups:
lifecyclestage=customerand (optional)hs_lastmodifieddate≥ last syncyounium_account_idhas property and (optional) same modified-date filter
After fetch, companies are filtered to those with valid younium_legal_entity (matches scope or null). Within each batch, companies with a non-matching legal entity ID are skipped.
CreateAccount only materialises or updates Younium data when HubSpot lifecyclestage is customer, the call is deal-driven (dealAccount), or the existing Younium record is a Prospect. Non-customer companies without those conditions are ignored.
When OnlySynchNewAccounts is true, existing accounts matched by HubSpot company ID are returned without field updates (except deal-driven import).
Account resolution after a HubSpot company merge
Before creating a new account, Younium first looks for an existing account whose Company Id custom field already holds the HubSpot company's id. When no account holds it, Younium checks two further signals on the HubSpot company before falling back to creating a new account — this applies both to the batch import job and to account resolution for deal-driven order, change order, and quote creation:
Merged companies (
hs_merged_object_ids): if HubSpot recorded the company as the survivor of a merge, Younium looks for an account whose Company Id matches any of the ids the company was merged from.Exactly one match — that account is used, and its Company Id is overwritten with the current HubSpot company id, so future syncs match directly.
More than one match — the accounts are duplicates left over from separate merges and Younium cannot pick one automatically (see below).
younium_account_idproperty: if the company carries this property and it resolves to an existing account, that account is used and its Company Id is stamped with the current HubSpot company id — unless the account already has a different Company Id set, meaning it is already linked to another HubSpot company (see below).
If neither signal resolves to a single account, Younium creates a new account as it would if the company had never been seen before.
Note on the correction being permanent: the Company Id update from either signal is saved immediately, so it is not lost on a later run where
OnlySynchNewAccountsis enabled (which otherwise leaves existing accounts untouched).
The batch import job and deal-driven creation handle an unresolved case (multiple merge matches, or a younium_account_id account already linked elsewhere) differently:
Batch import job
The company is skipped for that run — no account is created or updated. The integration log records each candidate account so the duplicates can be reconciled and merged, or the Company Id fields corrected, before the next run.
Deal-driven creation (create order, create change order, create quote from deal)
The flow must still return an account, so Younium creates a new account rather than blocking the deal. The integration log records the same mismatch, so the resulting duplicate can be identified and merged afterwards.
Subscription export
Account link
Account must have non-empty integrationHubspotCompanyId
Order type
OrderType.Subscription
Versions
Last-version order and last-version order product charge
Order status
Active, Cancelled, or Deleted
Account resolution
SyncToInvoiceAccount: match on InvoiceAccountId; otherwise AccountId
Incremental
If LastExportOrders set: charge or order ModifiedWithDependencies must be newer
Deleted orders
Skipped for create if no existing HubSpot order; updates still apply when ID exists
Charge number
Charges with null ChargeNumber are skipped
Jobs
Import HubSpot accounts
None defined in job definition
Export Orders to Hubspot
None defined in job definition
Deal company resolution
Creating an order from a deal, creating a change order from a deal, creating a quote from a deal, and the deal's quote/change-order card all resolve the deal's associated company the same way. A deal with a single associated company uses that company directly. A deal with several associated companies resolves the account through HubSpot's association metadata: the company carrying the Primary association, or the one carrying the InvoiceAccountAssociationLabel association label when set, determines the linked Younium account (and, separately, the invoice account). If that lookup does not return a company, Younium falls back to the first company HubSpot lists for the deal.
The quote/change-order card requires at least one company associated with the deal, and a Younium account linked to the resolved company. If either is missing, the card shows an error instead of rendering with no account.
Once a company is resolved, the Younium account for it is found using the same matching described in Account resolution after a HubSpot company merge, including the merge and younium_account_id fallbacks.
Custom Field Mapping
Configurable field-to-field mappings (integration custom mappings) pair a HubSpot property with a Younium field, and apply to the account, quote, order, and order product charge entities. The deprecated AccountCustomFieldsMapping and DealCustomFieldsMapping settings work the same way for account and quote fields.
A mapping can target most Younium field types, including whole numbers such as Notice Period, Term, and Renewal Term. Calculated fields, fields that reference another record (single or multiple), image fields, ID fields, and currency-amount fields cannot be used as mapping targets.
Note on custom field names: Younium matches an incoming custom field to its configured field without regard to letter case, and always stores the value under the field's exact configured name — so a value mapped to
regionand one mapped toRegionupdate the same Younium field rather than creating two.
Note on blank source values: An integration custom mapping only ever sets a Younium field when the HubSpot source property has a value. If the property is empty, blank, or missing, the mapping is skipped and the existing Younium value is left as it is — clearing a mapped HubSpot property never clears the corresponding Younium field or custom field.
Field Mapping — Account Import (HubSpot → Younium)
Standard company properties map as follows. Configurable integration custom mappings (entity account) and deprecated AccountCustomFieldsMapping can add or override fields.
Account.Name
name
Account.Domain
domain
Account.Description
description
Account.InvoiceEmailAddress
younium_invoice_email
Account.OrganizationNumber
younium_org_nr
Account.TaxRegistrationNumber
younium_tax_reg_nr
Custom: integrationHubspotCompanyId
Company id (HubSpot object ID)
Address.Name (invoice)
younium_invoice_address_name (or default “Invoice address”)
Address.Street
address
Address.Street2
address2
Address.City
city
Address.Zip
zip
Address.State
state (normalised for US/Canada)
Address.CountryId
country (matched to Younium country; US/CA aliases supported)
Invoice address create/update runs only when country is non-empty and (UpdateAddresses is true or no invoice address exists yet).
A blank HubSpot value for any of the standard company properties above (name, domain, description, younium_org_nr, younium_tax_reg_nr, younium_invoice_email) is skipped: the existing Younium field keeps its current value rather than being cleared.
List-type custom fields from deprecated mapping resolve HubSpot values to list Key or Value before storing.
Owner sub-properties in custom mappings trigger a fetch of HubSpot owners for the mapped owner ID.
Field Mapping — Account Write-Back (Younium → HubSpot)
After successful import/update, Younium batch-updates HubSpot companies (max 99 per async batch) for properties that are empty in HubSpot:
younium_account_id
Account.Id
younium_account_number
Account.AccountNumber
younium_legal_entity
{LegalEntityId},{TenantId} from settings
younium_org_nr
Account.OrganizationNumber
younium_tax_reg_nr
Account.TaxRegistrationNumber
younium_invoice_email
Account.InvoiceEmailAddress
Field Mapping — Subscription Export (Younium → HubSpot Custom Objects)
Custom object schemas: younium_order (order), younium_order_charge (charge). Younium creates schemas and properties if missing and associates orders to companies (0-2) and charges to parent orders.
Dates sent to HubSpot use Unix milliseconds at start of day (UTC).
Younium Order (younium_order)
Order.OrderNumber
order_number
Order.Description
order_description
Order.EffectiveStartDate
order_effective_start_date
Order.EffectiveEndDate
order_effective_end_date (if set)
Order.OrderDate
order_date (if set)
Order.IsAutoRenewed
order_is_auto_renewed
Order.CMRR.Amount
order_cmrr
Order.ACV.Amount
order_acv
Order.TCV.Amount
order_tcv
Order.RenewalTerm
order_renewal_term
Order.Term
order_initial_term
Order.Currency.Code
order_currency
Order.Version
order_version
Order.Status
order_status
Order.TermType
order_term_type
Order.NoticePeriod
order_notice_period
Order.NoticePeriodDate
order_notice_period_date (if set)
PaymentTerm.Name
order_payment_term
Order.Id
order_id
Custom: integrationHubspotHubspotDealId
hubspot_deal_id
Association
HubSpot company ID from account custom field
Create vs update: match existing HubSpot order by order_number.
Younium Order Charge (younium_order_charge)
OrderProductCharge.ChargeNumber
charge_number
OrderProductCharge.Name
charge_description
OrderProductCharge.CMRR.Amount
charge_cmrr
OrderProductCharge.TCV.Amount
charge_tcv
OrderProductCharge.ACV.Amount
charge_acv
OrderProductCharge.ACV.CurrencyCode
charge_currency
OrderProductCharge.Quantity
charge_quantity
OrderProduct.Order.ProductNumber
product_number
OrderProductCharge.ChargeType
charge_type
OrderProductCharge.Version
charge_version
OrderProductCharge.Model
charge_model
OrderProductCharge.PricePeriod
charge_price_period
OrderProductCharge.BillingPeriod
charge_billing_period
UnitOfMeasure.DisplayName
charge_uom
Charge plan name
charge_chargeplan_name
OrderProductCharge.EndOn
charge_end_on
OrderProductCharge.StartOn
charge_start_on
OrderProduct.Name
charge_product_name
OrderProductCharge.Remarks
charge_remarks
OrderProductCharge.ExternalCRMId
external_crm_id
Active detail list price
list_price_amount
Active detail price
price_amount
Active detail line discount
discount_amount
Active detail price (PPu)
charge_ppu
OrderProductCharge.EffectiveEndDate
charge_effective_end_date (if set)
OrderProductCharge.EffectiveStartDate
charge_effective_start_date (if set)
Batch create/update uses chunks of 50 on crm/v3/objects/{chargeSchemeId}/batch/create or update.
Field Mapping — Create Order from Deal (HubSpot → Younium)
Order.Description
dealname
Order.OrderDate
closedate
Order.Remarks
younium_remarks
Order.IsAutoRenewed
younium_auto_renewal
Order.RenewalTerm
younium_renewal_term
Order.Term
younium_initial_term
Order.EffectiveStartDate
younium_order_effective_start_date (required)
Order.EffectiveEndDate
Start date + term months − 1 day
Order.Status
younium_order_status (parsed to order status)
Currency
hs_line_item_currency_code (all line items must share one currency)
Custom: deal ID
Deal associatedObjectId → integrationHubspotHubspotDealId
Account / invoice account
Primary and labelled invoice companies on deal
Charges
Built from deal line items (see line item table)
Deal line item → order product charge
Product name
name
Line item ID
hs_object_id (stored on charge)
HubSpot product ID
hs_product_id
Charge number
younium_order_charge
Charge type
younium_charge_type
Charge model
younium_charge_model
List price / price / quantity
hs_pre_discount_amount, amount, quantity
Currency
hs_line_item_currency_code
Start/end options
younium_start_on, younium_end_on
Effective dates
younium_charge_effective_start_date, younium_charge_effective_end_date (sv-SE date parse)
Billing
younium_billing_period, recurringbillingfrequency
Discount
discount
Line status
younium_line_item_status
HubSpot pricing models (flat, volume, stairstep, graduated) map to Younium charge models with tier validation.
Note on stock product quantity: For a new one-off charge on a stock product, the line item's
quantitysets Ordered quantity (and Remaining quantity) rather than Quantity — a stock one-off charge tracks delivery through those fields instead, the same rule the API applies when creating or changing a subscription directly in Younium. A line item with no quantity leaves the product's default quantity in place. Quantity on a recurring charge, and on any charge that is not on a stock product, still maps to Quantity as shown above.
Note on multiple companies: See Deal company resolution under Eligibility and Scope — the same resolution rule applies here.
Field Mapping — Create Quote from Deal (Currency)
Quote currency
deal_currency_code (when set)
When the deal has a currency, it must exist as a currency in Younium, and the quote takes it. Younium rejects the deal otherwise. For a change quote on an existing order, the deal currency must also match the order's currency; a mismatch is rejected.
When the deal has no currency, Younium skips these checks and the quote keeps the currency it would otherwise get: the account's currency for a new quote, or the order's currency for a change quote.
Note on orders: Creating an order from a deal still requires a deal currency. A deal without one is rejected with an error asking for a currency to be set on the deal.
Field Mapping — Create Change Order from Deal
Uses the same deal property sources as create order, plus:
Change effective date
younium_order_effective_change_date (required)
Existing order
younium_order_number
Deal already synced flag
younium_deal_synched
Line items are matched to existing charges by younium_order_charge on last-version charges. A line item that matches an existing charge updates it in place and never changes that charge's Ordered quantity or Remaining quantity. A line item with no match creates a new charge, which follows the same stock product quantity rule as create order: its quantity sets Ordered quantity rather than Quantity when the new charge is a one-off on a stock product.
Note on blank deal properties: Unlike creating a new order, a change order updates an order that already has values.
dealname,younium_remarks, andclosedateonly overwrite the order's description, remarks, and order date when the deal property is not blank; a property that has been cleared in HubSpot leaves the existing order value untouched. The same applies toyounium_renewal_term,younium_initial_term, andyounium_auto_renewal— a cleared HubSpot number or checkbox property is treated as no change rather than failing the change order.
Changing younium_initial_term also moves the order's effective end date to match the new term, the same way changing the term does on a change order created directly in Younium — so the term and the end date never drift out of sync. Tenants with Enable specific effective end date switched on are the exception: HubSpot has no property for a specific end date, so the term cannot be changed this way for those tenants and must be changed directly in Younium instead.
Field Mapping — CRM Cards (Younium → HubSpot display)
Company card (linked account)
Account name (link)
Account name + deep link
Account number
Account.AccountNumber
TCV / ACV / CMRR / EMRR
Aggregated from active last-version orders
Account balance
Outstanding amount on the account's posted invoices (invoice total less settlements), in the base currency. Settled invoices are not counted
Last charged
Invoice date of the latest posted or settled invoice; "No charges" when there is none
The card matches the HubSpot company to a Younium account by its stamped Company Id custom field first; if no account carries that ID, it falls back to matching on the account referenced by younium_account_id. If more than one account is stamped with the same company ID, the oldest one is shown.
Note on Account balance: The card shows the same figure as the account's invoice balance in Younium. Only posted invoices count, so a fully paid invoice contributes zero. This matters for foreign-currency invoices: the invoice and its payment are converted to the base currency at different exchange rates, and counting the settled invoice would leave the exchange rate difference in the balance.
Deal — order card
Actions depend on changeType, orderNumber, and younium_deal_synched: create order, create change order, or open iframe for existing order.
Deal — quote card
Shows quote metrics when a quote exists for the deal; otherwise empty placeholders with create-quote action.
Account Import (batch job)
Trigger: scheduled job Import HubSpot accounts (refreshes token, then ImportAccounts).
Flow:
Search companies (filters above), paginate 100 per page (max 1000 pages), 300 ms delay between pages.
Process in batches of 500 companies.
Match existing account by
integrationHubspotCompanyId; if none matches, resolve the account across a HubSpot merge oryounium_account_idbefore falling back to a new account (see Account resolution after a HubSpot company merge under Eligibility and Scope).Create or update via
CreateAccount; apply integration custom mappings.Write back empty Younium properties to HubSpot (batch async update, chunks of 99).
Set
LastAccountSynchronizeto UTC now; log new/updated counts.
Failures on individual companies are logged; batch failures log and continue with next batch.
Export Subscriptions (batch job)
Trigger: scheduled job Export Orders to Hubspot.
Flow:
Refresh OAuth token; require PAT.
Resolve or create
younium_orderandyounium_order_chargeschemas and associations.Load existing HubSpot orders (by
order_number) and charges (bycharge_number).Select changed last-version subscription charges for linked accounts.
Process in batches of 100 subscriptions; export order then charges.
Set
LastExportOrders,LastExportOrdersCount; log created/updated counts.
Deal and Quote Actions (on demand)
Create order from deal
CRM card / API from deal
New subscription order with line items
Create change order from deal
CRM card when change type set
Change order on existing order number
Create quote from deal
Quote card
New quote linked to deal
Update deal from quote
Quote workflow
Patches HubSpot deal amount/properties
Create/update/delete line item
Product selector
HubSpot line items for deal charges
Create new deal from Hubspot
Change subscription request
New HubSpot deal from order
Quote currency when creating a quote from a deal
The quote takes the deal's currency (deal_currency_code) when the deal has one. The currency must exist in Younium, and when the quote is a change quote for an existing order it must match that order's currency; otherwise the quote is not created and an error explains why.
When the deal has no currency, Younium skips these checks and the quote keeps the currency it would otherwise have: the account's currency for a new quote, or the order's currency for a change quote.
Note: Creating an order from a deal still requires a currency on the deal's line items. A deal without a currency is rejected before anything is created in Younium or updated in HubSpot.
HubSpot Property Provisioning
On demand, Younium can create HubSpot properties for products, deals, companies, and line items (CreateYouniumProductProperties, CreateYouniumDealProperties, CreateYouniumCompanyProperties, CreateYouniumLineItemProperties, SynchronizeCustomProperties). Property names follow the younium_* convention used in mappings above.
ClearLastDateSync clears LastExportOrders when entity name orders is passed.
Last updated
Was this helpful?