# Cancel a shipment

`POST https://api.mothership.com/beta/shipments/{shipmentId}/cancel`

Sandbox: `https://sandbox.api.mothership.com/beta/shipments/{shipmentId}/cancel`

Attempts to cancel the shipment immediately. By default, the request succeeds only when the cancellation path available right now is free. To accept a paid cancellation, set `acceptFees`, and optionally cap the fee with `limitAmountCents`.

Cancellation is immediate. The request only succeeds when cancelling is free, unless you set `acceptFees` to `true`. With `acceptFees`, add `limitAmountCents` to cap the fee you'll pay. A successful cancellation returns the fee charged in `cancellationFeeCents`.

| Response | When |
| --- | --- |
| `200` | The shipment was cancelled. |
| `402 PAYMENT_REQUIRED` | Cancelling costs more than you accepted. `metadata.feeCents` is the lowest fee available, and `metadata.availableCancellationOptions` lists each option's `type` and `feeCents`. Retry with `acceptFees: true` and a high enough `limitAmountCents`. |
| `409 INVALID_REQUEST` | "This shipment cannot be cancelled at this time." For example, a cancellation is already in progress. |

## Authorization

Send your API token as a Bearer token: `Authorization: Bearer <token>`.

## Path parameters

- `shipmentId` (string, required): Reference number of the shipment to cancel.

## Request body

- `reason` (string, required): Reason for cancellation. One of: `CargoNotReady`, `ShipmentCorrectionsNeeded`, `IncorrectCargoInfo`, `MissingAccessorial`, `ShipmentNotNeeded`.
- `acceptFees` (boolean, optional, default false): When true, cancels the shipment even if the cancellation path available now has a fee. Defaults to false.
- `limitAmountCents` (integer, optional, min 0): The most you will pay for the cancellation, in cents, when `acceptFees` is true. Optional.

## Responses

### 200

The shipment was cancelled. The result is inside `data`.

- `data` (object, required)
  - `status` (string, required): Whether the cancellation completed successfully. One of: `cancelled`.
  - `cancellationFeeCents` (integer, required, min 0): Fee in cents associated with the completed cancellation.

### 402

Cancellation is still possible, but the available fee exceeds what the caller accepted.

- `code` (number, required) One of: `100`, `101`, `200`, `201`, `202`, `203`, `204`, `205`, `206`, `300`, `301`, `302`, `303`, `304`, `305`, `307`, `400`, `401`, `402`, `403`, `404`, `405`, `406`, `407`, `408`, `409`, `410`, `411`, `412`, `413`, `414`, `415`, `416`, `417`, `422`, `429`, `500`, `501`, `502`, `503`, `504`, `505`.
- `type` (string, required) One of: `UNKNOWN`, `NOT_FOUND`, `SERVER_ERROR`, `UNAUTHENTICATED`, `MISSING_PERMISSION`, `INVALID_REQUEST`, `RATE_LIMIT_EXCEEDED`, `CARGO_TOO_LARGE`, `NO_RATES_FOUND`, `QUOTE_NOT_PURCHASABLE`, `PAYMENT_REQUIRED`, `PAYMENT_FAILED`.
- `message` (string, required)
- `metadata` (object, optional)

### 409

The shipment cannot be cancelled at this time.

- `code` (number, required) One of: `100`, `101`, `200`, `201`, `202`, `203`, `204`, `205`, `206`, `300`, `301`, `302`, `303`, `304`, `305`, `307`, `400`, `401`, `402`, `403`, `404`, `405`, `406`, `407`, `408`, `409`, `410`, `411`, `412`, `413`, `414`, `415`, `416`, `417`, `422`, `429`, `500`, `501`, `502`, `503`, `504`, `505`.
- `type` (string, required) One of: `UNKNOWN`, `NOT_FOUND`, `SERVER_ERROR`, `UNAUTHENTICATED`, `MISSING_PERMISSION`, `INVALID_REQUEST`, `RATE_LIMIT_EXCEEDED`, `CARGO_TOO_LARGE`, `NO_RATES_FOUND`, `QUOTE_NOT_PURCHASABLE`, `PAYMENT_REQUIRED`, `PAYMENT_FAILED`.
- `message` (string, required)
- `metadata` (object, optional)

## Example request

```bash
curl --request POST \
  --url 'https://sandbox.api.mothership.com/beta/shipments/MS5016101/cancel' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason": "ShipmentNotNeeded",
  "acceptFees": true,
  "limitAmountCents": 5000
}'
```

## Example response (200)

```json
{
  "data": {
    "status": "cancelled",
    "cancellationFeeCents": 0
  }
}
```