PATCH /appointments/:id

Partially update an existing appointment. Only the fields included in the request body are modified — all other fields remain unchanged.

Cannot be called on appointments in a terminal state (canceled, refunded, failed) or with a past appointment_time.

State-Dependent Field Access

Which fields can be patched depends on the appointment's current status:

Field	new / pending	ready / paying / paid
consumer_name	Yes	Yes
consumer_phone	Yes	Yes
driver_notes	Yes	Yes
config	Yes	Yes
appointment_time	Yes	No
consumer_at_pickup	Yes	No
pickup_location_id	Yes	No
delivery_location_id	Yes	No
vehicle_vin	Yes	No
vehicle_make	Yes	No
vehicle_model	Yes	No
vehicle_year	Yes	No
vehicle_color	Yes	No
vehicle_manual	Yes	No

Once an appointment reaches ready status, move staging has begun. Location, vehicle, and scheduling fields are frozen to prevent inconsistencies with the move being created.

System-managed fields (id, status, customer_id, move_id, workflow_set_id, payment fields, and timestamps) are never patchable.

Example Request

PATCH /v1/appointments/:id

{
    "consumer_phone": "+15555550199",
    "driver_notes": "Updated gate code: 5678"
}

Body Params

Field	Type	Required?	Description
consumer_name	String	Optional	Consumer full name.
consumer_phone	String	Optional	Consumer mobile phone number.
driver_notes	String	Optional	Gate codes, special pickup instructions, or other notes for the driver.
config	Object	Optional	Flexible JSONB metadata object for integration-specific keys.
appointment_time	String	Optional	ISO 8601 timestamp. Only modifiable in new or pending status.
consumer_at_pickup	Boolean	Optional	Whether the vehicle is at the consumer's location. Only modifiable in new or pending status.
pickup_location_id	Number	Optional	HopDrive location ID for the consumer's pickup address. Only modifiable in new or pending status.
delivery_location_id	Number	Optional	HopDrive location ID for the dealership address. Only modifiable in new or pending status.
vehicle_vin	String	Optional	Vehicle Identification Number. Only modifiable in new or pending status.
vehicle_make	String	Optional	Vehicle make. Only modifiable in new or pending status.
vehicle_model	String	Optional	Vehicle model. Only modifiable in new or pending status.
vehicle_year	Number	Optional	Vehicle model year. Only modifiable in new or pending status.
vehicle_color	String	Optional	Vehicle color. Only modifiable in new or pending status.
vehicle_manual	Boolean	Optional	Manual transmission flag. Only modifiable in new or pending status.

Example Response

200 /v1/appointments/:id

{
    "id": 88001234,
    "status": "ready",
    "customer_id": 1234,
    "appointment_time": "2026-03-10T14:00:00+00:00",
    "consumer_name": "Jane Smith",
    "consumer_phone": "+15555550199",
    "consumer_at_pickup": true,
    "pickup_location_id": 9012,
    "delivery_location_id": 5678,
    "vehicle_vin": "1HGBH41JXMN109186",
    "vehicle_make": "Honda",
    "vehicle_model": "Accord",
    "vehicle_year": 2022,
    "vehicle_color": "Silver",
    "vehicle_manual": false,
    "driver_notes": "Updated gate code: 5678",
    "move_id": null,
    "config": { "transportation_type": "valet" },
    "updatedat": "2026-03-05T19:15:00.000000+00:00"
}