> ## 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.
# Update Campaign Status (V5)
> Applies a state transition to a published campaign. Supported for **Email** and **Push** campaigns.
`PUBLISH` is not accepted on this endpoint. To publish a draft, use `PATCH /v5/campaigns/{campaign_id}` with `{ "status": "PUBLISH" }`.
The response does not include the resulting campaign status. To confirm the new state after a transition, call `GET /v5/campaigns/{campaign_id}`.
#### Rate Limits
| Rate Limit Name | Rate Limit |
| :-------------------------------- | :---------------------------------------------------------------------------------------- |
| change campaign status per second | The total number of change campaign status requests per second per client is 10. |
| change campaign status per minute | The total number of change campaign status requests per minute per client allowed is 100. |
| change campaign status per hour | The total number of change campaign status requests per hour per client allowed is 6000. |
**Notes**
* Breaching the limits will reject the request.
* Per-hour and per-day limits use a rolling window of the last 1 hour and last 24 hours respectively.
## OpenAPI
````yaml /api/campaigns/campaign-draft.yaml patch /v5/campaigns/{campaign_id}/status
openapi: 3.0.3
info:
title: MoEngage Campaigns API
version: '2025-11-20'
description: >
The Campaigns V5 API manages the full campaign lifecycle - draft creation,
incremental updates, validation, test sends, publication, and post-publish
management.
**Supported channels:**
- Push (Android, iOS, Web)
- Email
**Supported delivery types:**
- ONE_TIME
- PERIODIC
- EVENT_TRIGGERED
- BUSINESS_EVENT_TRIGGERED
- DEVICE_TRIGGERED (Push only)
- LOCATION_TRIGGERED (Push only)
- BROADCAST_LIVE_ACTIVITY (Push iOS only)
**Campaign lifecycle:**
1. **Create** - Start a draft with only the required fields (`channel`,
`campaign_delivery_type`, `created_by`). Add content, audience, and
scheduling incrementally across subsequent update calls.
2. **Update** - Patch individual components as you refine the setup. Each
submitted component is validated in full before the draft is updated.
3. **Validate** - Check whether a draft would pass publish-time validation
without committing any changes.
4. **Test** - Send a test message to specific users from either a saved
draft or inline content before going live.
5. **Publish** - Transition the draft to **ACTIVE** by sending `{ "status":
"PUBLISH" }` in a PATCH request.
6. **Manage** - Pause, resume, or stop a live campaign. Search your
workspace and retrieve lightweight metadata across all campaigns.
**Campaign versioning** is optional per workspace:
- When enabled, publishing an update to a live campaign creates a new
document with an incremented `version_number`.
- `campaign_id` is the stable identifier across all versions; each version
has its own raw `id` (ObjectId).
**Header change from V1 to V5:** The `MOE-APPKEY` request header is replaced
by `X-MOE-Tenant-ID` in V5.
- `X-MOE-Tenant-ID` is optional. When omitted, the workspace is resolved
from the Basic Auth credentials in the `Authorization` header.
- If you set the workspace via a header, use `X-MOE-Tenant-ID` in V5 in
place of `MOE-APPKEY`.
contact:
name: MoEngage Developer Team
email: support@moengage.com
url: https://developers.moengage.com
servers:
- url: https://api-{dc}.moengage.com/
description: MoEngage Campaigns API Server
variables:
dc:
default: '01'
description: >-
Data center (DC) segment in the hostname. Replace `OX` with your
workspace DC (01–06 or 101). See [Data
centers](/api/introduction#data-centers).
security:
- BasicAuth: []
paths:
/v5/campaigns/{campaign_id}/status:
patch:
tags:
- Update Campaigns
summary: Update Campaign Status (V5)
description: >
Applies a state transition to a published campaign. Supported for
**Email** and **Push** campaigns.
operationId: change_campaign_status_v5
parameters:
- $ref: '#/components/parameters/X-MOE-Tenant-ID'
- $ref: '#/components/parameters/X-MOE-Request-Id'
- name: campaign_id
in: path
required: true
description: Raw 24-char ObjectId of the published campaign to transition.
schema:
type: string
- $ref: '#/components/parameters/Idempotency-Key-Required'
requestBody:
description: Send campaign status change request with action.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignStatusV5Request'
examples:
stop_campaign:
summary: Stop a campaign
value:
request_id: '{{request_id}}'
action: STOP
pause_campaign:
summary: Pause a campaign
value:
request_id: '{{request_id}}'
action: PAUSE
resume_campaign:
summary: Resume a campaign
value:
request_id: '{{request_id}}'
action: RESUME
responses:
'200':
description: Transition accepted.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/V5SuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/CampaignStatusTransitionData'
example:
response_id: abc-601
type: campaign
data:
id: 64a1b2c3d4e5f6a7b8c9d0e1
action: STOP
'400':
$ref: '#/components/responses/V5ValidationError'
'401':
$ref: '#/components/responses/V5Unauthorized'
'422':
description: >
The action is not valid for the campaign's current state or delivery
type. Common causes:
- Attempting `STOP` on a Periodic campaign.
- Attempting `PAUSE` or `RESUME` on a One-time campaign.
- Attempting `RESUME` on a campaign that is not in `PAUSED` state.
- Attempting `PAUSE` on a campaign that is not in `ACTIVE`,
`SCHEDULED`, or `SENDING` state.
content:
application/json:
schema:
$ref: '#/components/schemas/V5ErrorEnvelope'
example:
response_id: abc-422
error:
code: UNPROCESSABLE_ENTITY
message: Action STOP is not valid for a PERIODIC campaign.
details: []
'500':
$ref: '#/components/responses/V5InternalError'
components:
parameters:
X-MOE-Tenant-ID:
name: X-MOE-Tenant-ID
in: header
required: false
description: >
Workspace tenant ID. Set this to the workspace (App) ID from
**Settings** > **Account** > **APIs** > **Workspace ID**.
This header is optional. When omitted, the API resolves the workspace
from the Basic Auth credentials in the `Authorization` header.
In the V1 Campaigns API, the workspace ID was passed via the
`MOE-APPKEY` request header. In V5, this header is renamed to
`X-MOE-Tenant-ID`.
schema:
type: string
example: '{{workspace_id}}'
X-MOE-Request-Id:
name: X-MOE-Request-Id
in: header
required: true
description: >
Correlates with `response_id`. Supply this header or `request_id` in the
body; if both are set, they must match.
schema:
type: string
Idempotency-Key-Required:
name: Idempotency-Key
in: header
required: true
description: >
UUID v4. Required on all `POST` and `PATCH` requests except `POST
/v5/campaigns/{campaign_id}/validate`. Repeating the same key returns
the same response body.
schema:
type: string
format: uuid
schemas:
CampaignStatusV5Request:
type: object
description: >-
Changes the status of a single published campaign. One campaign ID per
request.
required:
- action
properties:
request_id:
type: string
description: A unique identifier for this status change request.
action:
type: string
enum:
- STOP
- PAUSE
- RESUME
description: >
Lifecycle action for an already published or scheduled campaign.
Each action applies only to specific delivery types and requires the
campaign to be in a valid source state:
| Action | Supported delivery types | Valid source states |
| :--- | :--- | :--- |
| `STOP` | `ONE_TIME` | `ACTIVE`, `SCHEDULED`, `PAUSED`, `SENDING` |
| `PAUSE` | `PERIODIC`, `EVENT_TRIGGERED` | `ACTIVE`, `SCHEDULED`,
`SENDING` |
| `RESUME` | `PERIODIC`, `EVENT_TRIGGERED` | `PAUSED` |
`STOP` cannot be used on Periodic campaigns. `PAUSE` and `RESUME` cannot be used on One-time campaigns.
V5SuccessEnvelope:
type: object
properties:
response_id:
type: string
type:
type: string
example: campaign
data:
type: object
CampaignStatusTransitionData:
type: object
required:
- id
- action
description: Returned after a successful status transition on a published campaign.
properties:
id:
type: string
description: Raw 24-character campaign ObjectId.
example: 64a1b2c3d4e5f6a7b8c9d0e1
action:
type: string
description: The action that was applied (matches the requested action).
enum:
- STOP
- PAUSE
- RESUME
V5ErrorEnvelope:
type: object
properties:
response_id:
type: string
error:
type: object
properties:
code:
type: string
enum:
- VALIDATION_FAILED
- UNPROCESSABLE_ENTITY
- BAD_REQUEST
- RATE_LIMITED
- UNAUTHORIZED
- INTERNAL_ERROR
- FORBIDDEN
message:
type: string
target:
type: string
details:
type: array
items:
type: object
properties:
target:
type: string
message:
type: string
request_id:
type: string
description: >
The `request_id` from the originating request. Use this to
correlate a failed response back to the specific call that
triggered it, particularly useful in high-volume or retry
scenarios.
In V1, `request_id` appeared inside the `error` object. V5
preserves this field in the same location.
responses:
V5ValidationError:
description: Request failed schema or component validation.
content:
application/json:
schema:
$ref: '#/components/schemas/V5ErrorEnvelope'
example:
response_id: abc-101
error:
code: VALIDATION_FAILED
message: One or more fields failed validation.
request_id: req-push-001
details:
- target: campaign_delivery_type
message: campaign_delivery_type value is required.
V5Unauthorized:
description: Authentication failure.
content:
application/json:
schema:
$ref: '#/components/schemas/V5ErrorEnvelope'
example:
response_id: abc-101
error:
code: UNAUTHORIZED
message: Invalid or missing credentials.
details: []
V5InternalError:
description: Unhandled server-side failure.
content:
application/json:
schema:
$ref: '#/components/schemas/V5ErrorEnvelope'
example:
response_id: abc-101
error:
code: INTERNAL_ERROR
message: Internal server error.
details: []
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). You can find it in the MoEngage dashboard at **Settings** >
**Account** > **APIs** > **Workspace ID (earlier app id)**.
- **Password**: On your MoEngage workspace, navigate to **Settings** →
**Account** → **API keys** and click **Create new key**. The tab lists
every API surface (Data, Segmentation, Push, Email, Campaigns,
Templates, and more) and exposes per-resource actions. For Campaigns,
ensure the **View**, **Create & Manage**, and **Create, Manage &
Publish** checkboxes are selected.
For more information on authentication and getting your credentials,
refer to [Getting your
credentials](/api/introduction#getting-your-credentials).
Send the value in the `Authorization` header as `Basic` followed by
Base64-encoding of `appkey:apisecret` (workspace ID and API key).
````