> For the complete documentation index, see [llms.txt](https://docs.simplespa.net/simplespa-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.simplespa.net/simplespa-documentation/api/simplespa-enterprise-api/write/appointment-status.md).

# Appointment Status

> Note: API Beta Access, see [API Terms of Use](https://docs.simplespa.net/simplespa-documentation/api/simplespa-enterprise-api/integrations/api-terms-of-use)

***

### Overview

The Appointment Status Update API allows approved Enterprise accounts to update the status of an existing appointment using the appointment **ID**.

This endpoint is designed for integrations that need to:

* Confirm appointments
* Cancel appointments
* Sync appointment status updates from external systems
* Automate workflows triggered by appointment changes

Status changes update the internal appointment tables and create corresponding status update records used for notifications and audit logs.

### Endpoint

```http
POST https://my.simplespa.com/api/v1/write/appointment-status.php
```

### Authentication

You must include a valid Authorization header using your SimpleSpa API Key:

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

> Replace YOUR\_API\_KEY with your SimpleSpa Enterprise API Key.\
> API Key Mode must be 2 (Write) or 3 (Read + Write) to use this endpoint.

### Request Body

| Parameter       | Type    | Required | Description                                                                                                |
| --------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| appointment\_id | string  | Required | The appointment ID.                                                                                        |
| status          | integer | Required | The new appointment status code (see Status Codes table below).                                            |
| reason          | string  | Optional | Optional text describing why the status is being changed (used for logging/audit purposes, not displayed). |

### Example Request

```bash
curl -X POST https://my.simplespa.com/api/v1/write/appointment-status.php \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "appointment_id": "e3b0c44298fc1c149afbf4c8996fb924",
  "status": 20,
  "reason": "client_confirmed_via_external_system"
}'
```

### Example Response

```json
{
  "success": true,
  "appointment_id": "e3b0c44298fc1c149afbf4c8996fb924",
  "appointment_id_raw": 12345,
  "old_status": 10,
  "new_status": 20,
  "reason": "client_confirmed_via_external_system"
}
```

**Example 1 — Mark Appointment as Confirmed**

```bash
curl -X POST https://my.simplespa.com/api/v1/write/appointment-status.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": "e3b0c44298fc1c149afbf4c8996fb924",
    "status": 20,
    "reason": "client_confirmed_via_external_system"
  }'
```

**Example 2 — Cancel Appointment**

```bash
curl -X POST https://my.simplespa.com/api/v1/write/appointment-status.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": "e3b0c44298fc1c149afbf4c8996fb924",
    "status": 15,
    "reason": "cancelled_by_client"
  }'
```

### Status Codes

These status codes align with the main Appointment Endpoint:

| Code | Description        |
| ---- | ------------------ |
| 0    | New                |
| 5    | Rebooked           |
| 7    | Request            |
| 10   | Online             |
| 12   | Payment Due        |
| 15   | Canceled           |
| 17   | No-Show            |
| 20   | Confirmed          |
| 22   | Confirmed (No SMS) |
| 25   | Arrived            |
| 30   | Paid               |
| 40   | Completed          |

### Notes

* This endpoint only updates status for an existing appointment. It does not create appointments or change times, staff, or services.
* Rate Limiting: This endpoint is strictly rate limited. Excessive updates may result in HTTP 429 responses. We recommend keeping status updates to no more than 10 requests per minute per API key.
* Pagination is not applicable for this endpoint (single appointment update per call).<br>

> ⚠️ IMPORTANT: Never expose your private API key in client-side JavaScript, mobile apps, or public code repositories. Always perform API calls from secure, server-side code.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.simplespa.net/simplespa-documentation/api/simplespa-enterprise-api/write/appointment-status.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.