How to delete a partner appointment with trip

This document explains how to delete a partner appointment and its linked pickup/dropoff trips using the Partner v2 delete endpoint.

Use this API when you want to delete:

• the appointment
• the mapped pickup trip
• any linked dropoff trip(s), if present

To delete a partner appointment with trip, you first need your credentials. If you don't already have one, head over to the Authentication and Authorization page to see how you can request credentials from us.

Request

HTTP request

DELETE  https://api.mykaarma.com/appointment/v2/departments/{dealerDepartmentUUID}/partner-appointments-with-trip/{appointmentUuid}
        ?updatedByDAUUID={updatedByDAUUID}
        &source={source}

Parameters

Path parameters

Parameter Name	Value	Description	Required
dealerDepartmentUUID	String	Unique identifier of the dealer department	Yes
appointmentUuid	String	UUID of the appointment to delete. This is the SAR UUID.	Yes

Query parameters

Parameter Name	Value	Description	Required
updatedByDAUUID	String	UUID of the dealer associate performing the delete. Required unless source=WEB and the API can derive a fallback actor from the appointment.	Conditional
source	String	Platform source of the request. Supported values include WEB, DEALER_APP, PND_API, and EXTERNAL_CONTROLLER.	No

Authorization

Scope	Level	Description
appointment.create	Department	Authorises client to delete appointment and trip data for the provided dealer department

Behavior

• The API resolves the dealer internally from dealerDepartmentUUID.
• The API resolves the mapped pickup trip internally from appointmentUuid.
• The caller does not send tripUuid or dropoffTripUUID.
• If the pickup trip has linked dropoff trip(s), they are deleted automatically through the same delete flow.
• If source=WEB and updatedByDAUUID is omitted, the API attempts to derive the delete actor from:
  • the appointment assigned user
  • otherwise the appointment creator user
• If source is omitted, the request is treated as non-WEB, so updatedByDAUUID is required.
• If source is present and not WEB, updatedByDAUUID is required.
• The endpoint deletes the appointment, removes the SAR-trip mapping, and deletes the linked trip records through the pickup/dropoff service.

To inspect the current pickup/dropoff trips before delete, call get partner trips for an appointment.

Curl Examples

Delete with explicit actor

curl --location --request DELETE 'https://api.mykaarma.com/appointment/v2/departments/{{department_uuid}}/partner-appointments-with-trip/{{appointment_uuid}}?updatedByDAUUID={{dealer_associate_uuid}}&source=WEB' \
--header 'Authorization: Basic {{basic_auth_token}}'

Delete with WEB fallback actor

Use this only when the appointment already has an assigned user or creator user that can be used as the delete actor.

curl --location --request DELETE 'https://api.mykaarma.com/appointment/v2/departments/{{department_uuid}}/partner-appointments-with-trip/{{appointment_uuid}}?source=WEB' \
--header 'Authorization: Basic {{basic_auth_token}}'

Delete with non-WEB source

For non-WEB sources, updatedByDAUUID must be provided.

curl --location --request DELETE 'https://api.mykaarma.com/appointment/v2/departments/{{department_uuid}}/partner-appointments-with-trip/{{appointment_uuid}}?updatedByDAUUID={{dealer_associate_uuid}}&source=DEALER_APP' \
--header 'Authorization: Basic {{basic_auth_token}}'

Response

The response is a DeleteAppointmentWithTripResponse object:

Property Name	Value	Description
pickupEventUUID	String	UUID of the deleted pickup trip event
appointmentUuid	String	UUID of the deleted appointment
statusCode	Integer	HTTP status code of the response
errors	List<Object>	List of errors, if any
warnings	List<Object>	List of warnings, if any

Response Example

{
  "pickupEventUUID": "{{pickup_trip_uuid}}",
  "appointmentUuid": "{{appointment_uuid}}",
  "statusCode": 200,
  "errors": null,
  "warnings": null
}

Possible Errors

The delete API can fail at the authentication layer, request validation layer, or downstream pickup/delivery and appointment-cancel layers.

Authentication and authorization errors

HTTP Status	Error Code	When it happens
401	UNAUTHORIZED	The Basic Auth credentials are missing or invalid.
403	FORBIDDEN	The client does not have the required appointment.create scope at the department level for the requested department.

Request validation errors

These are the explicit validation errors enforced by the partner delete endpoint before the downstream delete flow runs.

HTTP Status	Error Code	Error Description	When it happens
400	INVALID_DEPT_UUID	Invalid dealer department UUID is provided in the request	dealerDepartmentUUID is blank, invalid, or cannot be resolved to a dealer.
400	INVALID_SAR_UUID	Invalid SAR UUID is provided in the request	appointmentUuid is blank.
400	PARTNER_DELETE_REQUEST_FIELDS_MISSING	updatedByDAUUID is required in the partner delete request unless source is WEB and a fallback actor can be derived from the appointment	updatedByDAUUID is missing for a non-WEB request, or source=WEB but the API cannot derive a fallback actor from the appointment.
400	PARTNER_DELETE_TRIP_NOT_LINKED_TO_APPOINTMENT	Pickup trip is not linked to the given appointment for the partner delete request	The appointment does not have an active mapped pickup trip, so the API cannot start the delete flow.

Downstream delete and cancel errors

After validation passes, the endpoint deletes the pickup/dropoff trip chain and then cancels the appointment. If either downstream step fails, the response can include one or more entries in errors.

HTTP Status	Error Code	When it happens
4xx or 5xx	downstream service error code	The pickup/dropoff delete service rejects the request or fails while deleting the trip chain. The API returns the downstream statusCode and propagates the downstream error in errors.
200 or downstream trip-delete status	downstream appointment update error code	The trip delete succeeds, but the appointment cancel step returns an error. In that case, the response includes the appointment update error in errors.
500	INTERNAL_ERROR or INTERNAL_SERVER_ERROR	An unexpected server-side failure occurs while processing the delete request.

Error response example

{
  "pickupEventUUID": null,
  "appointmentUuid": null,
  "statusCode": 400,
  "errors": [
    {
      "errorCode": "PARTNER_DELETE_TRIP_NOT_LINKED_TO_APPOINTMENT",
      "errorDescription": "Pickup trip is not linked to the given appointment for the partner delete request"
    }
  ],
  "warnings": null
}

Related APIs

• Create a partner appointment with trip
• Get partner trips for an appointment
• Update a partner appointment with trip