@@ -9,6 +9,29 @@ The documentation below is organized by feature. Each section will have links t
---
## Order Type & First Orders (GTM Systems Hub)
This section is the single source of truth for:
-**Order Type** logic in Salesforce (all 7 values).
-**UPA First Order (UPA FO)** logic.
-**Domestic First Order (DFO)** logic.
- How these fields are used across GTM systems and processes.
### Business overview
At a high level:
-**Order Type** tells us how an opportunity changes ARR on the existing customer hierarchy (UPA): land, expand, contract, or churn.
-**UPA FO** identifies the **first qualifying paid subscription** at the Ultimate Parent Account level for a given period, excluding EDU/OSS and with a 180-day returning customer policy.
-**Domestic First Order (DFO)** identifies the first qualifying paid New Business subscription under that **UPA and Domestic Region** (Domestic Region account field).
Downstream:
-**Sales & Finance** primarily use **Order Type** and **UPA FO / DFO** for comp, C&C, and bookings analysis.
-**Enterprise Applications / Field Ops** use these fields to drive automation (for example, Admin Contact Required, CSM stamping).
-**Sales** should use the First Orders – Sales Guide for how to interpret these fields in day-to-day selling.
## ARR
Please see the dedicated [ARR Technical Documentation Page](/handbook/sales/field-operations/sales-systems/gtm-technical-documentation/sfdc-booking-metric-fields/)
**Business Process this supports:**[New vs Connected New vs Growth](/handbook/sales/sales-term-glossary/)
**Business process:**
Classify every opportunity into one of seven Order Type values so we can:
**Overview:** The goal of the Order Type system is to determine a given Opportunity's relationship with the business. Did it start a new customer relationship, cross into a related segment of the customer, or grow an existing relationship.
- Distinguish **lands vs expansions vs contractions vs churn**.
- Support accurate **commissions**, **C&C**, and **First Order** reporting.
| Opportunity | Order Type | Stamped Order Type (primary field). |
| Opportunity | Order Type (Live) | Live Order Type used for in-year adjustments; not updated after fiscal year end. |
| Opportunity | Order Type Override | Manual override field (used rarely, with strict process). |
| Opportunity | New Logo Eligible | Flags whether an opportunity can ever be a FO / New - Connected / eligible Growth land. |
| Opportunity | Domestic First Order | Indicates whether this opportunity is the DFO for its UPA & Domestic Region. |
| Opportunity | Link to Decommissioned Opportunity | Used for Decommission opportunities to inherit Order Type and DFO from another record. |
#### Logic summary (high-level)
Below is a Salesforce-focused summary of the implemented logic, grouped by **Subscription Type** and **Net ARR sign**.
##### New Business
**Positive Net ARR**
- If **New Logo Eligible = TRUE**:
- First qualifying opportunity under the UPA within the 180-day window → `New - First Order` (UPA FO).
- First qualifying opportunity on another Account under the same UPA, when a UPA FO already exists → `New - Connected`.
- Subsequent qualifying opportunities at the same Account → `Growth`.
- If **New Logo Eligible = FALSE**:
- Order Type = `Growth`.
Storage-only New Business opportunities (for example, only storage products on the opportunity) are **not** New - First Order or New - Connected; they are treated as **Growth**.
**Negative Net ARR**
For Subscription Type = New Business and categories such as:
- Standard
- Internal Correction
- Contract Reset
- Ramp Deal
- Contract Reset/Ramp Deal
- CloudBlue Public Offer
- Bad Debt
→ Order Type = `Contraction`.
**Decommission**
- If a Decommission opportunity is linked to another opportunity:
- Order Type is inherited from the linked opportunity’s **Order Type (Live)**.
- Domestic First Order on the Decommission opportunity inherits from the originating opportunity’s DFO value (via the **Opportunity to Decommission** lookup). This allows Finance to track “negative DFOs” (removal of first-order business) when original FO/DFO deals are debooked.
- If the link is missing or invalid:
- Order Type (Live) and DFO are not changed by this logic; remediation is handled via data cleanup.
- Changes to the originating opportunity’s DFO value after the Decommission is created do **not** resync the Decommission’s DFO; the Decom keeps the value it had at creation.
##### Add-On
**Positive Net ARR**
- Order Type = `Growth`.
**Negative Net ARR**
- Order Type = `Contraction`, except for rare edge cases explicitly mapped as `PS / Other` (for example, some non-standard credit scenarios).
**Net ARR = 0, Recurring Amount > 0**
- Typically **PS / Other**, since these are non-recurring or technical corrections that do not change ARR.
##### Renewal
**Positive Net ARR**
- Order Type = `Growth` (renewals that maintain or increase ARR).
**Negative Net ARR**
- While open or Closed Won:
- Order Type = `Contraction`.
- When moved to Closed Lost:
- If the Account Family has **no remaining active subscriptions** after the associated subscription end date → `Churn - Final`.
- If the Account Family has **one or more active subscriptions** remaining → `Churn - Partial`.
**Net ARR = 0, Recurring Amount > 0**
- Treated as **flat renewals** and mapped to `Growth`, with some special cases covered by business rules.
#### Abbreviated scenario table
| Subscription Type | Net ARR sign | Example Categories | Typical Order Type (Open / Closed Won) | Churn behavior (when Closed Lost) |
| New Business | positive | Standard, Ramp Deal, Internal Correction | `New - First Order` / `New - Connected` / `Growth` based on FO history and eligibility | Later negative-ARR renewals may drive churn classification |
| New Business | negative | Standard, Internal Correction, Contract Reset, Ramp Deal, CB Offer, Bad Debt | `Contraction` | `Contraction` |
| New Business | any | Decommission | Inherits from linked opportunity | Inherits from linked opportunity |
| Renewal | zero | Flat renewals (rec. amount > 0) | `Growth` | Churn only if associated subscription fully ends later |
#### Domestic First Order logic (DFO – high level)
**Domestic First Order (DFO)** is calculated for **New Business** opportunities:
- Type = New Business.
- Positive Net ARR.
- Not storage-only.
- Not EDU/OSS.
- Qualifies as a land under the Order Type 2.3 rules (New - First Order / New - Connected / Growth, not Decommission).
- Is the first such land under the same **UPA and Domestic Region** (Domestic Region account field) within the 180-day policy window.
Key properties:
- Exactly **one UPA FO** at a time per UPA.
-**Multiple DFOs per UPA are allowed**, but only **one DFO per Domestic Region**.
- DFO is stamped on the Opportunity; **Domestic First Order Available** is tracked on Accounts and updated by a nightly job (allow **up to 24 hours** after close to update).
- The 180-day return-customer rules and FO/DFO eligibility are evaluated based on **paid subscriptions** (current MRR > 0). Subscriptions with **$0 MRR** do not make a customer “active” for First Order purposes, do not reset the 180-day timer, and do not block FO/DFO eligibility.
**DFO on Closed Lost opportunities**
- If an opportunity has **Domestic First Order = TRUE** and later moves to **Closed Lost**, the Domestic First Order value on that opportunity remains **TRUE** and is not cleared.
- A Closed Lost DFO opportunity does **not** make the account ineligible for future DFOs:
-**Domestic First Order Available** on the Account remains TRUE (subject to normal eligibility rules).
- The next eligible open New Business opportunity in that Domestic Region can also be marked **Domestic First Order = TRUE**.
- This mirrors the behavior of **Order Type** (persistent on the opportunity, independent of whether the deal was won or lost).
**Cross-region example: DFO = TRUE, Order Type = New – Connected**
Because UPA FO and DFO are evaluated at different levels:
- UPA FO and Order Type look at the entire UPA and ask “has this hierarchy had a first order before?”
- DFO looks at a single Domestic Region and asks “has this UPA + Domestic Region had a qualifying first order before (and, if applicable, passed any regional 180-day rules)?”
Example:
- determineOpportunityRevenueTypes
- UPA has two accounts:
- Account A (Domestic Region = AMER)
- Account B (Domestic Region = ANZ)
- First qualifying New Business opportunity is created on Account B (ANZ):
- Meets all “first order” criteria.
- There is no prior FO in the UPA yet.
- Order Type = New – First Order.
- Domestic First Order = TRUE for ANZ.
- Later, a first-ever qualifying New Business opportunity is created on Account A (AMER) in the same FO cycle:
- Meets all “first order” criteria for Account A.
- The UPA already has a New – First Order on Account B, so from a hierarchy perspective this is a connected new logo.
- Order Type = New – Connected.
- If AMER has not had a qualifying FO before (and satisfies any regional 180-day rules), Domestic First Order = TRUE for AMER.
**Inputs:** Salesforce Account Hierarchy, Salesforce Opportunity Close Date and Stage.
In this scenario, the opportunity on Account A has Domestic First Order = TRUE and Order Type = New – Connected. DFO is “first in this region for this UPA,” while Order Type distinguishes between the very first FO in the UPA (New – First Order) and the first FO on additional accounts in that same UPA (New – Connected).
**Outputs:** Populates the Order Type field on the Opportunity with New - First Order, New - Connected or Growth based on the following logic:
| New - First Order | The First Closed Won Opportunity in an Account Family. |
| New - Connected | The First Closed Won Opportunity on an individual Account, that is not the first one in the Account Family.|
| Growth | All opportunities that follow the `New - First Order` or `New - Connected` opportunities. This includes Add-ons, Renewals, and additional Subscriptions. |
- Order Type 2.3 logic is implemented in Salesforce and runs when relevant fields change.
- Some historical backfills were performed (for example, on Stage 3+ opportunities and targeted negative-ARR corrections). Opportunities that never met those criteria may still show legacy values.
- After fiscal year end, **Order Type (Live)** is not updated for historical opportunities to preserve compensation and reporting integrity.
- DFO inheritance on Decommission opportunities and persistence on Closed Lost DFO opps are implemented and tested per the Order Type Redesign project issues.
