Sports Inventory Hierarchy

This page explains what the Sports Inventory model is—what each entity represents, how Optimove Personalize uses it, and the conventions and gotchas that are not obvious from the field list alone.

The six entities

Sports Inventory has six entity types. Each child references its parent by key:

Category.categoryKey
└── Class.categoryKey
    └── Type.classKey
        └── Event.typeKey
            └── Market.eventKey
                └── Selection.marketKey

Global conventions

• Keys are yours, and they are identity. They must be non-empty where required, stable, and unique for that entity type within the brand feed.
• Treat keys as immutable. To replace a key, create the new entity and then remove the old one—do not repurpose an existing key.
• Names are public. They are display labels and are used by search and recommendation output.
• Translation fields are JSON objects of strings, for example {"en":"Football","es":"Fútbol"}. Agree locale-key conventions during onboarding.
• displayOrder is an integer, lower values first per the API contract—but configured Personalize experiences can apply additional ranking on top of it, so do not treat it as the final order.
• Case matters. displayStatus is Displayed or NotDisplayed; entity status is Active or Inactive. These are case-sensitive.
• Do not rely on fields not documented in the API Reference. Undocumented fields have no contract.

Parent-propagation gotcha: the API contract describes NotDisplayed on a parent as applying to its children. For predictable results across configured models, still keep the affected child records' display and status values accurate—do not rely on parent propagation alone.

Denormalized parent context

Beyond the direct parent key that every child requires, Type, Event, and Market accept optional denormalized ancestor keys (for example categoryKey/classKey on an Event). These are a convenience for your own pipeline.

Event timing and lifecycle

Events carry the model's time awareness, and this is where the least-obvious behavior lives.

• eventDateTime must include a timezone. Accepted offsets include Z, ±hh, ±hhmm, and ±hh:mm. It drives future/in-play logic, ordering, and minutes-to-start calculations.
• isEventStarted should be sent true once the event has started; it feeds in-play state, search behavior, and configured ordering.
• eventEndDateTime has a defaulting rule you must plan for. It is optional and UTC (Z or +0000). If omitted, the effective end is eventDateTime + 24 hours. An end before the start is coerced to that same 24-hour default. Inventory lifecycle processing uses the effective end, so an event with a real duration longer or shorter than 24 hours needs an explicit eventEndDateTime.
• isEventFinished stores the provider's completion state, but not every model path consumes it directly—set it accurately, but do not assume it alone removes an event from results.

Provider-specific fields—agree during onboarding

Several fields carry provider-specific values with no universal enum in the public contract. Their meaning must be agreed during onboarding; do not assume a fixed vocabulary:

Selection display and status

Selection is the entity recommendation APIs return, so two of its fields behave more strictly than their equivalents higher up:

• displayStatus is required on a Selection and directly filters displayability in common recommendation paths—it is not just advisory metadata.
• displayOrder is combined with price as an additional ordering signal in configured paths.

Selection pricing

Pricing is the most behavior-heavy part of the model. A Selection can be priced as fractional (numPrice/denPrice), decimal (decPrice), or left explicitly unpriced. The valid shapes accepted on create (POST):

Zero-numerator gotcha: although the request schema accepts a zero numerator, the current runtime does not derive decimal odds from a zero-valued fractional pair. For a priced Selection, send a positive numerator, a positive denominator, and a consistent decPrice.

On update (PUT), automatic decimal derivation is not guaranteed. When changing odds, always send numPrice, denPrice, and a consistent decPrice together—see the PUT operation in the Sports Inventory API Reference. Do not update only the numerator or only the denominator; the fractional pair must stay consistent.

extra pass-through

Every entity accepts a free-form extra JSON object, passed through for configured customer use (for example participant extraction on Events).

• Do not place secrets or sensitive personal data in extra.
• A PUT replaces the whole extra object—it does not merge. Retain your authoritative copy before sending an update meant to preserve existing keys.