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

# Cancel Shipment

> Cancels a shipment by setting its status to cancelled

## Request Parameters

### Path Parameters

<ParamField path="id" type="string" required>
  Shipment ID to cancel
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X DELETE \
    'https://platform.returnqueen.dev/api/shipments/123e4567-e89b-12d3-a456-426614174000' \
    -H 'X-API-KEY: your-api-key'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order_number": "ORDER-123",
    "status": "cancelled",
    "cancelled_at": "2024-01-15T10:30:00Z",
    "cancelled_by_id": "api-key-uuid",
    "cancelled_reason": "Partner requested cancellation via API",
    "shipment_type": "delivery",
    "shipment_date": "2023-11-07T10:00:00Z",
    "complete_at_start": "2023-11-07T14:00:00Z",
    "complete_at_end": "2023-11-07T18:00:00Z",
    "carrier_id": "660e8400-e29b-41d4-a716-446655440000",
    "carrier_service_level_id": "550e8400-e29b-41d4-a716-446655440000",
    "pickup_id": "770e8400-e29b-41d4-a716-446655440000",
    "timezone": "America/New_York",
    "inserted_at": "2023-11-07T10:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for the shipment (UUID format)
</ResponseField>

<ResponseField name="order_number" type="string">
  Order reference number
</ResponseField>

<ResponseField name="status" type="string">
  Shipment status (will be `cancelled`)
</ResponseField>

<ResponseField name="cancelled_at" type="string">
  When the shipment was cancelled (ISO 8601 format)
</ResponseField>

<ResponseField name="cancelled_by_id" type="string">
  ID of the entity that cancelled the shipment
</ResponseField>

<ResponseField name="cancelled_reason" type="string">
  Reason for cancellation
</ResponseField>

<ResponseField name="shipment_type" type="string">
  Type of shipment: `delivery`, `return`, or `exchange`
</ResponseField>

<ResponseField name="shipment_date" type="string">
  Original shipment date in ISO 8601 format
</ResponseField>

<ResponseField name="complete_at_start" type="string">
  Start of pickup window in ISO 8601 format
</ResponseField>

<ResponseField name="complete_at_end" type="string">
  End of pickup window in ISO 8601 format
</ResponseField>

<ResponseField name="carrier_id" type="string">
  Carrier identifier (UUID format)
</ResponseField>

<ResponseField name="carrier_service_level_id" type="string">
  Carrier service level identifier (UUID format)
</ResponseField>

<ResponseField name="pickup_id" type="string">
  Pickup identifier (UUID format)
</ResponseField>

<ResponseField name="timezone" type="string">
  IANA timezone identifier
</ResponseField>

<ResponseField name="label_url" type="string">
  URL to the shipping label
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional shipment metadata
</ResponseField>

<ResponseField name="inserted_at" type="string">
  When the shipment was created (ISO 8601 format)
</ResponseField>

<ResponseField name="updated_at" type="string">
  When the shipment was last updated (ISO 8601 format)
</ResponseField>

<Note>
  Only shipments in `pending` or `scheduled` status can be cancelled. Attempting to cancel a shipment in any other state will result in a 409 Conflict error.
</Note>