Create Offering

Scheduling window that determines when an offering is eligible for delivery. Both start_datetime and expiry_datetime are required when creating an offering.

Segment targeting configuration that controls which users are eligible to receive this offering.

included_filters: criteria a user MUST match to be eligible. excluded_filters: criteria that DISQUALIFY a user even if they match the included filters.

To target all users, use the built-in moe_all_users segment:

{
  "filters": {
    "included_filters": {
      "filter_operator": "and",
      "filters": [
        {
          "filter_type": "custom_segments",
          "id": "moe_all_users",
          "name": "All Users"
        }
      ]
    }
  }
}

The core content payload delivered to the end-user. This object supports two mutually exclusive structures depending on whether your offering uses content variations or experimentation.

Mutually Exclusive: Do not provide both content_1 and locales in the same request payload. Doing so will result in a validation error.

1. Flat Format (No Content Variations)

Use this structure for simple offerings that do not require A/B testing or localization.

• Payload Structure: Send a single content_1 object at the root level.
• Behavior: The exact same content block is served universally to all eligible users.

2. Nested Format (Multiple Content Variations)

Use this structure when variation_meta.type is configured as either SMV (Static Multi-Variant) or DMV (Dynamic Multi-Variant).

• Payload Structure: Send a structured locales map object.
• Single-Locale Targeting: For single-locale offerings, you must use "0" as the literal locale key string.
• Variations Mapping: Inside each locale, the nested variations map keys must exactly match the variation IDs defined in smv_distribution.split. Variation keys must follow the variation_N format (e.g. variation_1, variation_2).

Configuration for A/B testing content variations.

• SMV: Fixed percentage splits across up to 5 variations.
• DMV: The system automatically learns which variant performs best over time and shifts traffic toward the winner.
• Offer Control Group: A configurable percentage of eligible users to be held out as a pure control group.

Lifecycle & Mutation Rules

variation_meta can be edited later via PATCH /v5/offers/{offer_id}, subject to status-based rules. Field mutability depends on both the offering status and the variation type. Attempting to modify a locked field returns a 400 IMMUTABLE_FIELD error.

Frequency capping configuration that limits how often this offering is delivered. Two independent capping rules can be configured and enabled simultaneously.

overall: Limits the TOTAL number of times the offering is delivered across ALL users in the target segment within the capping schedule period.

user_level: Limits the number of times any SINGLE user can receive the offering within the capping schedule period.

Conversion goal configuration for measuring offering effectiveness. This can be set at creation time or later via PATCH while the offering is still in "scheduled" status. Once the offering goes "active", the conversion configuration is locked to preserve Thompson Sampling statistical integrity.

Created offering summary.