> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Trigger Business Event (V5)
> Fires a registered business event, enqueueing all attached active campaigns and flows for delivery, subject to per-workspace daily and hourly quotas.
- An unknown event name returns a `400 Bad Request`.
- Attribute types are validated against the registered event schema.
- Delivery is asynchronous.
- The response reports how many attached campaigns and flows were triggered compared to how many were skipped due to quota (`failed`), and returns the triggered campaign and flow IDs.
#### Rate Limits
For campaigns:
* You can send a maximum of 10 triggers per 5 minutes.
* You can send a maximum of 50 triggers per hour.
* You can send a maximum of 200 triggers per day.
For flows:
* You can trigger a maximum of 3 business trigger flows per hour.
* You can trigger a maximum of 10 business trigger flows per day.
If you need higher limits, reach out to your Customer Success Manager (CSM) or MoEngage Support team.
#### Example Request
```bash Trigger a Business Event
curl --request POST \
--url 'https://api-01.moengage.com/v5/business-events/triggers' \
--header 'Authorization: Basic ' \
--header 'Content-Type: application/json' \
--header 'X-MOE-Request-Id: 550e8400-e29b-41d4-a716-446655440000' \
--data '{
"event_name": "price_drop",
"triggered_by": "ops@acme.com",
"event_attributes": {
"product_id": "SKU-99321",
"new_price": 349.5,
"dropped_at": "2026-08-03T09:12:00Z"
},
"moe_request_id": "550e8400-e29b-41d4-a716-446655440000"
}'
```
## OpenAPI
````yaml /api/business-events/business-events-v5/business-events-v5.yaml post /v5/business-events/triggers
openapi: 3.0.3
info:
title: MoEngage Business Events API (V5)
description: >
V5 API for triggering business events in a MoEngage workspace and for
looking up the events registered in it.
You can fire a previously created business event so that any campaigns or
flows attached to it are executed. For example, you can trigger a business
event when a new episode of an OTT series becomes available, when there is a
flight delay, or when there is a price drop on an item in a cart. You can
also list the business events in your workspace, or look several up at once
by name or ID.
Served to users through the unified MoEngage gateway, behind a versioned
`{response_id, type, data}` envelope.
To create a new business event, use the [Business Events
(Legacy)](/api/business-events/business-events-legacy/business-events-overview)
API — that operation has not moved to V5 yet.
version: 1.4.0
servers:
- url: https://api-{dc}.moengage.com
description: MoEngage API Server
variables:
dc:
default: '01'
description: >-
The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center
(DC). MoEngage hosts each customer in a different DC. You can find
your DC number and replace the value of ‘dc’ in the URL by referring
to the DC and API endpoint mapping
[here](/api/introduction#data-centers). Your MoEngage Data Center (DC)
can be 01, 02, 03, 04, 05, 06, or 101.
security:
- basicAuth: []
tags:
- name: Business Events
description: >-
Trigger business events registered in the workspace, and look up the
events it contains.
paths:
/v5/business-events/triggers:
post:
tags:
- Business Events
summary: Trigger Business Event (V5)
description: >
Fires a registered business event, enqueueing all attached active
campaigns and flows for delivery, subject to per-workspace daily and
hourly quotas.
- An unknown event name returns a `400 Bad Request`.
- Attribute types are validated against the registered event schema.
- Delivery is asynchronous.
- The response reports how many attached campaigns and flows were
triggered compared to how many were skipped due to quota (`failed`), and
returns the triggered campaign and flow IDs.
operationId: triggerBusinessEvent
parameters:
- $ref: '#/components/parameters/RequestIdHeader'
requestBody:
description: Event to trigger.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessEventTriggerRequest'
example:
event_name: price_drop
triggered_by: ops@acme.com
event_attributes:
product_id: SKU-99321
new_price: 349.5
dropped_at: '2026-08-03T09:12:00Z'
moe_request_id: 550e8400-e29b-41d4-a716-446655440000
responses:
'200':
description: >-
This response is returned when the trigger request is processed
successfully, whether the result is full success, partial success,
or complete failure to reserve the attached campaigns/flows.
headers:
X-MOE-Request-Id:
schema:
type: string
format: uuid
description: >-
Trace ID echoed from the request. Generated by MoEngage when you
do not send one.
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessEventTriggerResponse'
examples:
success:
summary: All attached campaigns/flows were triggered within quota
value:
response_id: 550e8400-e29b-41d4-a716-446655440000
type: business-event
data:
triggered_status: SUCCESS
message: The business event has been triggered
summary:
total: 4
triggered: 4
failed: 0
triggered_campaign_ids:
- 64a1b2c3d4e5f6a7b8c9d0e1
- 64a1b2c3d4e5f6a7b8c9d0e2
- 64a1b2c3d4e5f6a7b8c9d0e3
failed_campaign_ids: []
triggered_flow_ids:
- 64a1b2c3d4e5f6a7b8c9d0f1
failed_flow_ids: []
partial_success:
summary: Some triggered, some skipped due to quota
value:
response_id: 550e8400-e29b-41d4-a716-446655440000
type: business-event
data:
triggered_status: PARTIAL_SUCCESS
message: The business event has been triggered
summary:
total: 4
triggered: 3
failed: 1
triggered_campaign_ids:
- 64a1b2c3d4e5f6a7b8c9d0e1
- 64a1b2c3d4e5f6a7b8c9d0e2
failed_campaign_ids:
- 64a1b2c3d4e5f6a7b8c9d0e3
triggered_flow_ids:
- 64a1b2c3d4e5f6a7b8c9d0f1
failed_flow_ids: []
failed:
summary: Nothing triggered — all skipped by quota
value:
response_id: 550e8400-e29b-41d4-a716-446655440000
type: business-event
data:
triggered_status: FAILURE
message: The business event has been triggered
summary:
total: 4
triggered: 0
failed: 4
triggered_campaign_ids: []
failed_campaign_ids:
- 64a1b2c3d4e5f6a7b8c9d0e1
- 64a1b2c3d4e5f6a7b8c9d0e2
- 64a1b2c3d4e5f6a7b8c9d0e3
triggered_flow_ids: []
failed_flow_ids:
- 64a1b2c3d4e5f6a7b8c9d0f1
'400':
$ref: '#/components/responses/TriggerBadRequest'
'401':
$ref: '#/components/responses/TriggerUnauthorized'
'403':
$ref: '#/components/responses/TriggerForbidden'
'429':
$ref: '#/components/responses/TriggerRateLimited'
'500':
$ref: '#/components/responses/TriggerInternalServerError'
components:
parameters:
RequestIdHeader:
name: X-MOE-Request-Id
in: header
required: false
schema:
type: string
format: uuid
description: >
Client-supplied trace ID (UUID v4). Echoed back in the
`X-MOE-Request-Id` response header and returned unchanged as
`response_id` in the body. When you omit this header, MoEngage generates
a 12-character hexadecimal identifier instead. Quote it when contacting
MoEngage Support.
On [Trigger Business Event
(V5)](/api/business-events/trigger-business-event-v5), the body field
`moe_request_id` takes precedence: when you send both, `response_id`
echoes `moe_request_id`, and this header is returned only in the
`X-MOE-Request-Id` response header.
example: 9f2c1b7a-4d3e-4a08-b5c6-1e7d02f43a91
schemas:
BusinessEventTriggerRequest:
type: object
required:
- event_name
- triggered_by
description: >
Attribute values are validated against the registered attribute schema
(types, presence). Unknown attributes are rejected with a 400.
properties:
event_name:
type: string
description: Name of a business event registered in this workspace.
example: price_drop
triggered_by:
type: string
format: email
description: Email of the user/service firing the event. Required.
example: ops@acme.com
event_attributes:
type: object
additionalProperties: true
description: >
Attribute values for this firing, keyed by attribute name. Types
must match the registered schema (string, number, boolean,
datetime).
example:
product_id: SKU-99321
new_price: 349.5
dropped_at: '2026-08-03T09:12:00Z'
moe_request_id:
type: string
format: uuid
description: >
Optional request id, returned unchanged as `response_id` and used
for tracing. This field takes precedence over the `X-MOE-Request-Id`
header — when you send both, `response_id` echoes this value, and
the header value is returned only in the `X-MOE-Request-Id` response
header.
example: 550e8400-e29b-41d4-a716-446655440000
BusinessEventTriggerResponse:
type: object
properties:
response_id:
type: string
description: >
Echo of the caller-supplied `moe_request_id`, returned unchanged.
When you omit `moe_request_id`, it echoes the `X-MOE-Request-Id`
header instead; when you send neither, MoEngage generates a
12-character hexadecimal identifier.
example: 5f3e2a1b9c8d
type:
type: string
enum:
- business-event
example: business-event
data:
$ref: '#/components/schemas/BusinessEventTriggerData'
BusinessEventTriggerData:
type: object
properties:
triggered_status:
type: string
enum:
- SUCCESS
- PARTIAL_SUCCESS
- FAILURE
description: >
- SUCCESS: every attached campaign/flow was triggered.
- PARTIAL_SUCCESS: at least one triggered, at least one skipped by
quota.
- FAILURE: nothing triggered (all skipped by quota, or the event has
no active campaigns/flows attached).
example: SUCCESS
message:
type: string
description: >
Human-readable summary of the outcome. Branch on `triggered_status`
and `summary` rather than on this text.
example: The business event has been triggered
summary:
type: object
properties:
total:
type: integer
description: Total attached active campaigns and flows considered.
example: 12
triggered:
type: integer
description: >-
Count triggered (sum of `triggered_campaign_ids` and
`triggered_flow_ids`).
example: 12
failed:
type: integer
description: >-
Count skipped by quota (sum of `failed_campaign_ids` and
`failed_flow_ids`).
example: 0
triggered_campaign_ids:
type: array
description: >-
Base-version campaign IDs that were triggered. Bare 24-character
hexadecimal ObjectIds, with no resource prefix.
items:
type: string
example: 64a1b2c3d4e5f6a7b8c9d0e1
example:
- 64a1b2c3d4e5f6a7b8c9d0e1
- 64a1b2c3d4e5f6a7b8c9d0e2
failed_campaign_ids:
type: array
description: >-
Base-version campaign IDs that were skipped by quota. Bare
24-character hexadecimal ObjectIds, with no resource prefix.
items:
type: string
example: 64a1b2c3d4e5f6a7b8c9d0e3
example: []
triggered_flow_ids:
type: array
description: >-
Base-version flow IDs that were triggered. Bare 24-character
hexadecimal ObjectIds, with no resource prefix.
items:
type: string
example: 64a1b2c3d4e5f6a7b8c9d0f1
example:
- 64a1b2c3d4e5f6a7b8c9d0f1
failed_flow_ids:
type: array
description: >-
Base-version flow IDs that were skipped by quota. Bare 24-character
hexadecimal ObjectIds, with no resource prefix.
items:
type: string
example: 64a1b2c3d4e5f6a7b8c9d0f1
example: []
TriggerErrorResponse:
type: object
properties:
response_id:
type: string
example: 5f3e2a1b9c8d
error:
type: object
properties:
code:
type: string
description: Machine-readable, UPPER_SNAKE_CASE error code.
example: VALIDATION_FAILED
message:
type: string
description: Human-readable error message.
example: One or more fields failed validation.
target:
type: string
description: >-
The request field, query parameter, or header that caused the
error.
example: event_attributes.new_price
details:
type: array
description: >-
Field-level breakdown of what failed validation. Returned for
validation errors only; absent on 401, 403, and 429.
items:
type: object
properties:
code:
type: string
description: >-
Machine-readable UPPER_SNAKE_CASE code for this specific
violation. More granular than the top-level `code`.
example: INVALID_TYPE
target:
type: string
description: The specific parameter or field this violation applies to.
example: event_attributes.new_price
message:
type: string
description: Human-readable description of this violation.
example: Expected number, got string.
responses:
TriggerBadRequest:
description: >-
This response is returned when the required parameters are missing from
the request or when the provided parameters are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerErrorResponse'
examples:
invalidEventAttribute:
summary: An event attribute failed validation
value:
response_id: 43df15004501
error:
code: VALIDATION_FAILED
message: Wrong business event attribute passed in api request
target: event_attributes.product_id
details:
- code: INVALID_VALUE
target: event_attributes.product_id
message: Wrong business event attribute passed in api request
unknownEventName:
summary: The business event is not registered in the workspace
value:
response_id: a02e573f65c2
error:
code: VALIDATION_FAILED
message: Business event does not exists
target: event_name
details:
- code: INVALID_VALUE
target: event_name
message: Business event does not exists
TriggerUnauthorized:
description: >-
This response is returned when the authorization parameters are missing
or incorrect in the HTTP Auth Header.
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerErrorResponse'
example:
response_id: 5f3e2a1b9c8d
error:
code: AUTHENTICATION_REQUIRED
message: >-
Workspace ID and API key are missing from the Authorization
header.
TriggerForbidden:
description: >
Missing required scope. Your credentials authenticated successfully, but
the API key does not carry the scope needed to trigger business events.
Check the key's scopes — rotating or re-sending the same key will not
help. Create a key with the required access in the MoEngage dashboard at
**Settings** > **Account** > **API keys**.
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerErrorResponse'
example:
response_id: 5f3e2a1b9c8d
error:
code: FORBIDDEN
message: >-
This API key does not have the scope required to trigger
business events.
target: Authorization
TriggerRateLimited:
description: >-
This response is returned when the number of requests has exceeded the
rate limit.
headers:
Retry-After:
description: Number of seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerErrorResponse'
example:
response_id: 5f3e2a1b9c8d
error:
code: RATE_LIMIT_EXCEEDED
message: Exceeded rate limit for this workspace.
TriggerInternalServerError:
description: This response is returned when the system runs into an unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerErrorResponse'
example:
response_id: 5f3e2a1b9c8d
error:
code: INTERNAL_ERROR
message: >-
An unexpected error occurred while processing the request. Retry
the request, and quote `response_id` if you contact MoEngage
Support.
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >
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 MoEngage dashboard at **Settings** > **Account** >
**API keys**.
- **Password**: Use an API key from **Settings** > **Account** > **API
keys**.
Refer to [API Key
Dashboard](/user-guide/settings/account/api-and-api-keys/api-key-dashboard)
for details on creating and managing API keys.
````