> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/crm-integrations/salesforce.md). # Salesforce ## Overview The Salesforce integration connects Younium to Salesforce CRM at the **legal entity** level using the Younium managed package in Salesforce. It synchronises accounts from Salesforce into Younium, exports subscription orders, order charges, and invoices to Salesforce custom objects, and maintains product catalogue and price book entries in Salesforce for quoting workflows. Authentication uses the Salesforce username–password OAuth flow, with separate token endpoints for production and sandbox orgs. The integration detects installed package capabilities at runtime and omits or includes fields when corresponding Salesforce columns are not present. *** ## Change Log The current package version is **0.28**. Each release is listed newest first. | Version | Date | Changes | | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0.28 | 2026-09-09 | Product sync processes one legal entity at a time and only clears withdrawn products after a complete, error-free run, so a product can no longer be deactivated by two syncs overlapping. Incremental syncs track their position per legal entity. | | 0.27 | 2026-07-24 | Corrects the opportunity fields used to identify a record, and fixes a fault in General Settings. | | 0.26 | 2026-07-03 | Reworked settings page. Line-building methods are available to other packages in the org. | | 0.25 | 2026-05-29 | The billing day offset on an order is carried in both directions. | | 0.24 | 2026-05-29 | Order discounts can be changed. Discounts and tiered prices are written as records, so they can be reported on. Account sync runs when an account name changes. **View in Younium** buttons added to Account, Order and Invoice. | | 0.23 | 2026-05-25 | Fixes rated charges that carry no price details. | | 0.22 | 2026-04-27 | Product bundles supported. Metrics are fetched from Younium. Products and charge plans past their end-of-new-sales date are no longer offered. | | 0.21 | 2026-04-22 | Adds milestones and an optional full-width charge form. Fixes currency field mapping, a division by zero on quantity, and measured product quantity. | | 0.20 | 2026-02-27 | Quote can be used instead of Opportunity as the object behind the product selector and the sync to Younium, with its own field mappings. Change quotes can be created from an opportunity directly. | | 0.19 | 2026-02-23 | Optional automatic price book on opportunity insert. Invoices are filtered as they are requested rather than afterwards. | | 0.18 | 2026-02-18 | Fixes an error when custom-mapping a date field from Younium to Salesforce. | | 0.17 | 2026-02-16 | Fixes duplicate rows in the product selector. Adds a back-to-overview button and an expanding sidebar. Order discount editing no longer depends on the charge table's edit mode. | | 0.16 | 2026-02-11 | Adds a re-sync button for change opportunities, product-level control over whether tiers can be edited, and all products in the flow summary. | | 0.13 | 2026-01-29 | Renewal opportunities can be generated automatically. Invoice PDF download. Effective end date on new opportunities. Cancelled invoices are no longer synchronised. More decimal places for currency fields in the product editor. | | 0.11 | 2025-11-24 | Fixes order discounts that have no start date. | | 0.10 | 2025-11-21 | Order discounts supported. Legal entity shown on sync jobs. More detailed logging for subscription, product and order sync. | | 0.9 | 2025-10-16 | Fixes rounding when setting discounts in the product selector. Product sync errors name the row that failed. | | 0.8 | 2025-10-08 | Products can be excluded from the product selector per price book entry. | | 0.7 | 2025-09-29 | Quantity is hidden and fixed at one for usage and measured charges. Country code is synchronised instead of free text. Several product selector ordering and layout fixes. | | 0.6 | 2025-09-10 | Cancelling an order defaults the cancel date to the order end date. The billing address is used for both addresses when the shipping address is empty. | | 0.5 | 2025-08-27 | The invoice account is synchronised to the opportunity's Invoice Account field. More checks when creating change opportunities from an order. | | 0.4 | 2025-08-26 | Fixes duplicate layout metadata in subscriber orgs. | | 0.3.0.1 | 2025-08-21 | Order cancellation. Sales Order opportunity type. Sync jobs listed in settings. **Younium User** permission set. Contract value metrics on opportunity products. Layout item editing. | | 0.1.0.3 | 2025-08-21 | First release. | *** ## Authentication Younium connects to Salesforce as a dedicated integration user rather than as the person setting it up, so the connection does not break when that person leaves or changes their password. You provide the connected app's consumer key and secret from Salesforce, and the username, password and security token of the integration user. Younium signs in with them when you activate, and if Salesforce accepts them the connection is marked valid and the org it connected to is remembered. If Salesforce rejects them, activation fails and no connection is made. From then on Younium signs in again as needed, before each synchronisation, so the connection does not need renewing by hand. It does need attention when the integration user's password or security token changes in Salesforce: the stored credentials stop working, and you re-enter them in the integration settings. > **Note on the integration user:** Because the connection is that user's sign-in, anything that invalidates it in Salesforce — a password change, a reset security token, a deactivated user — stops synchronisation until the credentials are re-entered in Younium. A dedicated integration user, rather than a person's own login, keeps that from happening unannounced. *** ## Sandbox vs. Production One setting decides whether Younium connects to your Salesforce production org or a sandbox, and it is chosen when you connect. Everything else about the connection is the same in both. Sandbox credentials are not production credentials: a sandbox has its own connected app and its own integration user, so switching between the two means re-entering the credentials, not just changing the flag. *** ## Activation Activation is the moment Younium first signs in with the credentials you entered. If Salesforce accepts them, they are stored, the connection is marked valid, and Younium creates the integration custom fields it needs on your Younium records (see below). Confirming the connection includes a short redirect through Salesforce to authorise the connected app. Each authorisation attempt is single-use: completing the same authorisation link twice, or returning to Salesforce on a stale or bookmarked link, fails and the connection must be started again from Younium. Nothing is installed or deployed into Salesforce when you connect. The objects and fields the integration expects must already exist in your org, which is what the managed package provides. **Installing or upgrading the package.** An administrator installs the current version from: ``` https://login.salesforce.com/packaging/installPackage.apexp?p0=04tQy000000ZNTBIA4 ``` The same link upgrades an org that already has an earlier version. *** ## Deactivation Disconnecting removes the stored credentials and the record of when each synchronisation last ran, and synchronisation stops. Nothing is removed on either side beyond that. The Salesforce package objects stay in your org, and the Younium custom fields holding Salesforce identifiers stay on your records — no longer maintained, but preserving what was synchronised. *** ## Save and Setup Saving the settings stores any changed credentials and re-creates the Younium custom fields the integration needs. It does not test the credentials — saving a wrong one leaves the existing connection working until it next signs in, so activate again after changing credentials rather than assuming a successful save means a working connection. Account import can also create Younium custom fields dynamically from Salesforce **Younium Settings** custom metadata (`Younium__Younium_setting__mdt`) mapped to account fields. *** ## Custom Fields Created by the Integration Fields use the pattern `integrationSalesforce` + description (spaces/punctuation removed). Do not rename or delete integration-owned fields. | Entity | Field description | Resolved name | Type / notes | | -------------------- | ------------------------------------ | ------------------------------------------------------- | -------------------------------------- | | Account | Salesforce Id | `integrationSalesforceSalesforceId` | Text — Salesforce Account Id | | Order | Salesforce Order Id | `integrationSalesforceSalesforceOrderId` | Text — parent order in SF | | Order product charge | Salesforce Order Id | `integrationSalesforceSalesforceOrderId` | Text — charge record Id in SF | | Order product charge | Salesforce Product Id | `integrationSalesforceSalesforceProductId` | Text | | Charge (catalogue) | Salesforce Product Id | `integrationSalesforceSalesforceProductId` | Text | | Product | Pricebook Category | `integrationSalesforcePricebookCategory` | Text | | Product | Exclude product from Salesforce sync | `integrationSalesforceExcludeproductfromSalesforcesync` | Checkbox | | Charge detail | PricebookEntry Id | `integrationSalesforcePricebookEntryId` | Text | | Order | Opportunity Id | `integrationSalesforceOpportunityId` | Text | | Invoice | Salesforce Invoice Id | `integrationSalesforceSalesforceInvoiceId` | Text | | Order product charge | Pricebook | `integrationSalesforcePricebook` | List — price book names synced from SF | Additional account custom fields may be created at import time from Salesforce settings metadata (one per mapped Younium field name). *** ## Eligibility and Scope ### Legal entity Each legal entity has its own Salesforce connection. Salesforce accounts must have `Younium__Legal_entity__r.Younium__ID__c` equal to the connected Younium legal entity ID **and** `Younium__Y_Synch_to_Younium__c = TRUE` to be included in batch account import. ### Account import Incremental skip: if the account already exists in Younium and Salesforce `LastModifiedDate` (UTC) is **before** `LastAccountSynchronize`, the record is skipped. ### Subscription export | Rule | Detail | | -------------- | -------------------------------------------------------------------------------------------------------------------------- | | Account link | Order `AccountId` must belong to an account with non-empty `integrationSalesforceSalesforceId` | | Order version | `IsLastVersion` | | Order type | Subscription | | Order status | Active, Cancelled, or Deleted | | Incremental | If `LastSubscriptionSynchronize` set: order `Modified` or order custom field `Modified` since last sync | | Deleted orders | CMRR and TCV export as **0**; ACV also 0 when package field exists | | Charge export | Only for orders successfully exported in the same run; charges modified since last sync (or parent order/product modified) | Charges without a parent Salesforce order Id are skipped and logged; order and charge `Modified` timestamps may be bumped for retry on the next sync. ### Invoice export | Rule | Detail | | ----------- | ---------------------------------------------------------------------------- | | Account | Invoice account must be Salesforce-linked | | Status | Posted or Settled only | | Incremental | `Modified` or invoice custom field `Modified` since `LastInvoiceSynchronize` | Invoices without a resolvable Salesforce account Id for the account group are skipped with a warning. ### Product sync Products on the current legal entity only. Excluded when `Exclude product from Salesforce sync` custom field is explicitly `false` is **not** the rule — export **includes** products where exclude field is `false` **or** empty; products with exclude = `true` are omitted. Shared products on parent legal entity are excluded from child LE sync by `LegalEntityId` filter. ### Jobs Two exports run on a schedule, each no more often than every 30 minutes: | Job | Minimum repeat (minutes) | | ------------------------------------------ | ------------------------ | | Export Younium subscriptions to Salesforce | 30 | | Export invoices to Salesforce | 30 | Account synchronisation is not scheduled. It runs when you start it from the Salesforce integration settings. *** ## Field Mapping — Account Import (Salesforce → Younium) ### Standard and package fields | Younium Field | Salesforce Account field | | ------------------------------------------- | ---------------------------------------------------------------------------------------- | | `Account.Name` | `Name` | | `Account.Description` | `Description` | | `Account.Domain` | `Website` | | `Account.InvoiceEmailAddress` | `Younium__Y_Invoice_email__c` | | `Account.InvoiceEmailCcAddresses` | `Younium__Y_Invoice_CC_Email__c` | | `Account.ExternalCRMId` | Salesforce `Id` | | `Account.ElectronicInvoiceAddress` | `Younium__Electronic_Invoice_Address__c` | | `Account.InvoiceDeliveryMethod` | `Younium__Invoice_Delivery_Method__c` (enum parse) | | `Account.ExternalERPId` | `Younium__ERP_Id__c` (when package supports field) | | `Account.AccountsReceivableId` | Resolved from `Younium__Accounts_receivable_account__c` → financial account **Code** | | `Account.TaxTemplateId` | Resolved from `Younium__Tax_template__c` → tax template **Name** | | `Account.DefaultPaymentTermId` | Resolved from `Younium__Payment_terms__c` → payment term **Name** | | `Account.InvoiceTemplateId` | Resolved from `Younium__Younium_invoice_template__c` → document template **Description** | | Custom: `integrationSalesforceSalesforceId` | `Id` | ### Billing address → invoice address | Younium address field | Salesforce field | | --------------------- | ----------------------------------------------- | | `Street` / `Street2` | `BillingStreet` (split on `\r` into two lines) | | `City` | `BillingCity` | | `Zip` | `BillingPostalCode` | | `State` | `BillingStateCode` | | `CountryId` | `BillingCountryCode` → two-letter country match | ### Shipping address → delivery address | Younium address field | Salesforce field | | --------------------- | --------------------- | | `Street` / `Street2` | `ShippingStreet` | | `City` | `ShippingCity` | | `Zip` | `ShippingPostalCode` | | `State` | `ShippingStateCode` | | `CountryId` | `ShippingCountryCode` | ### Settings metadata-driven mappings Rows from `Younium__Younium_setting__mdt` where `Younium__Younium_object__c = 'Account'` map `Younium__Salesforce_field__c` → `Younium__Younium_field__c` on the account custom field. List fields resolve Salesforce keys through custom field list items. ### Single-record import API Webhook-style import accepts JSON with fields such as `Name`, `YourRef`, `OurRef`, `TaxRegNr`, `OrgNr`, `InvoiceEmail`, `InvoiceEmailCCs`, nested `CustomFields`, and address fragments — used for Salesforce triggers and manual sync actions. *** ## Field Mapping — Subscription Export (Younium → Salesforce) Object: **`Younium__Y_Younium_Order__c`**. Create uses composite tree `v34.0`; update uses composite sobjects `v44.0`. | Younium Field | Salesforce field | | -------------------------- | -------------------------------------------------------- | | `Order.IsAutoRenewed` | `Younium__Auto_renewal__c` | | `Order.CMRR.Amount` | `Younium__CMRR__c` (0 if order Deleted) | | `Order.EffectiveEndDate` | `Younium__Effective_end_date__c` (`yyyy-MM-dd`) | | `Order.EffectiveStartDate` | `Younium__Effective_start_date__c` | | `Order.OrderNumber` | `Younium__Order_number__c` | | `Order.RenewalTerm` | `Younium__Renewal_term_months__c` | | `Order.TermType` | `Younium__Subscription_type__c` | | `Order.TCV.Amount` | `Younium__TCV__c` (0 if Deleted) | | `Order.Id` | `Younium__Younium_Order_ID__c` | | `Order.Version` | `Younium__Y_Order_version__c` | | `Order.Currency.Code` | `CurrencyIsoCode` | | `Order.Status` | `Younium__Y_Order_status__c` | | `Order.ACV.Amount` | `Younium__ACV__c` (when package has field; 0 if Deleted) | | `Order.CancellationDate` | `Younium__Y_Cancellation_date__c` (Cancelled only) | | Invoice account SF Id | `Younium__Invoice_Account__c` (when package has field) | | `Account` (SF Id) | `Younium__Account__c` on create only | | Existing SF order Id | `id` on update | Configurable mappings from Salesforce custom metadata entity type **Order** can add fields via `MapCustomFields`. After create, Younium stores returned Salesforce Id in `integrationSalesforceSalesforceOrderId` on the order. > **Note on recovery:** Batch SOQL recovery can repopulate missing order Ids before create to avoid duplicate Salesforce orders. *** ## Field Mapping — Order Charge Export (Younium → Salesforce) Object: **`Younium__Younium_Order_charge__c`**. | Younium Field | Salesforce field | | --------------------------------------- | -------------------------------------------------------------- | | `OrderProductCharge.BillingPeriod` | `Younium__Billing_period__c` | | `OrderProductCharge.Model` | `Younium__Charge_model__c` | | `OrderProductCharge.ChargeType` | `Younium__Charge_type__c` | | `OrderProductCharge.CMRR.Amount` | `Younium__CMRR__c` | | `OrderProductCharge.PricePeriod` | `Younium__Price_period__c` | | `OrderProductCharge.Quantity` | `Younium__Quantity__c` | | `OrderProductCharge.TCV.Amount` | `Younium__TCV__c` | | `UnitOfMeasure.DisplayName` | `Younium__UOM__c` | | `OrderProductCharge.Id` | `Younium__Younium_order_charge_ID__c` | | `OrderProductCharge.CMRR.CurrencyCode` | `CurrencyIsoCode` | | `OrderProductCharge.ChargeNumber` | `Younium__Order_charge_number__c` | | `OrderProduct.ProductNumber` | `Younium__Order_product_number__c` | | `OrderProductCharge.Name` | `Younium__Younium_Charge_Name__c` and `Name` (truncated to 80) | | `OrderProductCharge.Remarks` | `Younium__Remarks__c` (max 255) | | `OrderProductCharge.EffectiveEndDate` | `Younium__Effective_end_date__c` | | `OrderProductCharge.EffectiveStartDate` | `Younium__Effective_start_date__c` | | `OrderProductCharge.ACV.Amount` | `Younium__ACV__c` (when package has field) | | Active detail price | `Younium__Price__c` (when package has field) | | Product SF Id custom field | `Younium__SF_Prod_ID__c` | | Parent order SF Id | `Younium__Younium_order__c` on create | | Existing charge SF Id | `id` on update | Volume/tiered pricing rows export to **`Younium__Y_VolumeTiered_Pricing__c`** when the package is installed, linked by Salesforce charge Id and tier metadata. *** ## Field Mapping — Invoice Export (Younium → Salesforce) Object: **`Younium__Y_Younium_Invoices__c`**. | Younium Field | Salesforce field | | ------------------------------- | -------------------------------------------------------------------------- | | `Invoice.Subtotal.CurrencyCode` | `Younium__Currency_code__c` and `CurrencyIsoCode` | | `Invoice.DueDate` | `Younium__Due_date__c` | | `Invoice.InvoiceDate` | `Younium__Invoice_date__c` | | `Invoice.InvoiceNumber` | `Younium__Invoice_number__c` | | `Invoice.Status` | `Younium__Status__c` | | `Invoice.Subtotal.Amount` | `Younium__Subtotal_amount__c` | | `Invoice.Tax.Amount` | `Younium__Tax_amount__c` | | `Invoice.TotalAmount.Amount` | `Younium__Total_amount__c` | | `Invoice.Id` | `Younium__Younium_ID__c` | | Settled amount | `Younium__Settled_amount__c` (full total if Settled, else `SettledAmount`) | | `Invoice.ExternalERPId` | `Younium__ExternalERPId__c` (when package has field) | | Account SF Id | `Younium__Account__c` on create | | Existing SF invoice Id | `id` on update | Posted invoices persist Salesforce Id to `integrationSalesforceSalesforceInvoiceId` per successful composite chunk. *** ## Field Mapping — Product and Price Book Sync (Younium → Salesforce) Products export to **Product2** with Younium package fields including product name, charge name, charge type, billing/price periods, charge plan, tiered/volume flags, and legal entity reference. Price books and **PricebookEntry** records are created or updated per charge detail; Younium stores `integrationSalesforcePricebookEntryId` on charge details and maintains the **Pricebook** list on order product charges. Exact Salesforce field API names for product sync are defined on the Product2 and price book objects in the managed package; runtime queries validate column existence before export. *** ## Account Import (batch) **Trigger:** **Synchronize accounts** operation (refreshes token, SOQL query). **Query filter:** `Younium__Y_Synch_to_Younium__c = TRUE` AND legal entity ID match. **Outcome:** Creates or updates Younium accounts; sets `LastAccountSynchronize` to **UTC now** (must remain UTC for `LastModifiedDate` comparison). Logs new and updated counts. *** ## Export Subscriptions (batch job) **Trigger:** **Export Younium subscriptions to Salesforce** (min repeat 30 minutes). **Outcome:** Creates/updates `Younium__Y_Younium_Order__c`, then exports eligible charges. Sets `LastSubscriptionSynchronize` to local `DateTime.Now`, counts new/updated subscriptions. Failed orders/charges may have `Modified` bumped for retry. *** ## Export Invoices (batch job) **Trigger:** Salesforce invoice export job. **Outcome:** Per-account composite create/update; sets `LastInvoiceSynchronize`, new/updated counts. Skipped or failed invoices are marked for retry via modified timestamp bump. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.younium.com/crm-integrations/salesforce.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.