---
title: "Cancel a batch message"
method: DELETE
path: "/xms/v1/{service_plan_id}/batches/{batch_id}"
tags: ["Batches"]
---

# Cancel a batch message

`DELETE /xms/v1/{service_plan_id}/batches/{batch_id}`

A batch can be canceled at any point. If a batch is canceled while it's currently being delivered some messages currently being processed might still be delivered. The delivery report will indicate which messages were canceled and which weren't.

Canceling a batch scheduled in the future will result in an empty delivery report while canceling an already sent batch would result in no change to the completed delivery report.

## Response `200`

Batch deleted or an [Error](https://developers.sinch.com/docs/sms/api-reference/status-codes).

- union
  - TextResponse
    - `id` string — Unique identifier for batch
    - `to` MtDestination[] — List of Phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)
    - `from` string — Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured.
    - `canceled` boolean — Indicates if the batch has been canceled or not.
    - `parameters` ParameterObj — Contains the parameters that will be used for customizing the message for each recipient. [Click here to learn more about parameterization](https://developers.sinch.com/docs/sms/resources/message-info/message-parameterization).
    - `body` string — The message content
    - `type` 'mt_text', required — Regular SMS
    - `created_at` string, date-time — Timestamp for when batch was created. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):`YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `modified_at` string, date-time — Timestamp for when batch was last updated. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):`YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `delivery_report` 'none' | 'summary' | 'full' | 'per_recipient' | 'per_recipient_final' — Kind of delivery report
    - `send_at` string, date-time — If set in the future, the message will be delayed until `send_at` occurs. Must be before `expire_at`. If set in the past, messages will be sent immediately. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `expire_at` string, date-time — If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `callback_url` string — Override the default callback URL for this batch. Must be valid URL.
    - `client_reference` string — The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
    - `feedback_enabled` boolean — If set to `true`, then [feedback](https://developers.sinch.com/docs/sms/api-reference/sms/batches/deliveryfeedback) is expected after successful delivery.
    - `flash_message` boolean — Shows message on screen without user interaction while not saving the message to the inbox.
    - `truncate_concat` boolean — If set to `true` the message will be shortened when exceeding one part.
    - `max_number_of_message_parts` integer — Message will be dispatched only if it is not split to more parts than Max Number of Message Parts
    - `from_ton` integer — The type of number for the sender number. Use to override the automatic detection.
    - `from_npi` integer — Number Plan Indicator for the sender number. Use to override the automatic detection.
  - BinaryResponse
    - `id` string — Unique identifier for batch.
    - `to` MtDestination[] — A list of phone numbers and group IDs that have received the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628).
    - `from` string — The sender number provided. Required if the Automatic Default Originator is not configured.
    - `canceled` boolean — Indicates whether or not the batch has been canceled.
    - `body` string — The message content provided. Base64 encoded.
    - `udh` string — The [UDH](https://community.sinch.com/t5/Glossary/UDH-User-Data-Header/ta-p/7776) header of a binary message HEX encoded. Max 140 bytes including the `body`.
    - `type` 'mt_binary', required — SMS in [binary](https://community.sinch.com/t5/Glossary/Binary-SMS/ta-p/7470) format.
    - `created_at` string, date-time — Timestamp for when batch was created. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `modified_at` string, date-time — Timestamp for when batch was last updated. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `delivery_report` 'none' | 'summary' | 'full' | 'per_recipient' | 'per_recipient_final' — Kind of delivery report
    - `send_at` string, date-time — If set, the date and time the message should be delivered. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `expire_at` string, date-time — If set, the date and time the message will expire. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
    - `callback_url` string — The callback URL provided in the request.
    - `client_reference` string — The string input to identify this batch message. If set, the identifier will be added in the delivery report/callback of this batch.
    - `feedback_enabled` boolean — If set to true, then [feedback](https://developers.sinch.com/docs/sms/api-reference/sms/batches/deliveryfeedback) is expected after successful delivery.
    - `from_ton` integer — The type of number for the sender number.
    - `from_npi` integer — Number Plan Indicator for the sender number.
  - MediaResponse
    - `id` string — Unique identifier for batch
    - `to` MtDestination[] — List of Phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)
    - `from` string — Sender number. Required if Automatic Default Originator not configured.
    - `canceled` boolean — Indicates if the batch has been canceled or not.
    - `body` MediaBody — The message content, including a URL to the media file
      - `subject` string — The subject text
      - `message` string — The message text. Text only media messages will be rejected, please use SMS instead.
      - `url` string, required — URL to the media file
    - `parameters` ParameterObj — Contains the parameters that will be used for customizing the message for each recipient. [Click here to learn more about parameterization](https://developers.sinch.com/docs/sms/resources/message-info/message-parameterization).
    - `type` 'mt_media', required — Media message
    - `created_at` string, date-time — Timestamp for when batch was created. YYYY-MM-DDThh:mm:ss.SSSZ format
    - `modified_at` string, date-time — Timestamp for when batch was last updated. YYYY-MM-DDThh:mm:ss.SSSZ format
    - `delivery_report` 'none' | 'summary' | 'full' | 'per_recipient' | 'per_recipient_final' — Kind of delivery report
    - `send_at` string, date-time — If set in the future the message will be delayed until send_at occurs. Must be before `expire_at`. If set in the past messages will be sent immediately. YYYY-MM-DDThh:mm:ss.SSSZ format
    - `expire_at` string, date-time — If set the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after send_at. YYYY-MM-DDThh:mm:ss.SSSZ format
    - `callback_url` string — Override the default callback URL for this batch. Must be valid URL.
    - `client_reference` string — The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
    - `feedback_enabled` boolean — If set to true then [feedback](https://developers.sinch.com/docs/sms/api-reference/sms/batches/deliveryfeedback) is expected after successful delivery.
    - `strict_validation` boolean — Whether or not you want the media included in your message to be checked against [Sinch MMS channel best practices](https://developers.sinch.com/docs/mms/bestpractices/). If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed.

## Other responses

- `404` — Not found. The batch ID is unknown to the system.
- `409` — Conflict. There was an active operation operating on the batch. The cancellation can be retried.

---

[API](https://skmtc.net/sinch/apis/api-overview-sinch.md) · [All operations](https://skmtc.net/sinch/apis/api-overview-sinch/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sinch/api-overview-sinch/revisions/67cb925f1c81/schema)