Fluent Commerce Logo
Docs

Getting Started with Reference Sourcing Criteria

How-to Guide

Author:

Kirill Gaiduk

Changed on:

26 Sept 2025

Key Points

  • Understand the Ranking Mechanism: Sourcing Criteria score (or exclude) candidate Locations to drive ranking and tie-breaking
  • Sequence Matters: Criteria are evaluated top-to-bottom; the first Criterion decides the primary order, the next acts as a tie-breaker
  • Normalize Ratings: Most Criteria return raw numeric ratings that the framework normalizes across Locations to ensure consistent comparisons
  • Use Exclusion Carefully: Some Criteria return a negative score (-1) to exclude Locations; apply these early in the stack for predictable outcomes
  • Know When to Extend: The reference library covers common distance, inventory availability, and priority logic; develop a custom Criterion for domain-specific logic
No alt text provided

Steps

Step arrow right iconCore Concept

A Sourcing Criterion is a configurable function that evaluates a candidate Location in context of the Sourcing Request and returns a rating:

  • A positive float (0…1) ranks how suitable a Location is
  • -1 filters a Location out of consideration
  • Criteria are applied in sequence to produce a final ranked list of eligible Locations

During Strategy evaluation, the framework instantiates the Criterion class defined by `type` (for example, `fc.sourcing.criterion.locationDistance`) and applies its `apply()` method to every candidate Location.

Step arrow right iconInternal Mechanics

Reference Criteria share common behavior through `BaseSourcingCriterion` and Criterion Utilities:

  • Apply → Execute → Normalize:
    • `apply()` calls pre-logic, executes business rules, and post-logic
    • `normalize()` adjusts raw scores to a [0–1] range where applicable
  • Sequential Stack:
    • Criteria are applied in order of appearance
    • The first Criterion usually defines the main ranking dimension (e.g., distance or inventory availability)
    • Later Criteria resolve ties
  • Parameter Parsing:
    • `parseParams()` reads JSON params defined in the `fc.rubix.order.sourcing.criteria` Setting
    • Helper Utilities (`getFloats`, `getStrings`, `getDistanceUnits`) ensure correct types and default handling

Step arrow right iconReference Sourcing Criterion Functions

Class

(Criterion Utilities)

Type

(Sourcing Criteria Schema)

Description

(UI)

Notes

`LocationDistanceCriterion`

`fc.sourcing.criterion.locationDistance`

Prioritises locations that are geographically closer to the delivery address

  • Calculates raw distance (in km) between delivery address and Location
  • Then normalized (closer = higher rating)

`LocationDistanceBandedCriterion`

`fc.sourcing.criterion.locationDistanceBanded`

Ranks locations by distance bands {{value}}, prioritising bands that are closer

  • Groups Locations into configurable distance “bands” (in km or miles)
  • Scores based on which band they fall into (closer = higher rating)

`LocationDistanceExclusionCriterion`

`fc.sourcing.criterion.locationDistanceExclusion`

Excludes locations that are farther than {{value}}{{value}}

Excludes (-1) Locations beyond a specified maximum distance threshold (in km or miles)

`LocationDailyCapacityCriterion`

`fc.sourcing.criterion.locationDailyCapacity`

Prioritises locations with the highest available daily fulfillment capacity

Rates Locations based on their `DAILY_MAX_ORDER_CAPACITY` attribute value (higher capacity = higher rating)

`NetworkPriorityCriterion`

`fc.sourcing.criterion.networkPriority`

Prioritises locations by the specified network ranking {{value}}

  • Assigns scores by matching each Location to an ordered list of preferred Networks
  • If a Location belongs to multiple Networks, it inherits the score of the highest-ranked Network it belongs to

Example:

  • Network priority value = [Network1, Network2]
  • Scores:
    • Location1 (Network1) → 1
    • Location2 (Network2) → 0
    • Location3 (Network1 and Network2) → 1

`InventoryAvailabilityCriterion`

`fc.sourcing.criterion.inventoryAvailability`

Prioritises locations based on total units of inventory requested in the order that can be fulfilled

  • Calculates a "raw" availability for each Location = total available Items / total requested Items (can be > 1 if there is surplus Inventory)
  • All scores normalized to the 0-1 range: normalized = raw / max(raw)
  • If total requested Items = 0, returns 1

Example:

  • Sourcing Request:
    • Product1 (P1): 5
    • Product2 (P2): 3
    • Total requested Items = 8
  • Scores:
    • Location 1 (P1: 5, P2: 3) → raw = 8 / 8 = 1 → normalized = 0.625
    • Location 2 (P1: 4, P2: 1) → raw = 5 / 8 = 0.625 → normalized = 0.39
    • Location 3 (P1: 10, P2: 6) → raw = 16 / 8 = 2 → normalized = 1

Note:

A Location with surplus Inventory that does not fulfill the entire Sourcing Request may still receive a higher score than a Location that fully satisfies the Request. However, the framework prioritizes the Fulfillment Plan with the fewest Fulfillments overall

`InventoryAvailabilityBandedCriterion`

`fc.sourcing.criterion.inventoryAvailabilityBanded`

Ranks locations by fulfillment percentage bands {{value}}, prioritising bands with higher availability

  • Converts fulfillment percentage into configured “bands”
  • Assigns corresponding scores

`InventoryAvailabilityExclusionCriterion`

`fc.sourcing.criterion.inventoryAvailabilityExclusion`

Excludes locations where inventory availability for a given order, is less than {{value}}%

Excludes (-1) Locations that do not meet the configured minimum fulfillment threshold (in %)

`LocationTypeExclusionCriterion`

`fc.sourcing.criterion.locationTypeExclusion`

Excludes locations of type {{value}}

Excludes (-1) Locations whose type matches a configured value(s) (e.g., store vs. warehouse)

`LocationNetworkExclusionCriterion`

`fc.sourcing.criterion.locationNetworkExclusion`

Excludes locations that are members of one of the following networks {{value}}

  • Excludes (-1) Locations that belong to disallowed Networks
  • If a Location belongs to multiple Networks, and any of them matches a disallowed Network from the list, that Location will be excluded

`OrderValueCriterion`

`fc.sourcing.criterion.orderValue`

Prioritises locations that fulfill a higher monetary portion of the order

  • Calculates a score for each Location based on the monetary value of fulfillable Items
  • For each Item: value = (paidPrice + taxPrice) * quantity
  • filled = sum of monetary value that the Location can fulfill (capped at the requested quantity)
  • total = sum of monetary value of all requested Items
  • Score = filled / total (always in the 0–1 range)
  • If total = 0, returns 0

Example:

  • Sourcing Request:
    • Product1 (P1): 5 units @ $10 each
    • Product2 (P2): 3 units @ $20 each
    • Total value = (5 × $10) + (3 × $20) = $110
  • Scores:
    • Location 1 (P1: 5, P2: 3) → fulfills full $110 → 1
    • Location 2 (P1: 4, P2: 1) → fulfills (4 × $10) + (1 × $20) = $60 → 0.545
    • Location 3 (P1: 2, P2: 2) → fulfills (2 × $10) + (2 × $20) = $60 → 0.545

Note:

Unlike `InventoryAvailabilityCriterion`, surplus Inventory does not increase the score above 1 because the calculation caps the fulfilled value at the requested quantity of each Item

Default Sourcing Criteria

Class

Type

Notes

`RejectedLocationExclusionCriterion`

`fc.sourcing.criterion.locationExclusion`

Automatically excludes Locations that previously rejected Items in the same Sourcing Request (applied by default, not shown in UI)

Step arrow right iconParameter Definitions

Sourcing Criteria rely on parameters defined in the `fc.rubix.order.sourcing.criteria` Setting to ensure valid configuration:

  • `value`: Numeric thresholds or band breakpoints. An input like [10, 25, 50] defines 4 bands:
    • (–∞ … 10]
    • (10 … 25]
    • (25 … 50]
    • (50 … +∞)
  • `valueUnit`: Selects unit of measure where applicable (kilometres, miles)
  • `component`: UI input type such as `fc.field.multistring`, `integer`, or `select`
  • `mandatory` / `exactSearch`: Validation flags controlling whether the field must be provided and if exact match applies

Correct parameter definition guarantees consistent evaluation in both UI and runtime.

Step arrow right iconConfiguration in the UI

The reference schema in `fc.rubix.order.sourcing.criteria` Setting defines templates for all reference Sourcing Criteria. Each template specifies the required UI components and their validation rules to ensure that Criteria parameters are entered consistently and correctly.

For account/retailer-specific adjustments, override Criteria in `fc.rubix.order.sourcing.criteria.custom`. When a Criterion with the same `name` exists in both schemas, the custom schema takes precedence, allowing organizations to tailor global definitions to their own business needs without breaking the baseline.

Step arrow right iconAttaching Criteria to Strategies

Sourcing Criteria are added to Primary or Fallback Sourcing Strategies via the Sourcing Profile GraphQL API, similar to Conditions.

Step arrow right iconBest Practices

  • Order Criteria deliberately: put Exclusion Criteria first, then your primary ranking Criterion, then tie-breakers
  • Provide exact values and enforce strict types via schema-driven components (e.g., units in select, numeric bands)
  • Test boundary and edge cases thoroughly
  • Apply overrides in `fc.rubix.order.sourcing.criteria.custom` when tailoring Criteria for specific Accounts / Retailers