---
title: "Solicitar la cancelación de un envío propio"
method: POST
path: "/cancellations"
tags: ["cancellations"]
---

# Solicitar la cancelación de un envío propio

`POST /cancellations`

## Request

- Base URL: `https://api.enviadores.com.mx/api/v1`
- URL: `https://api.enviadores.com.mx/api/v1/cancellations`
- Auth: HTTP bearer

Crea una solicitud de cancelación (estado inicial `pending`). El avance del estado es operado por el staff/los procesos de la plataforma — consulta `GET /cancellations/{id}`. El reembolso esperado es lo que se cobró por el envío. Requiere scope `cancellations:write`.

## Request body

- object
  - `shipment_id` string, required: Id del envío propio a cancelar.
  - `reason_code` 'wrong_address' | 'duplicate' | 'customer_changed_mind' | 'damaged' | 'never_shipped' | 'not_picked_up' | 'other'
  - `reason_text` string

## Response `201`

Solicitud creada.

- object
  - `success` unknown, required
  - `data` object, required
    - `id` integer, required
    - `display_id` string, required: Live: formato `CR%08d`. Sandbox: `SBX-CR-<id>`.
    - `status` 'pending' | 'cancelled', required: Live devuelve `pending` (la solicitud entra a la cola de staff). Sandbox devuelve `cancelled` (cancelación síncrona y terminal — ver `x-test-mode`).
    - `refund_status` 'not_applicable' | 'refunded', required: Live: `not_applicable` (reembolso lo resuelve el staff). Sandbox: `refunded` (reembolso inmediato).
    - `refund_amount_expected` number, nullable
    - `cancellation_deadline` string, nullable: ISO-8601 UTC (Z). Siempre null en sandbox.
  - `requestId` string, required: Correlación de logs; también en el header `X-Request-Id`.

## Other responses

- `400`: `INVALID_JSON` · `REQUEST_FAILED` (rechazo del servicio).
- `401`: `UNAUTHORIZED` — credencial Bearer ausente/mal formada o llave desconocida/revocada (respuesta idéntica en ambos casos).
- `403`: `FORBIDDEN` (rechazo de permiso del servicio) · `INSUFFICIENT_SCOPE` · `PDV_NOT_ALLOWED`.
- `404`: `NOT_FOUND` — el envío no existe o no pertenece al usuario de la llave (respuesta idéntica).
- `409`: `CONFLICT` — el envío ya está cancelado o ya existe una solicitud abierta (`details.existing_request_id`).
- `422`: `VALIDATION_ERROR` (details.fields).
- `429`: `RATE_LIMITED` — bucket de la llave agotado. Espera `Retry-After` s (`details.retry_after_ms` para el hint fino). El limitador corre antes del gate de scope, por lo que un 429 tiene precedencia sobre un 403 `INSUFFICIENT_SCOPE`.
- `500`: `REQUEST_ERROR`.

---

[API](https://skmtc.dev/enviadores/apis/enviadores-public-api.md) · [All operations](https://skmtc.dev/enviadores/apis/enviadores-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/enviadores/apis/enviadores-public-api/revisions/3633f08c889c?raw)