# Cancel a coaching period

`DELETE https://api.coach-platform.com/api/public/escorts/{escortId}`

Cancel a coaching period. The trainee keeps their history.

- Resource: Escorts
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/delete-escorts-escort-id
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `escortId` | string | Yes |   |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | string | No | Optional. Send a unique key (e.g. a UUID) to make this POST safe to retry. The same key within 24h returns the original result instead of creating a duplicate. |

## Request body

Content type: `application/json`. Required.

| Field | Type | Required | Description |
|---|---|---|---|
| `cancelReason` | string | No |   |

## Responses

| Status | Description |
|---|---|
| `200` OK | Successful response |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `404` Not Found |  |
| `409` Conflict |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 200 OK

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object |   |
| `data.id` | string |   |
| `data.coach` | string |   |
| `data.trainee` | object | The escorted trainee. email and phoneNumber are returned only when the key also has the trainees:read scope. |
| `data.trainee.id` | string |   |
| `data.trainee.name` | string |   |
| `data.trainee.email` | string |   |
| `data.trainee.phoneNumber` | string |   |
| `data.status` | string | Allowed values: `pending`, `active`, `canceled`, `completed`, `suspended`. |
| `data.escortType` | string |   |
| `data.startDate` | string<date-time> |   |
| `data.endDate` | string<date-time> \| null | When the coaching period ends. null when the escort runs with no time limit, in which case isUnlimited is true. |
| `data.months` | integer \| null | Duration in months. null when the escort runs with no time limit. |
| `data.isUnlimited` | boolean | True when the escort has no end date. |
| `data.training` | object |   |
| `data.training.activeTrainingPlan` | object \| null |   |
| `data.training.activeTrainingPlan.id` | string |   |
| `data.training.activeTrainingPlan.title` | string |   |
| `data.training.activeTrainingPlan.level` | string |   |
| `data.training.trainingDays` | any |   |
| `data.nutrition` | object |   |
| `data.nutrition.activeNutritionPlan` | object \| null |   |
| `data.nutrition.activeNutritionPlan.id` | string |   |
| `data.nutrition.activeNutritionPlan.title` | string |   |
| `data.nutrition.activeNutritionPlan.level` | string |   |
| `data.skipRegistrationForms` | boolean | true when the trainee is not asked to fill registration forms in the app during this coaching period. Change it with PATCH /escorts/{escortId}. |
| `data.createdAt` | string<date-time> |   |

Example:

```json
{
  "data": {
    "id": "<string>",
    "coach": "<string>",
    "trainee": {
      "id": "<string>",
      "name": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>"
    },
    "status": "pending",
    "escortType": "<string>",
    "startDate": "<date-time>",
    "endDate": "<date-time>",
    "months": 123,
    "isUnlimited": true,
    "training": {
      "activeTrainingPlan": {
        "id": "<string>",
        "title": "<string>",
        "level": "<string>"
      },
      "trainingDays": null
    },
    "nutrition": {
      "activeNutritionPlan": {
        "id": "<string>",
        "title": "<string>",
        "level": "<string>"
      }
    },
    "skipRegistrationForms": true,
    "createdAt": "<date-time>"
  }
}
```

### Error responses 400, 401, 403, 404, 409, 429, 500

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `error` | object |   |
| `error.code` | string |   |
| `error.message` | string |   |
| `error.fix` | string \| null |   |
| `error.details` | object \| null |   |
| `error.retryAfterMs` | number \| null |   |

Example:

```json
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
```

## Examples

### cURL

```bash
curl --request DELETE \
  --url 'https://api.coach-platform.com/api/public/escorts/<escortId>' \
  --header 'Authorization: Bearer cp_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "cancelReason": "<string>"
}'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/escorts/<escortId>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer cp_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "cancelReason": "<string>"
  }),
});

const data = await response.json();
```

## Related endpoints

- [Get a coaching period](https://www.coach-platform.com/docs/api/reference/get-escorts-escort-id/index.md): `GET /api/public/escorts/{escortId}`. Get a coaching period by id.
- [Update a coaching period](https://www.coach-platform.com/docs/api/reference/patch-escorts-escort-id/index.md): `PATCH /api/public/escorts/{escortId}`. Update a coaching period.
- [Start a coaching period](https://www.coach-platform.com/docs/api/reference/post-escorts/index.md): `POST /api/public/escorts`. Start a new coaching period (escort) for a trainee.
- Previous: [Update a coaching period](https://www.coach-platform.com/docs/api/reference/patch-escorts-escort-id/index.md): `PATCH /api/public/escorts/{escortId}`. Update a coaching period.
- Next: [Start a coaching period](https://www.coach-platform.com/docs/api/reference/post-escorts/index.md): `POST /api/public/escorts`. Start a new coaching period (escort) for a trainee.