Create Offering - MoEngage

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/offers \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "Summer_Sale",
  "description": "Summer sale discount offers",
  "priority": 50,
  "delivery": "scheduled",
  "created_by": "john.doe@example.com",
  "scheduling": {
    "start_datetime": "2026-07-16T00:00:00Z",
    "expiry_datetime": "2026-07-16T23:59:00Z",
    "timezone": "Asia/Kolkata"
  },
  "segment_info": {
    "filters": {
      "included_filters": {
        "filter_operator": "and",
        "filters": [
          {
            "filter_type": "custom_segments",
            "name": "level_0_for_automation",
            "id": "6a572827fad010a3318a1bc1"
          }
        ]
      }
    }
  },
  "offer_content": {
    "content_1": {
      "type": "json",
      "value": "{\"discount\":\"10%\"}"
    }
  },
  "variation_meta": {
    "type": "SMV",
    "variantsPerLocale": [
      "Variant_A"
    ],
    "control_group": {
      "is_enabled": false,
      "percentage": 0
    },
    "smv_distribution": {
      "split": {
        "Variant_A": 100
      }
    }
  },
  "capping_rules": {},
  "is_global_control_enabled": false,
  "imp_track_hours": 36
}
'

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

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed.",
    "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview",
    "details": [
      {
        "code": "REQUIRED_FIELD_MISSING",
        "target": "variation_meta",
        "message": "variation_meta is required.",
        "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview"
      },
      {
        "code": "INVALID_SCHEDULING",
        "target": "scheduling",
        "message": "expiry_datetime must be after start_datetime.",
        "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview"
      },
      {
        "code": "INVALID_TEMPLATE_ID",
        "target": "offer_content.locales.0.variations.Variant_A.content_1.meta.templateId",
        "message": "Template 'app_large' is not registered in this workspace.",
        "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview"
      },
      {
        "code": "MISSING_TEMPLATE_FIELD",
        "target": "offer_content.locales.0.variations.Variant_A.content_1.value.cta_url",
        "message": "Field 'cta_url' is required by the template but is missing or blank.",
        "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview"
      }
    ]
  },
  "response_id": "resp_<trace-id>"
}

"<string>"

"{\"code\":\"ER001\",\"target\":\"Authentication Invalid\",\"message\":\"Auth validation failed.\"}"

{
  "response_id": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview",
    "target": "<string>",
    "details": [
      {
        "code": "<string>",
        "target": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "response_id": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview",
    "target": "<string>",
    "details": [
      {
        "code": "<string>",
        "target": "<string>",
        "message": "<string>"
      }
    ]
  }
}

"<html><body><h1>503 Service Temporarily Unavailable</h1></body></html>"

POST

offers

curl --request POST \
  --url https://api-{dc}.moengage.com/v5/offers \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "Summer_Sale",
  "description": "Summer sale discount offers",
  "priority": 50,
  "delivery": "scheduled",
  "created_by": "john.doe@example.com",
  "scheduling": {
    "start_datetime": "2026-07-16T00:00:00Z",
    "expiry_datetime": "2026-07-16T23:59:00Z",
    "timezone": "Asia/Kolkata"
  },
  "segment_info": {
    "filters": {
      "included_filters": {
        "filter_operator": "and",
        "filters": [
          {
            "filter_type": "custom_segments",
            "name": "level_0_for_automation",
            "id": "6a572827fad010a3318a1bc1"
          }
        ]
      }
    }
  },
  "offer_content": {
    "content_1": {
      "type": "json",
      "value": "{\"discount\":\"10%\"}"
    }
  },
  "variation_meta": {
    "type": "SMV",
    "variantsPerLocale": [
      "Variant_A"
    ],
    "control_group": {
      "is_enabled": false,
      "percentage": 0
    },
    "smv_distribution": {
      "split": {
        "Variant_A": 100
      }
    }
  },
  "capping_rules": {},
  "is_global_control_enabled": false,
  "imp_track_hours": 36
}
'

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

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed.",
    "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview",
    "details": [
      {
        "code": "REQUIRED_FIELD_MISSING",
        "target": "variation_meta",
        "message": "variation_meta is required.",
        "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview"
      },
      {
        "code": "INVALID_SCHEDULING",
        "target": "scheduling",
        "message": "expiry_datetime must be after start_datetime.",
        "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview"
      },
      {
        "code": "INVALID_TEMPLATE_ID",
        "target": "offer_content.locales.0.variations.Variant_A.content_1.meta.templateId",
        "message": "Template 'app_large' is not registered in this workspace.",
        "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview"
      },
      {
        "code": "MISSING_TEMPLATE_FIELD",
        "target": "offer_content.locales.0.variations.Variant_A.content_1.value.cta_url",
        "message": "Field 'cta_url' is required by the template but is missing or blank.",
        "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview"
      }
    ]
  },
  "response_id": "resp_<trace-id>"
}

"<string>"

"{\"code\":\"ER001\",\"target\":\"Authentication Invalid\",\"message\":\"Auth validation failed.\"}"

{
  "response_id": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview",
    "target": "<string>",
    "details": [
      {
        "code": "<string>",
        "target": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "response_id": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "doc_url": "https://www.moengage.com/docs/api/offerings/offerings-overview",
    "target": "<string>",
    "details": [
      {
        "code": "<string>",
        "target": "<string>",
        "message": "<string>"
      }
    ]
  }
}

"<html><body><h1>503 Service Temporarily Unavailable</h1></body></html>"

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 201 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.

Body

application/json

Request body for creating an Offering via POST /v5/offers.

Required fields: name, priority, delivery, created_by, scheduling, segment_info, offer_content, variation_meta.

name

string

required

Unique display name for this offering within the workspace. Names are case-sensitive and must be unique. Allowed characters: alphanumeric characters and underscores (_).

Required string length: 5 - 100

Example:

"Summer_Sale_Promo_2026"

priority

integer

required

Static priority score for offer ranking. Lower number means lower priority (1 is lowest priority, 100 is highest). This score is used when the Decision Policy ranking strategy is set to Offering Priority.

Required range: 1 <= x <= 100

delivery

enum<string>

required

Controls when the offering is eligible for delivery. scheduled — the offering is served within its scheduling window.

Available options:

scheduled

created_by

string<email>

required

Email address of the user creating this offering.

Example:

"marketing-team@example.com"

scheduling

object

required

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

Show child attributes

segment_info

object

required

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

required

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

required

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 }
}

description

string

Optional free-text description of the offering's purpose, targeting rationale, or expected user experience. Visible in the MoEngage UI offering list.

Maximum string length: 500

Example:

"20% discount for returning users who have not purchased in 30 days"

Response

Offering created successfully.

Response returned by POST /v5/offers on successful creation.

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>

Resource type discriminator. Always offer.

Available options:

offer

data

object

Created offering summary.

Show child attributes

List Offerings Update Offering

⌘I

​Rate Limit

Authorizations

Headers

Body

1. Flat Format (No Content Variations)

2. Nested Format (Multiple Content Variations)

Lifecycle & Mutation Rules

Response

Rate Limit