> 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 Gen 2

> This article covers the Younium managed package that is installed and configured inside Salesforce. Customers on the Salesforce legacy integration, which pairs an earlier Younium package for Salesforce with a connection configured in Younium, use the [Salesforce Legacy Integration](/crm-integrations/salesforce-legacy.md).

## Synchronisation scope

| Synchronisation                                                                    | Direction            | When it runs                                                                                                                                                    |
| ---------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accounts                                                                           | Salesforce → Younium | When an account with **Sync With Younium** selected is created, or one of its synchronised fields changes; or on demand with **Sync to Younium** on the account |
| Opportunities and quotes, as new subscriptions, sales orders, changes and renewals | Salesforce → Younium | On demand, with **Sync to Younium** on the opportunity or quote                                                                                                 |
| Order cancellations                                                                | Salesforce → Younium | On demand, with **Cancel Order** on a Younium order in Salesforce                                                                                               |
| Contract value metrics (TCV, CMRR, ACV, OTF) on opportunity and quote products     | Younium → Salesforce | When products are saved in the product editor, when an opportunity's or quote's dates, term, type or order discounts change, or on demand with **Sync Metrics** |
| Legal entities                                                                     | Younium → Salesforce | On demand, with **Get legal entities** in the package settings                                                                                                  |
| Products, charge plans, charges and price book entries                             | Younium → Salesforce | On a schedule set in the package settings, or on demand from there                                                                                              |
| Subscriptions and sales orders                                                     | Younium → Salesforce | On a schedule set in the package settings, or on demand from there; and straight after an order is cancelled from Salesforce                                    |
| Invoices and invoice lines                                                         | Younium → Salesforce | On a schedule set in the package settings, or on demand from there                                                                                              |
| Invoice PDFs                                                                       | Younium → Salesforce | On demand, with **Download Invoice PDF** on a Younium invoice in Salesforce                                                                                     |

Not in scope: contacts, payments, usage, and account changes made in Younium (accounts only travel from Salesforce to Younium).

***

## Overview

The Salesforce integration is a managed package that an administrator installs in Salesforce. It connects the Salesforce org to Younium through the Younium API, and everything it does runs from inside Salesforce: the connection, the settings, the schedules and the buttons sales users press.

Sales teams quote Younium products from Salesforce. The package brings the Younium product catalogue into Salesforce as products and price book entries, gives opportunities and quotes a product editor that understands charge plans, tiers, order discounts and milestones, and sends a won opportunity or quote to Younium as a new subscription, a sales order, a change to an existing subscription or a renewal. Accounts are created and kept up to date in Younium from Salesforce.

In the other direction, the package brings subscriptions, sales orders and invoices back from Younium into Salesforce, together with contract value metrics for the deals being worked on, so account teams see what the customer has bought and been invoiced without leaving Salesforce. From a synchronised order a user can start a change or renewal opportunity, or cancel the order.

***

## Change Log

The current package version is **0.31**. Each release is listed newest first.

| Version | Date       | Changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0.31    | 2026-10-23 | The product editor has an **Insights** panel showing the deal's total CMRR, ACV, TCV and one-time fees, recalculated as soon as products are saved. Line-item prefill flows are set on a new **Plugins** tab in the package settings. The **Sync Jobs** tab is reworked into one view per synchronisation, with overall status, latest and next scheduled run, the last successful sync per legal entity, and a **Sync From Date** on each sync job. Field mapping changes are collected and saved together, and mappings are grouped by mapping type and searchable. Layout items and mappings show Salesforce fields by label. The searchable picklists in the product editor can be used with the keyboard. Creating a change opportunity or quote shows a loading indicator, and the orders due for renewal list says when no orders are due. |
| 0.30    | 2026-10-02 | Product sync no longer creates duplicate standard price book entries when an entry for the same product and currency already exists, for example one created by the earlier Younium package; the existing entry is updated instead. The **Younium Admin** and **Younium User** permission sets now grant access to product bundles, invoice PDF download and order discounts, and **Younium Admin** also grants access to layout item editing and renewal opportunity settings.                                                                                                                                                                                                                                                                                                                                                                   |
| 0.29    | 2026-09-30 | Fixes custom field mappings for whole-number fields sent from the opportunity to Younium, such as notice period, billing day offset, specific billing day, estimated usage, estimated quantity and ordered quantity. These now accept a Salesforce number field as the source. Recurring monthly amount keeps its decimals. Tiered price records are written only for charges that use the tiered or volume charge model.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

***

## Core Concepts

### Younium legal entity

Every exchange with Younium happens on behalf of one Younium legal entity. The package keeps a **Younium Legal Entity** record in Salesforce for each legal entity the connection can reach, and an account is tied to one of them through its **Legal Entity** field. The account's legal entity decides where its account, orders and invoices live in Younium, and a price book is tied to a legal entity through its **Younium Legal Entity** field.

### Catalogue in Salesforce

The Younium catalogue arrives in three layers. A Younium product becomes a **Younium Product** record, each of its charge plans a **Charge Plan** record, and each charge in a charge plan a standard Salesforce **Product**. The Salesforce product is what goes on an opportunity or a quote, so in Salesforce terms a line item is one Younium charge. Prices arrive as price book entries.

### Deal

The package treats an opportunity and a quote alike: either can carry Younium products and be sent to Younium. This article calls either one a deal where the difference does not matter. Two fields on the deal decide what it becomes in Younium: **Opportunity Type** (*New* or *Change*) and **Order Type** (*Subscription* or *Sales Order*).

### Younium order records

Subscriptions and sales orders synchronised from Younium appear as **Younium Order** records, each with its **Younium Order Product** and **Younium Order Product Charge** records. Invoices appear as **Younium Invoice** records with **Younium Invoice Line** records. They are read-only copies of Younium data, refreshed by synchronisation.

### Sync job

Every background synchronisation run is recorded as a **Sync Job** with its type, legal entity, status and counts. Errors from the run are recorded as **Log** records attached to it. The last error-free run of each type and legal entity is the starting point for the next incremental run.

### Field mapping

The package sends and reads a fixed set of fields by default. **Field mappings** extend or override that set: each one pairs a Salesforce field with a Younium field for one kind of record, in one direction. They are maintained on the **Field Mapping** tab of the package settings.

***

## Installing the package

An administrator installs the current version of the package, or upgrades an org that already has an earlier version, from:

```
/packaging/installPackage.apexp?p0=04tQy000000aYeHIAU
```

The package works with opportunities, quotes and products in more than one currency, so the org needs **multiple currencies**, **state and country/territory picklists** and **Quotes** enabled.

Installing adds a **Younium** app with tabs for **Settings**, accounts, opportunities, **Younium Legal Entity**, **Younium Product**, **Charge Plan**, products, **Younium Order**, **Sync Job** and **Log**. It also adds the record pages, buttons and fields described in this article.

### Permission sets

| Permission set    | Intended for   | What it allows                                                                                                                                                                                                            |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Younium Admin** | Administrators | Everything in **Younium User**, plus the **Settings** tab (connection, settings, sync jobs, field mappings, layout items and renewals), the sync job and log records, and editing of the records the package synchronises |
| **Younium User**  | Sales users    | The product editor, change order forms and the sync buttons on accounts, opportunities, quotes and orders. Synchronised catalogue, order and invoice records are read-only                                                |

Both permission sets give their holders the use of the connection to Younium, so a sales user's actions reach Younium without the user holding any Younium credentials of their own.

***

## Authentication

The connection belongs to the Salesforce org, not to a user. It is made with a client id and client secret for the Younium API, issued in Younium for the Younium tenant you are connecting. You need a set for each Younium environment you connect: one for the Younium sandbox and one for Younium production.

An administrator enters them on the **Authentication** tab of the package **Settings**. The tab shows two cards, **Sandbox Authentication Status** and **Production Authentication Status**. **Update Credentials** on a card opens **Enter Credentials**, where you paste the **Client Id** and **Client Secret** and save. The package stores them in Salesforce's encrypted credential store; nobody can read them back afterwards.

As soon as the credentials are saved the card tests them against Younium. It shows *Successfully authenticated to environment* when Younium accepts them, or *Not authenticated to environment* with Younium's reason beside it when it does not. The refresh icon on the card tests again at any time. Once a card is authenticated, **Get legal entities** appears on it (see [Legal entities and price books](#legal-entities-and-price-books)).

The connection has no expiry of its own. It stops working when the client id and secret are revoked or replaced in Younium; every exchange then fails with an authentication error until new credentials are entered. To change credentials, enter the new pair with **Update Credentials**; it replaces the stored pair.

***

## Sandbox vs. Production

The package holds sandbox and production credentials side by side, but only one environment is active at a time. By default, a Salesforce sandbox talks to the Younium sandbox and a Salesforce production org talks to Younium production, so a refreshed sandbox never sends test deals to live Younium. The **Environment Info** card on the **Authentication** tab shows the environment and region currently in use, and lets an administrator override both.

| Region | Environment | Younium API                          | Younium web app (used by **View in Younium**) |
| ------ | ----------- | ------------------------------------ | --------------------------------------------- |
| EU     | Production  | `https://api.younium.com`            | `https://eu.younium.com`                      |
| EU     | Sandbox     | `https://api.sandbox.younium.com`    | `https://eu.sandbox.younium.com`              |
| US     | Production  | `https://api.us.younium.com`         | `https://us.younium.com`                      |
| US     | Sandbox     | `https://api.sandbox.us.younium.com` | `https://us.sandbox.younium.com`              |

### Settings

| Setting                  | Description                                                                                                                                                                                                              | Default |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| **Environment Override** | *Default* follows the type of Salesforce org (sandbox to sandbox, production to production). *Production* or *Sandbox* forces one Younium environment regardless of org type. Saved with **Update Environment Override** | Default |
| **Region**               | The Younium region your tenant is hosted in: *EU* or *US*. Saved with **Update Environment Override**                                                                                                                    | EU      |

***

## Legal entities and price books

**Get legal entities** on an authenticated card fetches the legal entities the credentials can reach and creates or updates a **Younium Legal Entity** record for each, named after the legal entity. Run it again after a legal entity is added or renamed in Younium.

Every account that is to be synchronised needs its **Legal Entity** field set. Accounts without one cannot be sent to Younium, and opportunities on them cannot be synchronised.

Each legal entity needs a price book in Salesforce, linked through the price book's **Younium Legal Entity** field. If no price book is linked when products are first synchronised for a legal entity, the package creates an active one named *{legal entity name} Pricebook*. Change opportunities created from an order require exactly one active price book for the account's legal entity, and fail with a message if there is none or more than one.

### Settings

| Setting                          | Description                                                                                                                                       | Default |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Set Pricebook on Opportunity** | On the **General Settings** tab. When on, a new opportunity created without a price book gets the active price book of its account's legal entity | Off     |

***

## Field mapping

Field mappings extend what the package sends and reads. Each mapping has a **Mapping Type** (the pair of records it applies to), a **Salesforce Field** chosen from the fields of that Salesforce object, and a **Younium Field** typed as the field's name in the Younium API. Mappings are created with **Add Mapping** on the **Field Mapping** tab, edited from the same list, and switched between *Active* and *Inactive* with the status button on each mapping. Only active mappings are applied. The list is grouped by mapping type, can be narrowed to one type or searched, and shows each Salesforce field by its label with its API name below it. New, edited and toggled mappings are held as unsaved changes until **Save changes** applies them all at once; **Discard** drops them. The package ships with no mappings; everything below in the mapping tables is what it does by default.

| Mapping Type                                                                           | Direction            |
| -------------------------------------------------------------------------------------- | -------------------- |
| Salesforce Account (Account) to Younium Account                                        | Salesforce → Younium |
| Salesforce Opportunity (Opportunity) to Younium Order                                  | Salesforce → Younium |
| Salesforce Opportunity Product (OpportunityLineItem) to Younium Order Product          | Salesforce → Younium |
| Salesforce Opportunity Product (OpportunityLineItem) to Younium Order Product Charge   | Salesforce → Younium |
| Salesforce Quote (Quote) to Younium Order                                              | Salesforce → Younium |
| Salesforce Quote Product (QuoteLineItem) to Younium Order Product                      | Salesforce → Younium |
| Salesforce Quote Product (QuoteLineItem) to Younium Order Product Charge               | Salesforce → Younium |
| Younium Product to Salesforce Younium Product (ynm\_\_Product\_\_c)                    | Younium → Salesforce |
| Younium Charge Plan to Salesforce Charge Plan (ynm\_\_Charge\_Plan\_\_c)               | Younium → Salesforce |
| Younium Charge to Salesforce Product (Product2)                                        | Younium → Salesforce |
| Younium Price Detail to Salesforce Pricebook Entry (PricebookEntry)                    | Younium → Salesforce |
| Younium Order to Salesforce Younium Order (ynm\_\_Order\_\_c)                          | Younium → Salesforce |
| Younium Order Product to Salesforce Younium Order Product (ynm\_\_Order\_Product\_\_c) | Younium → Salesforce |
| Younium Order Product Charge to Salesforce Younium Order Product Charge                | Younium → Salesforce |
| Younium Invoice to Salesforce Invoice (ynm\_\_Invoice\_\_c)                            | Younium → Salesforce |
| Younium Invoice Line to Salesforce Invoice Line (ynm\_\_Invoice\_Line\_\_c)            | Younium → Salesforce |

How a mapping is applied depends on its direction.

**Salesforce → Younium.** When the Younium field names one of the standard fields the package already sends, the mapped Salesforce field replaces the default source. When it names a field the package does not send by default but the record has (the overridable fields are listed with each mapping table below), the mapped value fills it. Any other name is sent as a Younium custom field of that name. Younium field names are not case-sensitive. Within one mapping type a Younium field can be mapped only once.

**Younium → Salesforce.** The mapped Salesforce field is filled from the Younium field of that name. Nested values are reached with a dot, such as `cmrr.basecurrencyamount` or `account.name`, and a name that is not a standard field is looked up among the record's Younium custom fields. Dates and date-times are converted to the Salesforce field's type. Within one mapping type a Salesforce field can be mapped only once.

> **Note on blank values:** Fields that are blank in Salesforce are left out of what is sent, rather than sent empty. Clearing a value in Salesforce therefore does not clear it in Younium.

***

## Account synchronisation

### When it runs

An account is sent to Younium only when its **Sync With Younium** box is selected. It is then sent:

| Event                                                                                       | What happens                                              |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| The account is created with **Sync With Younium** selected                                  | It is sent in the background                              |
| The account is edited, and it has not yet reached Younium and its last attempt did not fail | It is sent in the background                              |
| The account is edited and one of its synchronised fields changes                            | It is sent in the background                              |
| A user presses **Sync to Younium** on the account and accepts the prompt                    | It is sent immediately, and the result is shown on screen |

The synchronised fields are **Sync With Younium**, **Account Name**, the account currency, the street, city, state, postal code and country of both the billing and the shipping address, and every Salesforce field in an active account field mapping.

If the account already has a Younium id, Younium's account is updated; otherwise a new Younium account is created in the account's legal entity and its id is stored on the account.

### What the account shows

| Salesforce field      | Content                                                                          |
| --------------------- | -------------------------------------------------------------------------------- |
| **Id** (`ynm__Id__c`) | The Younium account id, set when the account is first created in Younium         |
| **Sync Status**       | *Success* or *Error* for the latest attempt                                      |
| **Sync Message**      | *Successfully created*, *Successfully updated*, or the reason the attempt failed |
| **Latest Sync Date**  | When the latest attempt was made                                                 |

A failed attempt leaves the account unchanged in Younium. A failed account is not retried automatically on every edit; it is sent again when one of its synchronised fields changes or when **Sync to Younium** is pressed.

### Field mapping: account (Salesforce → Younium)

| Younium Field                                                    | Salesforce Field                                                                                          |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `name`                                                           | **Account Name** (`Name`)                                                                                 |
| `currency`                                                       | **Currency** (`CurrencyIsoCode`)                                                                          |
| `externalCRMId`                                                  | The Salesforce account id (always; cannot be mapped)                                                      |
| `defaultInvoiceAddress.street`                                   | First line of **Billing Street** (`BillingStreet`)                                                        |
| `defaultInvoiceAddress.street2`                                  | Remaining lines of **Billing Street** (`BillingStreet`)                                                   |
| `defaultInvoiceAddress.city`                                     | **Billing City** (`BillingCity`)                                                                          |
| `defaultInvoiceAddress.state` and `defaultInvoiceAddress.county` | **Billing State/Province** (`BillingState`)                                                               |
| `defaultInvoiceAddress.zip`                                      | **Billing Zip/Postal Code** (`BillingPostalCode`)                                                         |
| `defaultInvoiceAddress.country`                                  | **Billing Country Code** (`BillingCountryCode`), matched to the Younium country with that two-letter code |
| `defaultDeliveryAddress.*`                                       | The same fields of the shipping address                                                                   |

The invoice address arrives in Younium described as *Salesforce Billing Address* and the delivery address as *Salesforce Shipping Address*. When the account has no shipping address, the billing address is used for both.

Every field in the table except `externalCRMId` can be replaced through a mapping. These account fields are sent only when mapped: `ourReference`, `yourReference`, `invoiceEmailAddress`, `invoiceEmailCcAddresses`, `taxRegistrationNumber`, `organizationNumber`, `electronicInvoiceAddress`, `electronicInvoiceAddressScheme`, `reminderEmailAddress`, `inactive`, `defaultPaymentTerm`, `taxTemplate`, `accountsReceivable`, `invoiceTemplateId`, `externalERPId`, `invoiceDeliveryMethod` and `accountType`. Any other Younium field name is sent as an account custom field.

| Younium Field           | Accepted values                                                            |
| ----------------------- | -------------------------------------------------------------------------- |
| `invoiceDeliveryMethod` | Email, Print, ElectronicInvoice, ExternalPrint, AutomaticElectronicRouting |
| `accountType`           | Customer, Reseller, Subsidiary, Prospect, Other                            |

### Settings

| Setting                     | Description                                                                                                        | Default |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------- |
| **Account Sync Batch Size** | On the **General Settings** tab. How many accounts are sent per background batch when many accounts change at once | 50      |

***

## Product editor

Opportunity and quote record pages carry a product editor. It works with Younium charge plans rather than single products, and is the way Younium products are meant to be added to a deal.

### What the editor offers

The editor needs the deal to have a price book, and it can only be edited while the deal is open; a closed opportunity, or a quote whose status counts as closed, is shown read-only. **Edit** opens the deal for editing, and changes are written when the user saves.

**Add Product** offers the charges in the deal's price book and currency, grouped by product and charge plan. A charge is offered only when its price book entry is active and does not have **Exclude from Product Selector** selected, and only while neither its charge plan nor its product has passed its **End Of New Sales** date. Choosing a charge plan adds all of its charges as line items, each starting with:

| Line item field                                     | Starting value                                                                                                         |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Quantity**                                        | The charge's **Default Quantity**. Fixed at 1 for charges with the *Flat* model and for *Usage* and *Measured* charges |
| **List Price** and **Sales Price**                  | The price book entry's price                                                                                           |
| **Charge Type**, **Charge Model**, **Price Period** | From the charge                                                                                                        |
| **Start On** and **End On**                         | *Align to Order*                                                                                                       |
| **Change State**                                    | *New*                                                                                                                  |
| **Tier Editability**                                | From the charge's product                                                                                              |

**Discount (%)**, **Discount Amount** and **Sales Price** stay consistent as any one of them is edited: changing the discount recalculates the price, and changing the price recalculates the discount. For *Tiered* and *Volume* charges the tiers are edited in a tier editor, and the sales price and list price are calculated from the tiers and the quantity. The charge's **Tier Editability** decides what the user can change in the tiers:

| Tier Editability | Effect                                        |
| ---------------- | --------------------------------------------- |
| **Full**         | Tiers and prices can be changed               |
| **Only Price**   | Prices can be changed; tier boundaries cannot |
| **None**         | Tiers are read-only                           |

**Start On** and **End On** take *Align to Order*, *Specific Date* (with **Effective Start** or **Effective End**) or *Milestone* (with **Start Milestone** or **End Milestone**). Tiered and volume line items are also written out as **Pricing Tier** records so they can be reported on.

On a change deal, **Add Existing Charges** adds charges from the linked Younium order that are not on the deal yet.

### Bundles

**Add Bundle** offers bundle products. A bundle is a Salesforce product with **Bundle Product** selected, an active price book entry in the deal's price book and currency, and **Product Option** records that each point to a charge plan. Choosing a bundle adds a bundle line at quantity 1 and price 0, and the charges of the options the user picks below it. A bundle is offered only when at least one of its options has charges available in the price book. The bundle line itself is not sent to Younium; its charges are.

### Order discounts

When **Order Discounts Enabled** is on, a deal can carry order discounts. Each one has a **Percent**, a **Description**, **Start On** and **End On** (*Align to Order* or a specific **Start Date** or **End Date**), and applies to all charges or to charges the user specifies. A charge that an order discount refers to cannot be deleted from the deal until the discount no longer refers to it. Order discounts are also written out as **Order Discount** and **Order Discount Charge** records so they can be reported on.

### Milestones

When **Milestones Enabled** is on, a deal can carry milestones, each with a **Name**, **Description** and **Planned Date**. Charges can then start or end on a milestone, and the milestones are sent to Younium with the order.

### Prefilling line items with a flow

An administrator can have every new line item passed through a Salesforce flow before the user sees it, to prefill fields the package does not set. The flow is set on the **Plugins** tab of the package settings, under **Product Selector Plugins**, by entering its API name in **Flow API name** for **Opportunity Product**, **Quote Product** or both. The flow must be active, and receives the new line item in an input and output variable named `opportunityLineItem` or `quoteLineItem` and returns it changed. A blank **Flow API name** turns prefilling off for that object.

### Insights

The editor's side panel has two views, **Insights** and **Details**, and opens on **Insights**. **Insights** shows the deal's totals of **CMRR**, **ACV**, **TCV** and **One-time fees** in the deal's currency, summed from the [contract value metrics](#contract-value-metrics) of its saved line items. While products have unsaved changes it notes *Save your changes to recalculate the metrics.*; when they are saved, or a field that affects the metrics changes on the deal, the totals and each line item's metrics are recalculated and shown in place.

### Settings

| Setting                           | Description                                                                                                         | Default              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **Order Discounts Enabled**       | Shows order discounts in the product editor                                                                         | Off                  |
| **Milestones Enabled**            | Shows milestones and the milestone start and end fields on the charge form                                          | Off                  |
| **Full Width Charge Form**        | Shows the charge form in a full-width panel                                                                         | Off                  |
| **Exclude from Product Selector** | On a price book entry. Keeps that charge out of **Add Product** and **Add Bundle** for that price book and currency | Off                  |
| **Tier Editability**              | On a product. **Full**, **Only Price** or **None**, as described above                                              | Blank (full editing) |

The first three are on the **General Settings** tab, under **Product Features**.

***

## Sending opportunities and quotes to Younium

### What a deal becomes

| Opportunity Type                                                     | Order Type   | Created in Younium                                                                                                                  |
| -------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| New                                                                  | Subscription | A new subscription                                                                                                                  |
| New                                                                  | Sales Order  | A new sales order                                                                                                                   |
| Change                                                               | Subscription | A new version of the linked subscription, with the deal's changes                                                                   |
| Change, with **Is Renewal** selected and a **Renewal Term (Months)** | Subscription | The linked subscription renewed for the renewal term, then changed, in one step that is rolled back as a whole if either part fails |

A deal without an **Opportunity Type** cannot be sent.

### Sending

**Sync to Younium** on an opportunity or quote opens a summary of the charges to be sent and the fields that matter for the deal type, which the user can still correct:

| Deal                | Fields shown                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| New subscription    | **Effective Start Date**, **Initial Term**, and **Effective End Date** when there is no initial term                                                                     |
| Change subscription | **Is Renewal**, **Renewal Term (Months)** when it is a renewal, and **Effective Change Date** (set to the day after the order's effective end date when it is a renewal) |

The deal is saved, and the user then sends it. The result is shown on screen: either *Opportunity Sync Successful!* (or *Quote Sync Successful!*) or the reason Younium or the package refused it.

Before anything is sent, the package checks the deal:

| Check                                                                                                    | Message when it fails                      |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| The deal has not been sent before (its **Sync Date** is empty)                                           | *Opportunity was already synced at {date}* |
| The account has a legal entity                                                                           | *Account needs Legal Entity*               |
| The account has been synchronised to Younium                                                             | *Account has to be Synced with Younium*    |
| The deal has at least one line item for a Younium charge                                                 | *Missing opportunity line items*           |
| A new subscription has an **Effective Start Date**                                                       | *Missing effective start date*             |
| A new subscription has an **Initial Term** above 0, or both an effective start and an effective end date | Refused with an error                      |
| A change has an **Effective Change Date**                                                                | *Missing effective change date*            |

Line items for Salesforce products that are not Younium charges, such as bundle lines, are left out of what is sent.

### After sending

On success, the deal's **Sync Date** is set, which blocks a second send. For a new subscription or sales order the Younium order id is stored on the deal (**Younium Order Id** on an opportunity, **Younium Id** on a quote).

Unless a field mapping supplies the order `status`, Younium creates a new subscription as a draft and a new sales order as an order draft, so the order is activated in Younium. Drafts are not brought back to Salesforce; the order appears as a **Younium Order** at the first subscription synchronisation after it is activated. When it first arrives, the package links it to the deal it came from: the order's **Source Opportunity** or **Source Quote** is set, and the deal's **Younium Order** field points to the order.

A change can only be made to a subscription that is active in Younium; Younium refuses a change to a draft.

### Field mapping: order (Salesforce → Younium)

The same fields are read from an opportunity or a quote unless noted.

| Younium Field         | Salesforce Field                                                                                           |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `account`             | The Younium id of the deal's account                                                                       |
| `invoiceAccount`      | The Younium id of the account in **Invoice Account**. When blank, Younium invoices the order's own account |
| `externalCRMId`       | The Salesforce id of the opportunity or quote (always; cannot be mapped)                                   |
| `currency`            | **Currency** (`CurrencyIsoCode`) of the opportunity or quote                                               |
| `orderDate`           | **Close Date** (`CloseDate`) on an opportunity; **Expiration Date** (`ExpirationDate`) on a quote          |
| `effectiveStartDate`  | **Effective Start Date**                                                                                   |
| `term`                | **Initial Term**                                                                                           |
| `effectiveEndDate`    | **Effective End Date**, sent only when there is no initial term above 0 (the term takes precedence)        |
| `renewalTerm`         | **Renewal Term (Months)**                                                                                  |
| `effectiveChangeDate` | **Effective Change Date**; for a renewal, the day after the linked order's **Effective End Date**          |
| `nextRenewalTerm`     | **Renewal Term (Months)**, for a renewal                                                                   |
| `orderDiscounts`      | The deal's order discounts, with only the charges whose discount has changed                               |
| `milestones`          | The deal's milestones: `name`, `description`, `plannedDate`                                                |
| `products`            | The line items, grouped into order products as below                                                       |

These order fields are sent only when mapped: `status`, `description`, `remarks`, `noticePeriodDate`, `noticePeriod`, `lastRenewalDate`, `isAutoRenewed`, `orderType`, `subscriptionType`, `orderPaymentMethod`, `yourReference`, `ourReference`, `yourOrderNumber`, `buyerReference`, `invoiceAddressId`, `deliveryAddressId`, `externalERPId`, `paymentTerm`, `invoicingCurrency`, `setOrderBillingPeriod`, `orderBillingPeriod`, and the invoice batch group as `invoicebatchgroup.value` (with `invoicebatchgroup.key`, which defaults to `code`). Any other Younium field name is sent as an order custom field.

### Field mapping: order product (Salesforce → Younium)

Line items are grouped into order products by the charge plan they were added from: all charges added together from one charge plan form one order product.

| Younium Field   | Salesforce Field                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `product`       | The Younium product of the charge's charge plan; on a charge carried over from an order, the existing order product |
| `chargePlan`    | The Younium charge plan of the charge (new order products only)                                                     |
| `operation`     | On a change: *Change* for an order product carried over from the order, *Create* for a new one                      |
| `externalCRMId` | The Salesforce id of the first line item in the group                                                               |

`externalERPId` is sent only when mapped, and any other Younium field name is sent as an order product custom field.

### Field mapping: charge (Salesforce → Younium)

| Younium Field                             | Salesforce Field                                                                                                                                                           |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `charge`                                  | The Younium charge of the Salesforce product; on a charge carried over from an order, the existing order charge                                                            |
| `name`                                    | **Product Name** of the Salesforce product                                                                                                                                 |
| `chargeType`                              | **Charge Type**                                                                                                                                                            |
| `priceModel`                              | **Charge Model**                                                                                                                                                           |
| `startOn` / `endOn`                       | **Start On** / **End On**: *Align to Order* is sent as `AlignToSubscription`, *Specific Date* as `SpecificDate`, *Milestone* as `Milestone`. Not sent for *OneOff* charges |
| `effectiveStartDate` / `effectiveEndDate` | **Effective Start** / **Effective End**, when **Start On** / **End On** is *Specific Date*                                                                                 |
| `startMilestone` / `endMilestone`         | **Start Milestone** / **End Milestone**, when **Start On** / **End On** is *Milestone*                                                                                     |
| `billingPeriod`                           | **Billing Period** of the Salesforce product. Not sent for *OneOff* charges                                                                                                |
| `billingTiming`                           | **Billing Timing** of the Salesforce product                                                                                                                               |
| `quantity`                                | **Quantity** (`Quantity`). Not sent for *Flat* charges                                                                                                                     |
| `pricePeriod`                             | **Price Period**                                                                                                                                                           |
| `externalCRMId`                           | The Salesforce id of the line item                                                                                                                                         |
| `priceDetails`                            | See below                                                                                                                                                                  |

These charge fields are sent only when mapped: `unitCode`, `chargedThroughDate`, `lastRenewalDate`, `lastPriceAdjustmentDate`, `usageRating`, `revenueRecognitionRule`, `billingDay`, `offsetBillingDays`, `specificBillingDay`, `periodAlignment`, `alignmentDate`, `taxTemplate`, `taxIncluded`, `createInvoiceLinesPerTier`, `remarks`, `deferredRevenueAccount`, `recognizedRevenueAccount`, `changeState`, `estimatedUsage`, `estimatedQuantity`, `orderedQuantity`, `recurringMonthlyAmount` and `externalERPId`. The line item's **Remarks** therefore reach Younium only through a mapping. Any other Younium field name is sent as a charge custom field.

**Price details.** For *Flat* and *Quantity* charges one price detail is sent, tier 0, with `price` from **Sales Price** and `listPrice` from **List Price**. A line discount is carried by the difference between the two. For *Tiered* and *Volume* charges the tiers on the line item are sent as they are, each with `tier`, `fromQuantity`, `toQuantity`, `price`, `listPrice`, `priceBase` and `description`.

***

## Quotes

Quotes work exactly like opportunities in the product editor and when sent to Younium, with their own field mapping types. A quote has its own **Opportunity Type**, **Order Type**, **Effective Start Date**, **Effective End Date**, **Effective Change Date**, **Initial Term**, **Renewal Term (Months)**, **Is Renewal**, **Invoice Account**, **Younium Order** and **Sync Date** fields.

The package keeps a quote and its opportunity aligned:

| Event                                                                    | What happens                                                                                                              |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| A quote is created on an opportunity                                     | The quote takes the opportunity's Younium fields                                                                          |
| A quote that is syncing with its opportunity has a Younium field changed | The change is copied to the opportunity                                                                                   |
| A quote starts syncing with its opportunity                              | Its Younium fields are copied to the opportunity, and its line items' Younium fields to the matching opportunity products |

Two formula fields on the quote, **Is Closed** and **Is Won**, are driven by the quote status settings below. **Is Closed** decides whether the product editor and **Reset to Order** treat the quote as closed.

### Settings

| Setting                   | Description                                                                              | Default         |
| ------------------------- | ---------------------------------------------------------------------------------------- | --------------- |
| **Quote Closed Statuses** | On the **General Settings** tab. Semicolon-separated quote statuses that count as closed | Accepted;Denied |
| **Quote Won Statuses**    | On the **General Settings** tab. Semicolon-separated quote statuses that count as won    | Accepted        |

***

## Contract value metrics

Younium calculates the contract value of a deal before it is sent. The package sends the deal to Younium as it would be ordered, without creating anything, and writes the metrics Younium returns for each line item onto it:

| Younium metric                      | Line item field |
| ----------------------------------- | --------------- |
| Total contract value                | **TCV**         |
| Committed monthly recurring revenue | **CMRR**        |
| Annual contract value               | **ACV**         |
| One-time fees                       | **OTF**         |

Metrics are recalculated:

| Trigger                                                                                                                                                                                                                                             | Notes                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Products are saved in the product editor                                                                                                                                                                                                            | Runs immediately; the editor's **Insights** panel and line items show the new values                                             |
| **Effective Start Date**, **Effective End Date**, **Effective Change Date**, **Initial Term**, **Renewal Term (Months)**, **Opportunity Type**, **Order Type** or the order discounts change on an opportunity or quote that has Younium line items | Runs in the background. When the product editor is open on the deal, it also recalculates immediately and refreshes **Insights** |
| **Sync Metrics** on the opportunity or quote                                                                                                                                                                                                        | Runs immediately and shows *Metrics Synced!* or the error                                                                        |

On a change deal, line items carried over from the order also show the order's values in **Previous TCV**, **Previous CMRR**, **Previous ACV** and **Previous OTF**, so the effect of the change can be compared.

***

## Change orders

### Creating a change opportunity or quote

**Change Order** on a **Younium Order** record creates a change opportunity from the order; **Change Order (Quote)** creates a change quote. The form asks for the deal's fields, the renewal options (**Is Renewal**, and **Renewal Term (Months)** when it is a renewal), and which of the order's charges to include.

The new deal is set up as follows. Values the user entered on the form take precedence over the defaults.

| Field                                                       | Value                                                            |
| ----------------------------------------------------------- | ---------------------------------------------------------------- |
| Name                                                        | *Change Order - {order number}*                                  |
| **Stage** (opportunity) or **Status** (quote)               | *Prospecting* or *Draft*                                         |
| **Close Date** (opportunity) or **Expiration Date** (quote) | Today                                                            |
| **Effective Change Date**                                   | Today                                                            |
| **Account** (opportunity)                                   | The order's account                                              |
| **Opportunity Type**                                        | *Change* (always)                                                |
| **Younium Order** and the Younium order id                  | The order (always)                                               |
| Price book                                                  | The one active price book of the account's legal entity (always) |
| Currency                                                    | The order's currency (always)                                    |
| Order discounts                                             | The order's order discounts                                      |

Each selected charge becomes a line item with the order charge's model, type, tiers, dates, price period, list price and unit price, a quantity of at least 1, **Change State** *No Change*, and the order charge's metrics in the **Previous** fields. If an order discount refers to a charge that was not selected, the deal is not created and the form says which charge is missing.

A change quote needs an opportunity. The package uses an opportunity already linked to the same order if there is one, and otherwise creates one alongside the quote.

Whenever a line item is saved again, its **Change State** is set to *Change* if it was carried over from the order and *New* otherwise.

### Reset to Order

**Reset to Order** on a change opportunity or quote rebuilds it from its linked order. All line items are removed, a line item is added for each recurring charge on the order, and the price book, currency, Younium order id and order discounts are reset to match the order. It is available only on an open change deal that is linked to an order.

### Settings

The fields on the change order forms are set on the **Layout Items** tab; see [Layout items](#layout-items).

***

## Cancelling an order

**Cancel Order** on a **Younium Order** record asks for an **End Date**, which starts as the order's **Effective End Date**. Younium cancels the subscription with that end date, recording today as the cancellation date on the order and its charges. The order is then synchronised back from Younium straight away, so the Salesforce record reflects the cancellation. If Younium refuses the cancellation, its reason is shown and nothing changes.

***

## Renewal opportunities

The package can create renewal opportunities automatically for orders approaching their end date. It runs on a schedule set on the **Renewals** tab of the package settings, and only while **Enable Renewal Opportunity Generator** is on.

An order is picked up when all of these hold:

| Condition             | Detail                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Status                | The order's **Status** is *Active*                                                                                                   |
| End date              | The order's **Effective End Date** falls within the number of months set in **Months before End Date Filter**, or has already passed |
| No open renewal       | No open opportunity with **Is Renewal** selected is linked to the order                                                              |
| Not already generated | No renewal has been generated for the order's current period                                                                         |
| Filter                | When **Custom Order Filter Field** is set, that checkbox field on the order is selected                                              |

For each order it creates a change opportunity named *Renewal - {order number}*, with **Is Renewal** selected, **Stage** from **Renewal Opportunity Stage**, **Amount** from the order field named in **Order Amount Field** (0 when that field is blank), and the order's account, currency, price book and link set as for a change order. The renewal opportunity starts with no line items; charges are added in the product editor before it is sent. The order is then marked so that it is not picked up again for the same period. The mark is cleared when the order's **Effective End Date** moves later, which happens when the renewal reaches Younium and the order is synchronised back.

**View Orders Due for Renewal** lists the orders the next run would pick up, or says that no orders are due. Each run is recorded as a sync job of type *Renewal Opportunity*, shown under **Previous Jobs** on the same tab.

### Settings

| Setting                                  | Description                                                                                             | Default        |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------- |
| **Enable Renewal Opportunity Generator** | Creates renewal opportunities on the schedule                                                           | Off            |
| **Batch Size**                           | How many orders are processed per batch                                                                 | 2              |
| **Order Amount Field**                   | API name of the field on the Younium order whose value becomes the renewal opportunity's **Amount**     | `ynm__CMRR__c` |
| **Months before End Date Filter**        | How many months ahead of their end date orders are picked up                                            | 3              |
| **Custom Order Filter Field**            | API name of a checkbox field on the Younium order. When set, only orders with it selected are picked up | Blank          |
| **Renewal Opportunity Stage**            | Stage given to new renewal opportunities                                                                | Prospecting    |

***

## Product catalogue synchronisation

### What is synchronised

For each legal entity, the package fetches the Younium products of that legal entity with their charge plans, charges and price details, and creates or updates the matching records in Salesforce. Records are matched on their Younium id, so a renamed product is updated rather than duplicated.

Price book entries are written for each charge in every price book linked to the legal entity, and in the standard price book: one entry per currency the charge is priced in. A *Tiered* or *Volume* charge gets one entry per currency, priced at its first tier, with all of its tiers stored on the entry. An existing entry keeps its currency and product; only its price and details are updated.

When the standard price book already holds an entry for the same product and currency — for example one created by the earlier Younium package — product sync takes over and updates that entry rather than creating a second one.

### Field mapping: product catalogue (Younium → Salesforce)

**Younium Product**

| Younium Field                       | Salesforce Field                       |
| ----------------------------------- | -------------------------------------- |
| `name`                              | **Product Name** (first 80 characters) |
| `id`                                | **Id**                                 |
| `endOfNewSalesDate`                 | **End Of New Sales**                   |
| The legal entity being synchronised | **Younium Legal Entity**               |

**Charge Plan**

| Younium Field             | Salesforce Field                           |
| ------------------------- | ------------------------------------------ |
| `name`                    | **Charge Plan Name** (first 80 characters) |
| `id`                      | **Id**                                     |
| `endOfNewSalesDate`       | **End Of New Sales**                       |
| The product it belongs to | **Younium Product**                        |

**Product (one per Younium charge)**

| Younium Field                 | Salesforce Field                       |
| ----------------------------- | -------------------------------------- |
| `name`                        | **Product Name** (first 80 characters) |
| `id`                          | **Id**                                 |
| `chargeType`                  | **Charge Type**                        |
| `model`                       | **Model**                              |
| `pricePeriod`                 | **Price Period**                       |
| `defaultQuantity`             | **Default Quantity**                   |
| `billingPeriod`               | **Billing Period**                     |
| `billingTiming`               | **Billing Timing**                     |
| The charge plan it belongs to | **Charge Plan**                        |
| (always)                      | **Active** is selected                 |

**Price book entry (one per price detail currency)**

| Younium Field                               | Salesforce Field                                             |
| ------------------------------------------- | ------------------------------------------------------------ |
| `price`                                     | **List Price** (`UnitPrice`)                                 |
| `currency`                                  | **Currency** (`CurrencyIsoCode`), on creation only           |
| The charge's price details in that currency | **Charge Tiers**                                             |
| (always)                                    | **Active** is selected and **Use Standard Price** is cleared |

### Products withdrawn from Younium

A full run, started with **Sync ALL Products Now**, also clears out what Younium no longer has. When every legal entity in the run finished without errors, every Younium product, charge plan, product and price book entry of those legal entities that the run did not touch gets **Removed From Younium** selected, and products and price book entries are also made inactive. If any part of the run had an error, nothing is cleared, so a partial run never withdraws products by mistake. Incremental runs never clear anything.

Only one product synchronisation runs at a time. Starting one while another, or its clean-up, is still running is refused.

### Settings

| Setting                     | Description                                                                     | Default |
| --------------------------- | ------------------------------------------------------------------------------- | ------- |
| **Product Sync Batch Size** | On the **General Settings** tab. How many Younium products are fetched per page | 100     |

***

## Subscription and sales order synchronisation

### What is synchronised

For each legal entity, the package fetches the latest version of each subscription and each sales order and creates or updates a **Younium Order** with its order products and order product charges. Draft subscriptions and order drafts are skipped. Orders are matched on order number and legal entity, order products on product number, and charges on charge number, so one Salesforce order always represents the current version of one Younium order. Only the latest version of each charge is kept.

An order is linked to its Salesforce account through the account's Younium id. An order whose account has not been synchronised from Salesforce cannot be saved and is counted as an error.

When a subscription or sales order created from Salesforce first arrives, it is linked to its source deal (see [After sending](#after-sending)).

### Field mapping: order (Younium → Salesforce)

| Younium Field        | Salesforce Field (on **Younium Order**)                                         |
| -------------------- | ------------------------------------------------------------------------------- |
| `orderNumber`        | **Order Number**                                                                |
| `id`                 | **Younium Id**                                                                  |
| `account.id`         | **Account**, matched on the account's Younium id                                |
| `currency`           | **Currency**                                                                    |
| `orderType`          | **Order Type** (*Subscription* or *SalesOrder*)                                 |
| `status`             | **Status**                                                                      |
| `effectiveStartDate` | **Effective Start Date**                                                        |
| `effectiveEndDate`   | **Effective End Date**                                                          |
| `cmrr.amount`        | **CMRR**                                                                        |
| `acv.amount`         | **ACV**                                                                         |
| `tcv.amount`         | **TCV**                                                                         |
| `orderDiscounts`     | **Order Discounts**                                                             |
| `externalCRMId`      | **Source Opportunity** or **Source Quote**, when the order was created from one |

Mappings can also read the order's account and invoice account (`account.name`, `account.accountnumber`, `account.externalcrmid`, `invoiceaccount.*`), its invoice and delivery addresses (`invoiceaddress.*`, `deliveryaddress.*`), the invoice batch group (`invoicebatchgroup.id`, `.code`, `.description`), each metric's currency and base currency values (`cmrr.currencycode`, `cmrr.basecurrencyamount`, `cmrr.basecurrencycode`, and the same for `acv`, `emrr`, `onetimefees` and `tcv`), any other order field by its name, and any order custom field by its name.

### Field mapping: order product (Younium → Salesforce)

| Younium Field          | Salesforce Field (on **Younium Order Product**)          |
| ---------------------- | -------------------------------------------------------- |
| `productNumber`        | **Product Number**                                       |
| `chargePlanId`         | **Charge Plan**, matched on the charge plan's Younium id |
| The order              | **Order**                                                |
| The order's `currency` | **Currency**                                             |

The order product's metrics (`cmrr.*`, `acv.*`, `emrr.*`, `onetimefees.*`, `tcv.*`), its other fields and its custom fields can be read through mappings.

### Field mapping: order product charge (Younium → Salesforce)

| Younium Field                             | Salesforce Field (on **Younium Order Product Charge**)                                                            |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `chargeNumber`                            | **Charge Number**                                                                                                 |
| `id`                                      | **Younium Id**                                                                                                    |
| `chargeId`                                | **Salesforce Product**, matched on the product's Younium id                                                       |
| `chargeType`                              | **Charge Type**                                                                                                   |
| `priceModel`                              | **Charge Model**                                                                                                  |
| `quantity`                                | **Quantity**                                                                                                      |
| `startOn` / `endOn`                       | **Start On** / **End On**: `AlignToSubscription` becomes *Align to Order*, `SpecificDate` becomes *Specific Date* |
| `effectiveStartDate` / `effectiveEndDate` | **Effective Start** / **Effective End**                                                                           |
| `pricePeriod`                             | **Price Period**                                                                                                  |
| `price`                                   | **Unit Price**, or the first price detail's price when there is none                                              |
| `listPrice`                               | **List Price**, or the first price detail's list price when there is none                                         |
| `priceDetails`                            | **Charge Tiers**                                                                                                  |
| `cmrr.amount`                             | **CMRR**                                                                                                          |
| `acv.amount`                              | **ACV**                                                                                                           |
| `tcv.amount`                              | **TCV**                                                                                                           |
| `oneTimeFees.amount`                      | **OTF**                                                                                                           |

The charge's metric currency values, its other fields and its custom fields can be read through mappings in the same way.

### Settings

| Setting                          | Description                                                                                  | Default |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------- |
| **Subscription Sync Batch Size** | On the **General Settings** tab. How many subscriptions or sales orders are fetched per page | 100     |

***

## Invoice synchronisation

### What is synchronised

For each legal entity, the package fetches invoices and creates or updates a **Younium Invoice** with its **Younium Invoice Line** records. Draft and cancelled invoices are not fetched. Invoices are matched on their Younium id and lines on theirs, so each Younium invoice appears once.

An invoice is linked to its Salesforce account through the account's Younium id. An invoice for an account that has not been synchronised from Salesforce cannot be saved and is counted as an error.

### Field mapping: invoice (Younium → Salesforce)

| Younium Field   | Salesforce Field (on **Younium Invoice**)        |
| --------------- | ------------------------------------------------ |
| `invoiceNumber` | **Invoice Number**                               |
| `id`            | **External Id**                                  |
| `account.id`    | **Account**, matched on the account's Younium id |
| `currency`      | **Currency**                                     |
| `status`        | **Status**                                       |
| `invoiceDate`   | **Invoice Date**                                 |
| `dueDate`       | **Due Date**                                     |
| `paymentDate`   | **Payment Date**                                 |
| `totalAmount`   | **Total Amount**                                 |

Mappings can also read the invoice's account (`account.name`, `account.accountnumber`, `account.externalcrmid`), its invoice and delivery addresses (`invoiceaddress.*`, `deliveryaddress.*`), any other invoice field by its name (for example `subtotal`, `tax`, `settledAmount`, `balancedAmount`, `yourReference` or `invoiceType`), and any invoice custom field by its name.

### Field mapping: invoice line (Younium → Salesforce)

| Younium Field            | Salesforce Field (on **Younium Invoice Line**) |
| ------------------------ | ---------------------------------------------- |
| `productName`            | **Invoice Line Number** and **Product Name**   |
| `id`                     | **External Id**                                |
| `quantity`               | **Quantity**                                   |
| `total`                  | **Total Amount**                               |
| The invoice              | **Invoice**                                    |
| The invoice's `currency` | **Currency**                                   |

Other invoice line fields (for example `price`, `subtotal`, `tax`, `servicePeriodStartDate`, `servicePeriodEndDate` or `chargeNumber`) and invoice line custom fields can be read through mappings by their names.

### Invoice PDF

**Download Invoice PDF** on a **Younium Invoice** fetches the invoice document from Younium, attaches it to the invoice record as a file named after the invoice number, and opens it. If the invoice already has that file and the document has not changed, the existing file is opened; if it has changed, a new version of the file is added.

### Settings

| Setting                     | Description                                                             | Default |
| --------------------------- | ----------------------------------------------------------------------- | ------- |
| **Invoice Sync Batch Size** | On the **General Settings** tab. How many invoices are fetched per page | 100     |

***

## Sync jobs, schedules and logs

### Running and scheduling

The **Sync Jobs** tab of the package settings shows one synchronisation from Younium at a time, chosen with **Products**, **Subscriptions and Sales Orders** or **Invoices**. For the chosen synchronisation it shows:

| Area                         | What it shows or does                                                                                                                                                                              |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Summary                      | **Overall status** of the latest run (*Healthy*, *Needs attention* when it had errors, or *No runs yet*), when the **Latest run** started, and the **Next scheduled run**                          |
| **Legal Entity Sync Status** | Each legal entity with the date of its **Last Successful Sync**, the last run for it that finished with no errors. Searchable                                                                      |
| **Sync since last run**      | Fetches what has changed in Younium since the last run that finished without errors, per legal entity                                                                                              |
| **Run full sync**            | Fetches everything                                                                                                                                                                                 |
| **Recent Activity**          | Lists earlier runs, newest first, with their legal entity, type, status, counts, **Sync From Date** and creation date. Runs with errors are flagged. **Fetch more rows** shows older runs          |
| **Schedule**                 | Adds a scheduled run with a **Job Name**, running **Every Day** at a set time (HH:mm) or **Every Hour** at a set number of minutes past the hour. Existing schedules are listed and can be removed |

Scheduled runs always fetch what has changed since the last error-free run. A run whose last error-free predecessor cannot be found, such as the first run, fetches everything.

### Sync job records

| Sync Job field     | Content                                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Type**           | *Product*, *Subscription*, *SalesOrder* or *Invoice* (and *Product Cleanup* and *Renewal Opportunity* for the clean-up and renewal runs) |
| **Legal Entity**   | The legal entity the run was for                                                                                                         |
| **Status**         | *Not Finished*, *Finished*, *Error*, or *Error (Timeout)* for a run still unfinished after six hours                                     |
| **Total Count**    | Records processed                                                                                                                        |
| **Error Count**    | Records that could not be saved                                                                                                          |
| **Sync From Date** | The point in time the run fetched changes from. Blank for a run that fetched everything, shown as *Full sync* in **Recent Activity**     |

A record that cannot be saved does not stop the run: the rest are saved, the failure is counted, and a **Log** record attached to the sync job names the record and the reason. A run that fails as a whole is marked *Error*. Either way, the next incremental run starts from the last run that finished with no errors, so nothing that failed is skipped.

### Settings

| Setting           | Description                                                                                                                                                      | Default |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Logging Level** | A Salesforce custom setting. *ERROR* records failures only; *INFO* also records every request to Younium and its response, which helps when diagnosing a mapping | ERROR   |

***

## View in Younium

**View in Younium** on an account, a **Younium Order** or a **Younium Invoice** opens the same record in the Younium web app, in the environment and region the package is using. On a record that has not reached Younium yet it reports *This record has not been synced to Younium yet.*

***

## Layout items

The **Layout Items** tab of the package settings decides which fields appear on the package's forms, in what order and how wide. Each layout item names a field and sets **Active**, **Read Only**, **Required**, **Sort Order** and **Width (Columns)** (1 to 12).

| Form                           | Object                       | Fields shipped with the package                                                                                                                                                                                               |
| ------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Charge Form                    | Opportunity product          | Description, Charge Type (read-only), Charge Model, Start On, Effective Start, Start Milestone, End On, Effective End, End Milestone, Price Period, Quantity, Remarks, List Price, Discount (%), Discount Amount, Sales Price |
| Charge Form (Quote)            | Quote line item              | The same fields as the Charge Form                                                                                                                                                                                            |
| Change Order Form              | Opportunity                  | Name, Stage, Close Date                                                                                                                                                                                                       |
| Change Order Form (Quote)      | Quote                        | Name, Status, Expiration Date                                                                                                                                                                                                 |
| Change Order Form Charge Table | Younium order product charge | Name, Salesforce Product, Unit Price                                                                                                                                                                                          |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/crm-integrations/salesforce.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
