Update Offering

Modify an existing offering. Only the fields you include in the request body are changed.

PATCH /v5/offers/{offer_id}

cURL

extendExpiry

curl --request PATCH \
  --url https://api-{dc}.moengage.com/v5/offers/{offer_id} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "updated_by": "[e-mail]",
  "scheduling": {
    "expiry_datetime": "2026-12-31T23:59:59Z"
  }
}
'

200

Example

{
  "response_id": "resp_c5f83262-3127-4e23-bb1b-9efd4c929e12",
  "type": "offer",
  "data": {
    "id": "offer_6a4f69ee490f66322f968b87",
    "status": "active",
    "updated_at": "2026-07-09T09:29:18.526812352Z"
  }
}

Rate Limit

The rate limit is 100 requests per minute, 300 requests per hour, and 600 requests per day per consumer.

Authorizations

Authorization · string · header · required

Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'.

• Username: Use your MoEngage Workspace ID (also known as the App ID). Find it in the dashboard at Settings > Account > APIs > Workspace ID (earlier app id).
• Password: On your MoEngage workspace, navigate to Settings > Account > API keys. Use the Key listed within the Personalize tile.

For more information on authentication and getting your credentials, refer to Getting your credentials. Send the value in the Authorization header as Basic followed by Base64-encoding of appkey:apisecret (workspace ID and API key).

Headers

Idempotency-Key · string<uuid> · required

UUID v4 idempotency token. Submitting the same key within 24 hours returns the original 200 response without re-creating the Offering. A different body hash on the same key returns 409 IDEMPOTENCY_CONFLICT. A concurrent in-progress request with the same key returns 409 DUPLICATE_IDEMPOTENCY_KEY.

X-MOE-Request-Id · string<uuid>

Client-supplied trace ID (UUID v4). Echoed back in the X-MOE-Request-Id response header. Use this to correlate client requests with server-side logs.

Path Parameters

offer_id · string · required

The unique ID of the offering to be updated. You can fetch the offering ID using the List Offerings API by filtering with name.

Body

application/json

Request body for partially updating an existing offering via the public API (PATCH /v5/offers/{offer_id}). Only the fields explicitly provided in the request body will be modified.

Some fields are status-gated based on the offering's current lifecycle phase — see the field-level descriptions for variation_meta, conversion, and scheduling for the exact rules. Modifying a locked field returns a 400 IMMUTABLE_FIELD error.

updated_by · string<email> · required

Email address of the team member making this update.

Example:

"[e-mail]"

name · string

Updated display name for the offering. Must remain unique within the workspace. Allowed characters: alphanumeric characters and underscores (_) only.

Required string length: 5 - 100

description · string

Updated free-text description of the offering's purpose.

Maximum string length: 500

priority · integer

Updated static priority score.

Required range: 1 <= x <= 100

tags · string[]

Full replacement, not additive — the entire existing tag list is overwritten with this value. To add a single tag, send the complete current tag list plus the new tag. To remove all tags, send an empty array.

Maximum array length: 10

Maximum string length: 50

scheduling · object

Partial scheduling update for PATCH operations. All fields are optional. start_datetime can only be changed when offering status is scheduled. expiry_datetime can be updated only when offering status is active or scheduled.

Show child attributes

segment_info · object

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, send an empty filters object: { "filters": {} }

Show child attributes

offer_content · object

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 variation_meta.variantsPerLocale and smv_distribution.split.

Show child attributes

Example:

{
  "content_1": {
    "type": "json",
    "value": "{\"headline\":\"Save 20% today\",\"cta_text\":\"Claim offer\",\"image_url\":\"https://cdn.example.com/banner.png\",\"cta_url\":\"https://example.com/offer/summer\"}"
  }
}

variation_meta · object

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.

Offering Status	Variation Type	Editable Fields	Locked Fields
scheduled	Any	Entire object (type, variantsPerLocale, smv_distribution, control_group)	None
active	SMV	smv_distribution.split percentages, control_group.percentage	type, Variant key names
active	DMV	control_group.percentage	type, variantsPerLocale, smv_distribution
expired	Any	None	All fields are locked

Show child attributes

Example:

{
  "type": "SMV",
  "variantsPerLocale": ["Variant_A", "Variant_B"],
  "smv_distribution": {
    "split": { "Variant_A": 70, "Variant_B": 30 }
  },
  "control_group": { "is_enabled": true, "percentage": 10 }
}

capping_rules · object

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.

Show child attributes

Example:

{
  "overall": {
    "enabled": true,
    "limit_value": 10000,
    "limit_schedule": "DAILY"
  },
  "user_level": {
    "enabled": true,
    "limit_value": 3,
    "limit_schedule": "WEEKLY"
  }
}

is_global_control_enabled · boolean

Toggle GCG holdout exclusion. When true, GCG members are excluded from receiving this offering. When false, all eligible users can receive it.

imp_track_hours · integer

Updated impression de-duplication window in hours (1 to 240).

Required range: 1 <= x <= 240

offering_attribute_configuration · object[]

Replacement custom attribute configuration. This is a FULL REPLACEMENT — the entire existing attribute list is overwritten. At most 5 attributes.

Maximum array length: 5

Show child attributes

conversion · object

List of conversion goals to track.

Status constraint: conversion can only be set or updated while the offering status is scheduled. Attempting to update it on an active or expired offering returns a 400 IMMUTABLE_FIELD error.

Show child attributes

Response

200

application/json

Offering updated successfully.

Response returned by PATCH /v5/offers/{offer_id} on successful update.

response_id · string

Format: resp_<X-MOE-Request-Id> header value (auto-generated UUID if the X-MOE-Request-Id header was not part of the request body).

Example:

"resp_c5f83262-3127-4e23-bc1b-9efd4c929e12"

type · enum<string>

Available options: offer

data · object

Updated offering summary.

Show child attributes