The UOM (Unit of Measure) and Frequency Conversion Rate runtime APIs support multiple levels of conversion rate configuration, at the Product level, the Product Family level, and the Global level. This topic explains how the system resolves the applicable conversion rate based on the parameters you include in your API request.

Prerequisites: Product Family Picklist Configuration

If you add a custom picklist value to the Product Family picklist, you must also add the same value to the UOM/Frequency ProductFamily picklist. This ensures that Product Family–specific conversion mappings can be configured and resolved correctly.

Conversion Rate Hierarchy:

Conversion rates can be configured at three levels, listed from most specific to least specific:

The system always returns the first matching conversion found in the above precedence order.

How the Lookup Works Based on Request Parameters:

Detailed Behavior:

• Scenario B — ProductId only: When a ProductId is provided, the system first looks for a conversion rate configured specifically for that Product. If no Product-specific conversion exists, the system falls back directly to the Global conversion. The system does not attempt to derive the Product's Family from the Product record.
• Scenario D — ProductId + ProductFamily: When both ProductId and ProductFamily are provided, the system follows the full three-tier lookup: Product → Product Family → Global. If no Product-specific conversion is found, the system checks for a Product Family–specific conversion before falling back to Global.

Important: No Implicit Product Family Resolution:

The system uses the ProductFamily value only when it is explicitly included in the request payload. If a ProductId is supplied but no matching Product-specific conversion is found, the system will not perform an additional lookup on the Product object to derive its Family value. Product Family fallback occurs only when ProductFamily is part of the request.