> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Shipment

> Cancel a shipment and void the shipping label

<Note>
  This endpoint cancels a shipment and voids the shipping label. Refunds are processed automatically based on carrier policies.
</Note>

## Authentication

This endpoint requires a valid API key with `shipments:write` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the shipment to cancel
</ParamField>

## Request Body

<ParamField body="reason" type="string" required>
  Cancellation reason: "order\_cancelled", "incorrect\_address", "changed\_shipping\_method", "duplicate", "other"
</ParamField>

<ParamField body="notes" type="string">
  Additional notes about the cancellation
</ParamField>

### Response

Returns the cancelled shipment with refund information.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/shipments/ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30/cancel' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "reason": "order_cancelled",
      "notes": "Customer requested cancellation before shipment"
  }'
  ```

  ```javascript Node.js theme={null}
  const shipment = await stateset.shipments.cancel(
    'ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    {
      reason: "order_cancelled",
      notes: "Customer requested cancellation before shipment"
    }
  );
  ```

  ```python Python theme={null}
  shipment = stateset.shipments.cancel(
    'ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    reason="order_cancelled",
    notes="Customer requested cancellation before shipment"
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "object": "shipment",
    "status": "cancelled",
    "cancelled_at": "2024-01-19T17:00:00Z",
    "cancellation": {
      "reason": "order_cancelled",
      "notes": "Customer requested cancellation before shipment",
      "cancelled_by": "user_123"
    },
    "refund": {
      "status": "processed",
      "amount": 1250,
      "currency": "USD",
      "processed_at": "2024-01-19T17:00:15Z",
      "reference": "REF-SHIP-001"
    },
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups",
    "metadata": {
      "cancellation_reference": "CANCEL-2024-001"
    }
  }
  ```
</ResponseExample>