HubSpot Integration - Common Issues & Solutions

Issue: Legal Entity Values Not in Allowed Options

Error Message: "Property values were not valid: [Legal Entity ID] was not one of the allowed options"

Cause: The Legal Entity ID and Tenant ID combination in HubSpot doesn't match what's configured in Younium, or the property options haven't been properly set up.

Solution:

  1. In HubSpot, go to Settings → Data Management → Company Properties → Search for "Younium Legal entity"
  2. Edit the property and verify the Internal Value matches the format: [Legal Entity ID],[Tenant ID]
  3. To get the correct Legal Entity ID from Younium:
    • Navigate to Reports → New Report → Choose Base Data Set → Select Legal Entity
    • Select fields: ID + Name
    • Copy the Legal Entity ID for the entity you want to use
  4. The format should be: 403ccbed-1994-49ab-892d-08da3428e333,eff9ccc4-2kkc-6969-a8c5-08da339239d6 (This is an example, it may not match on exact length what you should have)
    • First part: Legal Entity ID (changes per entity)
    • Second part: Tenant ID (stays the same)
  5. Repeat the process for Deal properties: Settings → Data Management → Deal Properties → Younium Legal Entity

Prevention: After any Legal Entity changes in Younium, re-export properties from Younium to HubSpot via Settings → Integrations → HubSpot → Export Younium Properties.

Issue: Missing Required HubSpot Properties (younium_org_nr, younium_legal_entity)

Symptom: Integration fails with "Property not found" or fields don't sync properly.

Solution:

  1. In Younium, navigate to Settings → Enabled Integrations → HubSpot
  2. Click "Export Younium Properties" (or "Synchronize Younium properties to HubSpot")
  3. This creates all required custom properties in HubSpot automatically
  4. Regular maintenance: Re-export properties periodically as new fields and features are released

Required Properties:

  • Company level: younium_org_nr, younium_tax_reg_nr, younium_invoice_email, younium_legal_entity
  • Deal level: younium_legal_entity, younium_order_initial_term, younium_renewal_term, younium_auto_renewal, younium_order_effective_start_date

Issue: Property Field Type Mismatches

Symptom: Data doesn't sync or displays incorrectly between systems.

Solution: Ensure matching field types when creating custom mappings:

  • Younium Text → HubSpot Single-line text
  • Younium Number → HubSpot Number
  • Younium Checkbox → HubSpot Single checkbox
  • Younium Date → HubSpot Date picker
  • Younium List → HubSpot Dropdown select

For List Fields:

  • HubSpot's "Internal Value" must exactly match Younium's list item "Value"
  • HubSpot's "Label" can be different (for display purposes)
  • Example: If Younium has value "30_days", HubSpot Internal Value must be "30_days"

Issue: Deal Properties Missing Legal Entity and Tenant ID

Symptom: Cannot create quotes or orders from HubSpot deals.

Solution:

  1. Ensure BOTH Company and Deal have the "Younium Legal Entity" field populated
  2. The associated company MUST have a "Younium Legal Entity" value set
  3. The deal must also have its own "Younium Legal Entity" value
  4. Both values should match the same Legal Entity
  5. Make the field visible: Deal → View all properties → Search "Younium legal entity" → Add to view

Issue: Missing Company ID/HubSpot Record ID

Symptom: Account sync fails, or relationships between systems break.

Solution for Initial Setup:

  1. Add HubSpot Company Record ID to Younium Accounts:
    • Export products from HubSpot: Settings → Data Management → Products → Export to XLSX
    • Copy the "Record ID" from the export
    • In Younium: Navigate to the Account → Field: "Record ID (HubSpot)" or "Company ID (Younium)"
    • Best method: CSV import for bulk updates
  2. Add Younium Account ID to HubSpot:
    • Field mapping: Younium "Account ID" → HubSpot "Younium Account ID"
    • This is typically done via CSV update in HubSpot
    • After initial mapping, the scheduled sync job handles ongoing updates
  3. Set Up Scheduled Sync:
    • In Younium: Settings → Scheduled Jobs → "Synchronize HubSpot accounts"
    • This job keeps the relationship fields updated automatically

Issue: New Accounts Created Instead of Using Existing Ones

Symptom: Multiple customer records for the same company in Younium.

Cause: Missing relationship fields between HubSpot and Younium (Company ID or Account ID fields are empty).

Solution:

  1. Initial Account Mapping (Before Integration Use):
    • Map existing accounts as described in "Missing Company ID/HubSpot Record ID" above
    • This prevents duplicates for existing customers
  2. For Quote Creation:
    • Always ensure the HubSpot Company has the "Younium Legal Entity" field populated
    • If the company doesn't exist in Younium, it will be created as type "Prospect"
    • When converting a quote to order, the account type updates to "Customer"
  3. Prevention:
    • Run the scheduled job "Synchronize HubSpot accounts" regularly
    • This keeps the relationship fields updated and prevents duplicates

Issue: Merged Companies in HubSpot Create Duplicates in Younium

Symptom: After merging companies in HubSpot, a new account is created in Younium.

Cause: When companies merge in HubSpot, the Company ID (Record ID) changes. Younium sees the new Company ID and creates a new account.

Solution:

  1. Before Merging in HubSpot:
    • Note the Younium Account ID associated with the companies
    • Decide which account should be the primary in Younium
  2. After Merging:
    • The merged company in HubSpot will have a new Record ID
    • Update the Younium account with the new HubSpot Company ID
    • Manually merge or deactivate the duplicate account in Younium if one was created
  3. Prevention:
    • Merge accounts in Younium first, then update HubSpot
    • Or manually update the Company ID field in Younium after HubSpot merge

Issue: Multiple Accounts When HubSpot-Younium Relationship Fields Missing

Symptom: Quote exported to wrong HubSpot account, creating separate customer records.

Solution:

  1. Verify the HubSpot Deal is associated with the correct Company
  2. Check that the Company has:
    • "Younium Account ID" populated (if it's an existing customer)
    • "Younium Legal Entity" selected
    • "Company ID" in Younium matches the HubSpot Record ID
  3. If quote was created with wrong account:
    • Cannot easily move the quote to another account
    • May need to cancel and recreate with correct associations

Issue: "Convert to Order" Button Greyed Out

Cause: Product start dates are outside the quote date interval, or quote status is incorrect.

Solution:

  1. Check Product Dates:
    • All product effective start dates must be within or after the Order Effective Start Date
    • Product end dates must align with the quote/order period
    • If a product has a specific end date that's outside the order period, this will block conversion
  2. Check Quote Status:
    • Quote must NOT be set to "Closed Won" before conversion
    • Convert the quote first, then update the deal status
  3. Date Alignment:
    • Ensure "Order Effective Start Date" on the deal is set correctly
    • Line item "Billing Start Date" should align with order dates
    • Use the "Younium Order Effective Start Date" field, not HubSpot's standard date fields

Issue: ACV Showing €0 or Disappearing

Cause: Product dates not correctly aligned with quote period.

Solution:

  1. Verify all products have valid date ranges
  2. Check that the quote period encompasses all product dates
  3. Ensure products have proper price periods set (Monthly, Quarterly, Annual)
  4. If using custom start dates on line items, verify they're within the order period

Issue: Quote Status Incorrectly Set to "Closed Won"

Symptom: Cannot convert quote, buttons greyed out.

Solution:

  1. Set the Deal/Quote status back to an appropriate pre-conversion status (e.g., "Contract Sent")
  2. Convert the quote to order in Younium
  3. THEN update the HubSpot Deal status to "Closed Won"
  4. The correct flow: Quote → Convert to Order → Update Deal Status

Issue: Confusion About When Younium Updates Deal Values

Question: When does Younium automatically update HubSpot deal amounts?

Answer: Younium does NOT automatically update deal amounts. Updates only occur when:

  1. Manual Button Click: User clicks "Update HubSpot Deal" button on the quote in Younium
  2. Widget Actions: User triggers an update through the HubSpot widget
  3. Scheduled Jobs: If configured, but this is NOT standard behavior

Solution to never be able to update it from Younium:

  1. In Younium: Settings → Integrations → HubSpot → Integration Settings
  2. Look for the "Update Deal Amount" toggle/setting
  3. If visible, disable it
  4. Train users NOT to click the "Update HubSpot Deal" button on quotes
  5. Consider hiding this button for users who don't need it

The integration is designed to be user-controlled, not automatic.

Issue: Missing CARR Metric Sync Option

Symptom: Only ACV, ARR, CMRR, MRR available but need CARR.

Solution: CARR = ACV in Younium:

  • CARR (Contracted Annual Recurring Revenue) is calculated as CMRR × 12
  • In Younium, this is represented as ACV (Annual Contract Value)
  • Select "ACV" in the integration settings to sync CARR values

Available Metrics for Deal Amount:

  • ACV (Annual Contract Value) = CARR = CMRR × 12
  • TCV (Total Contract Value) = Full contract value over entire term
  • CMRR (Contracted Monthly Recurring Revenue) = Monthly recurring amount
  • MRR (Monthly Recurring Revenue) = Actual monthly recurring

Custom Field Mapping: If you need CMRR in a separate HubSpot field (not just deal amount):

  • Currently not supported out-of-the-box
  • Would require custom development or API integration
  • Use roll-up properties on Orders (custom objects) for order-level metrics

Issue: Unable to Create Change Orders Due to Missing HubSpot Company ID

Error: "Something went wrong when creating deal" or unable to create upsell deal.

Cause: The Younium account doesn't have the HubSpot Company ID populated, or the relationship is broken.

Solution:

  1. In Younium, navigate to the Account
  2. Verify the "Record ID (HubSpot)" or "Company ID" field is populated
  3. If missing:
    • Get the Record ID from HubSpot (Company → About → Record ID, or export companies)
    • Add it to the Younium Account
  4. Run the "Synchronize HubSpot accounts" scheduled job to sync the relationship

Issue: Error Messages When Adding Change Orders

Error: Various error messages when clicking "Create Upsell Deal" or "Create Change Order".

Common Causes & Solutions:

  1. Legal Entity Error: See "Legal Entity Values Not in Allowed Options" above
  2. Missing Company ID: See above solution
  3. Missing Properties: Export properties from Younium to HubSpot
  4. Widget Loading Issues:
    • Try refreshing the HubSpot page
    • Disconnect and reconnect the integration
    • Clear browser cache

Issue: Missing Relationship Fields Block Change Orders

Symptom: Cannot create change order deals from HubSpot.

Solution: The change order creation requires several key fields:

  1. On the Younium Account:
    • HubSpot Company ID (Record ID) must be populated
  2. On the HubSpot Company:
    • Younium Account ID must be populated
    • Younium Legal Entity must be selected
  3. For the Deal:
    • Must have "Younium Change Type" = "Change Order"
    • Must have "Younium Order Number" populated
    • Must be associated with a company that has all required fields

To Create Change Order Deal:

  1. Navigate to Company in HubSpot
  2. Open Younium Account widget
  3. Select "Orders and Invoices"
  4. Click "Create upsell deal" icon on the relevant subscription
  5. This pre-populates the required fields automatically

Issue: Uncertainty About Sync Direction

Question: Is account sync bidirectional or one-way?

Answer: HubSpot → Younium ONLY (One Direction)

  • Company data flows FROM HubSpot TO Younium
  • Accounts are NOT synced back from Younium to HubSpot as part of standard integration
  • This is by design to maintain HubSpot as the source of truth for customer data

What Syncs FROM Younium to HubSpot:

  • Quote/Deal amounts (when manually triggered)
  • Orders (when using custom objects feature)
  • Order charges and metrics (with custom objects)

If you need Y → HS account sync:

  • Use Zapier, Make, or custom API integration
  • Or manually update as needed

Issue: Filtering Which Companies Sync

Question: Can we exclude certain HubSpot companies from syncing to Younium?

Answer: The sync looks for two criteria:

  1. Younium Legal Entity must be set on the company
  2. Lifecycle Stage must be "Customer"

To Exclude Companies:

  • Don't set a Younium Legal Entity on companies you want to exclude
  • Or keep them in a lifecycle stage other than "Customer"
  • Companies without both criteria won't sync to Younium

Issue: Field Naming Inconsistencies

Problem: Documentation shows integrationHubspotCompanyId vs hubspotCompanyId.

Clarification:

  • UI/API Field Name: Different naming conventions are used
  • What Matters: The actual HubSpot Record ID value
  • Mapping:
    • HubSpot Company "Record ID" → Younium Account "Company ID" or "Record ID (HubSpot)"
    • Both refer to the same identifier
    • Use the actual Record ID number (e.g., 12345678)

Issue: Scheduled Job "Synchronize HubSpot Accounts" Behavior Unclear

Question: What does this job do?

Answer: The job performs the following:

  1. Fetches companies from HubSpot that meet criteria:
    • Have "Younium Legal Entity" set
    • Have "Lifecycle Stage" = "Customer"
  2. Creates new accounts in Younium for companies not yet synced
  3. Updates existing accounts with changes from HubSpot
  4. Syncs the relationship fields (Younium Account ID back to HubSpot)

Setup:

  • In Younium: Settings → Scheduled Jobs
  • Look for "Synchronize HubSpot accounts"
  • Set frequency (daily, weekly, etc.)

Important: This only handles Company → Account sync. Deal → Quote/Order is triggered manually.

Issue: Quote Exported to Wrong HubSpot Account

Symptom: Quote created separate customer record instead of using existing.

Cause: Deal wasn't properly associated with the correct company, or company relationships weren't established.

Solution:

  1. Prevention: Always verify deal-company association before creating quote
  2. After Creation: Cannot easily move quote to another account
  3. Fix (Contact support before proceeding is recommended): May need to:
    • Cancel the incorrectly associated quote
    • Merge duplicate accounts in Younium
    • Recreate quote with correct associations

Issue: Company Lifecyclestage Field Requirements

Question: What lifecycle stages work with the integration?

Answer: For automatic account synchronization, the HubSpot company must have:

  • Lifecycle Stage = "Customer"

Other lifecycle stages (Lead, MQL, SQL, Opportunity, etc.) will NOT trigger automatic sync.

Manual Quote Creation:

  • You can create quotes from deals regardless of lifecycle stage
  • The account will be created in Younium as type "Prospect"
  • When converted to order, account type updates to "Customer"

Issue: Field Mapping Documentation Gaps

Problem: Unclear which HubSpot fields map to which Younium fields.

Standard Mappings:

Company → Account:

 
HubSpot Field          → Younium Field
Record ID              → Company ID
name                   → name
domain                 → domain
address                → street
address2               → street2
zip                    → zip
state                  → state
country                → country
city                   → city
description            → description
younium_org_nr         → orgNr
younium_tax_reg_nr     → taxRegNr
younium_invoice_email  → invoiceEmail

Deal → Order:

 
HubSpot Field                          → Younium Field
associatedCompanyId                    → Account
younium_auto_renewal                   → Order.IsAutoRenewed
younium_renewal_term                   → Order.RenewalTerm
younium_initial_term                   → Order.Term
dealname                               → Order.Description
closedate                              → Order.OrderDate
younium_order_effective_start_date     → Order.EffectiveStartDate

Deal → Quote (Delivery Address):

 
HubSpot Field                  → Younium Quote Field
younium_delivery_street1       → street
younium_delivery_street2       → street2
younium_delivery_zip           → zip
younium_delivery_state         → state
younium_delivery_country       → country
younium_delivery_county        → county
younium_delivery_city          → city
younium_legal_entity           → Legal Entity

Issue: Errors When Exporting Orders/Quotes from HubSpot to Younium

Common Errors:

  1. "Required field missing"
  2. "Property validation failed"
  3. "Invalid property value"

Solution Checklist:

  1. Required Deal Fields Must Be Populated:
    • Close date
    • Younium Auto Renewal
    • Younium Initial Term
    • Younium Legal Entity
    • Younium Order Effective Start Date
    • Younium Renewal Term
  2. Required Company Fields:
    • Younium Legal Entity (must match deal)
    • Country (for address)
  3. Line Items:
    • Must have valid Product ID mapping (External CRM ID)
    • Must have Billing Frequency (Monthly, Quarterly, or Annual)
    • Quantity (if quantity-based pricing)
  4. Common Mistakes:
    • Missing legal entity on company or deal
    • Dates in wrong format
    • Billing frequency not set or using unsupported values
    • Product not mapped (External CRM ID empty)

Issue: Property Validation Failures During Quote Creation

Error: "Property values were not valid" or "Field validation failed."

Solutions:

  1. Legal Entity Validation: See "Legal Entity Values Not in Allowed Options"
  2. Date Format Issues:
    • Use date pickers, not manual text entry
    • Ensure dates are in HubSpot's expected format
  3. Dropdown/Select Fields:
    • Values must exactly match configured options
    • Check for typos or extra spaces
  4. Required Fields:
    • All Younium required fields must have values
    • Can't leave mandatory fields empty

Issue: Currency Handling Issues

Problem: EUR/Currency orders not importing correctly, or currency mismatches.

Solution:

  1. Line Item Currency:
    • All line items on a deal must use the SAME currency
    • Field: hs_line_item_currency_code
    • This becomes the Order currency
  2. Multiple Currencies:
    • Cannot mix currencies on a single deal/order
    • Create separate deals for different currencies
  3. Validation:
    • Before converting to order, verify all line items show the same currency
    • Check that the currency is supported in your Younium legal entity

General Troubleshooting Steps

Step 1: Verify Connection

  1. In Younium: Settings → Enabled Integrations → HubSpot
  2. Check connection status (should show as connected)
  3. Try disconnecting and reconnecting if issues persist

Step 2: Export/Sync Properties

  1. In Younium: Settings → Integrations → HubSpot
  2. Click "Export Younium Properties" or "Synchronize Younium properties to HubSpot"
  3. This ensures all required fields exist in HubSpot
  4. Do this after any major changes or updates

Step 3: Check Scheduled Jobs

  1. In Younium: Settings → Scheduled Jobs
  2. Verify "Synchronize HubSpot accounts" is enabled and running
  3. Check last run time and any errors

Step 4: Verify Field Mappings

  1. Check custom field mappings in Younium integration settings
  2. Ensure field names match exactly (case-sensitive)
  3. For list fields, verify internal values match

Step 5: Test in Sandbox First

  1. Use HubSpot Sandbox and Younium Sandbox for testing
  2. Setup steps are identical to production
  3. Helps avoid issues in live environment
  4. Note: Legal Entity IDs may differ between prod and sandbox

Step 6: Check Widget Functionality

  1. If widgets aren't loading, check browser console for errors
  2. Try different browsers or incognito mode
  3. Clear browser cache
  4. Verify HubSpot app permissions

Sandbox to Production Considerations

Common Issue: Integration works in sandbox but fails in production.

Check:

  1. Legal Entity IDs are different(correct) between sandbox and production
  2. Re-export properties in production environment
  3. Re-configure Legal Entity dropdown options with production IDs
  4. Don't assume sandbox and production have matching Legal Entity IDs (they usually don't)

Exception: Some tenants have matching IDs due to database copies, but this is not standard.

Contact & Support

When to Contact Younium Support:

  • Widget not loading or showing errors
  • Integration connection failing
  • Scheduled jobs not running
  • Data sync issues that persist after troubleshooting
  • None of the above troubleshooting solved your issue

What to Provide:

  • Tenant/Environment name
  • Legal Entity name
  • Timestamp of when issue occurred
  • Screenshots of error messages
  • Steps to reproduce the issue
  • Affected HubSpot Company/Deal IDs or other relevant data (We do not per standard have access to your Hubspot environment)