# Cancel a shipment

`POST /v2/shipments/cancel`

**Base URLs:**

- Sandbox: `https://api.sandbox.bobgo.co.za`
- Production: `https://api.bobgo.co.za`

**Authentication:** Bearer token required (see the Authentication page).

## Example request

```bash
curl -X POST 'https://api.sandbox.bobgo.co.za/v2/shipments/cancel' \
  -H "content-type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
  "tracking_reference": "UASDRW78"
}'
```

Cancels a shipment and refunds the charge to your Bob Go account.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `tracking_reference` | string | yes | Bob Go's tracking reference for the shipment. Your `custom_tracking_reference` is not accepted here. |
| `note` | string | no | Free-text reason. It becomes the message on the shipment's `cancelled` tracking event; it is not kept on the shipment itself. |

Bob Go decides there and then, from how far the shipment has got. A shipment
can be cancelled while its `status` is empty or one of `pending-collection`,
`awaiting-dropoff`, `failed-collection`, `collection-exception` or
`cancelled-by-courier`. For a shipment collected from a pickup point, only an
empty `status`, `awaiting-dropoff` or `cancelled-by-courier` qualifies.

Anything further along is refused with a `400`:

| Message | When |
| --- | --- |
| `The shipment cannot be cancelled anymore.` | The courier accepted it and it has moved past the statuses above. |
| `The shipment cannot be cancelled, as it has not been submitted successfully.` | Submission failed for good (`failed-indefinitely` or `no-rates`). |

## Response

On success the response is the whole shipment, with `status: "cancelled"`, and
the charge is reversed. Bob Go then cancels the booking with the courier in the
background, so there is nothing further to call.