---
title: "Cancel Dispatch"
url: "https://stage-api-docs.centraldispatch.com/apis/stage-fulfillment-api-1-0-0/versions/8637c155-7ff6-49fa-ac0a-3b4df78c9665/operations/postCancelDispatch"
---

> Full API specification: https://stage-api-docs.centraldispatch.com/apis/stage-fulfillment-api-1-0-0/versions/8637c155-7ff6-49fa-ac0a-3b4df78c9665.md

# Cancel Dispatch

`POST` `/api/fulfillments/cancel`

Operation ID: `postCancelDispatch`

Cancel a dispatch that has not been delivered. #### 📝 Important Notes - A dispatch with a status of `DELIVERED` cannot be canceled. - A dispatch with a status of `PENDING_DELIVERY` can be canceled if the `postPickupCancelOverride` value is true.

## Header parameters

- `If-Match` (integer, required) - This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the `ETag` header that was received on the preceding get call.
- `Content-Type` (string, required) - The major version of the API to make a request against. This is a custom MIME type that contains `vnd.coxauto.v[#]+`. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to `application/vnd.coxauto.v1+json`.

## Request body

Content types: `application/json`

## Responses

- `204` - No Content. Successful request.
- `400` - Bad Request. Check the request payload.
- `401` - Unauthorized. Authentication failed or missing.
- `403` - Forbidden. The attempted action is not permitted.
- `404` - Not Found.
- `409` - Conflict. Update not allowed based on the current resource state. **Scenarios:** - Dispatch already picked-up. - Dispatch already delivered. - Dispatch in a state that cannot be canceled.
- `412` - Precondition Failed **Scenarios:** - RecordVersion (`If-Match` header) does not match. - Resource modified by another request (stale ETag).
- `422` - Unprocessable Entity. Errors found in the request.
- `429` - Too Many Requests. Rate limit exceeded.
- `500` - Error.
- `503` - Service Unavailable. Temporary service interruption.

## OpenAPI definition

```yaml
openapi: 3.0.1
info:
  title: Fulfillment API
  version: 1.0.0
servers:
  - url: https://fulfillment-api.centraldispatch.com
    description: Production server
paths:
  /api/fulfillments/cancel:
    post:
      tags:
        - Dispatch
      summary: Cancel Dispatch
      description: >
        
        Cancel a dispatch that has not been delivered.


        #### 📝 Important Notes

        - A dispatch with a status of `DELIVERED` cannot be canceled.

        - A dispatch with a status of `PENDING_DELIVERY` can be canceled if the
        `postPickupCancelOverride` value is true.
      operationId: postCancelDispatch
      parameters:
        - name: If-Match
          in: header
          description: This is a required field to ensure the update is being completed on
            an item that has not changed since it was last read. The value of
            this field will be the value of the `ETag` header that was received
            on the preceding get call.
          required: true
          schema:
            type: integer
          example: 8675309
        - name: Content-Type
          in: header
          description: The major version of the API to make a request against. This is a
            custom MIME type that contains `vnd.coxauto.v[#]+`. For example, to
            request a resource from version 1.x.x of an API, the Content-Type
            header should be set to `application/vnd.coxauto.v1+json`.
          required: true
          schema:
            type: string
          example: application/vnd.coxauto.v1+json
      requestBody:
        description: "`CancelDispatchRequest`"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CancelDispatchRequest"
            examples:
              ex.:
                value:
                  dispatchId: d159acc0-e89b-12d3-a456-426614174000
                  notes: Weather delay.
                  postPickupCancelOverride: true
      responses:
        "204":
          description: No Content. Successful request.
        "400":
          description: Bad Request. Check the request payload.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorsAlt"
        "401":
          description: Unauthorized. Authentication failed or missing.
        "403":
          description: Forbidden. The attempted action is not permitted.
        "404":
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorsAlt"
        "409":
          description: |-
            Conflict. Update not allowed based on the current resource state.

            **Scenarios:**

             - Dispatch already picked-up.
             - Dispatch already delivered.
             - Dispatch in a state that cannot be canceled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorsAlt"
        "412":
          description: |-
            Precondition Failed

            **Scenarios:**

             - RecordVersion (`If-Match` header) does not match.
             - Resource modified by another request (stale ETag).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorsAlt"
        "422":
          description: Unprocessable Entity. Errors found in the request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorsAlt"
        "429":
          description: Too Many Requests. Rate limit exceeded.
        "500":
          description: Error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorsAlt"
        "503":
          description: Service Unavailable. Temporary service interruption.
      security:
        - Bearer: []
security:
  - Bearer: []
components:
  schemas:
    CancelDispatchRequest:
      type: object
      properties:
        dispatchId:
          type: string
          description: The ID of the dispatch.
          format: uuid
          example: d159acc0-e89b-12d3-a456-426614174000
        cancellationReasonId:
          type: string
          description: The ID of the cancellation reason. This value can be retrieved
            using the 'Get Cancellation Reasons' endpoint. Required if caller is
            a carrier.
          format: uuid
          example: cac10000-e89b-12d3-a456-426614174000
        notes:
          type: string
          description: Additional notes regarding the cancellation.
          nullable: true
          example: Weather delay.
        postPickupCancelOverride:
          type: boolean
          description: Indicates if a cancellation override after vehicle pick up is
            allowed.
          default: false
          example: true
      description: Details of a dispatch cancellation.
      nullable: true
    ErrorsAlt:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ErrorAlt"
          description: A collection of errors.
          nullable: true
      description: An error occurred, and the request could not be completed.
    ErrorAlt:
      type: object
      properties:
        errorID:
          type: string
          description: The ID of the error.
          nullable: true
          example: 157a16f0-503d-4256-ba60-a4876e8eb9bb
        code:
          type: string
          description: The code used for the issue.
          nullable: true
          example: resource.issue_type
        description:
          type: string
          description: A detailed message.
          nullable: true
          example: The issue happened because something is wrong.
        properties:
          type: array
          items:
            $ref: "#/components/schemas/ErrorAltProperty"
          description: Properties related to the issue.
          nullable: true
      description: Details of an error or issue.
    ErrorAltProperty:
      type: object
      properties:
        property:
          type: string
          description: The name of the property.
          nullable: true
          example: person
        value:
          type: string
          description: The value of the property.
          nullable: true
          example: J0hn D03
      description: Details of an error's property.
  securitySchemes:
    Bearer:
      type: http
      scheme: Bearer
```