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

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

# Update Dispatch Payment Status

`POST` `/api/fulfillments/id/{dispatchId}/update-payment-status`

Operation ID: `postPaymentStatus`

Update the payment status of a dispatch. #### 📝 Important Notes - The shipper and carrier each have their own separate payment status that is tracked independently. - Payment status can only be updated for dispatches in `PENDING_DELIVERY`, `DELIVERED`, `CANCELED`, or `ARCHIVED` status. - Requires `admin` or `owner` role permissions.

## Path parameters

- `dispatchId` (string, uuid, required) - The ID of the dispatch.

## Header parameters

- `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.
- `401` - Unauthorized. Authentication failed or missing.
- `403` - Forbidden. The attempted action is not permitted.
- `409` - Conflict. Update not allowed based on the current resource state. **Scenarios:** - Dispatch is in a status that does not accept payment status updates.
- `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/id/{dispatchId}/update-payment-status:
    post:
      tags:
        - Dispatch
      summary: Update Dispatch Payment Status
      description: >
        
        Update the payment status of a dispatch. 


        #### 📝 Important Notes

        - The shipper and carrier each have their own separate payment status
        that is tracked independently.

        - Payment status can only be updated for dispatches in
        `PENDING_DELIVERY`, `DELIVERED`, `CANCELED`, or `ARCHIVED` status.

        - Requires `admin` or `owner` role permissions.
      operationId: postPaymentStatus
      parameters:
        - name: dispatchId
          in: path
          description: The ID of the dispatch.
          required: true
          schema:
            type: string
            format: uuid
          example: d159acc0-e89b-12d3-a456-426614174000
        - 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: "`UpdatePaymentStatusRequest`"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePaymentStatusRequest"
            examples:
              ex.:
                value:
                  paymentStatus: PARTIALLY_PAID
      responses:
        "204":
          description: No Content. Successful request.
        "401":
          description: Unauthorized. Authentication failed or missing.
        "403":
          description: Forbidden. The attempted action is not permitted.
        "409":
          description: >-
            Conflict. Update not allowed based on the current resource state.


            **Scenarios:**

             - Dispatch is in a status that does not accept payment status updates.
          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:
    UpdatePaymentStatusRequest:
      type: object
      properties:
        paymentStatus:
          type: string
          description: "The status of the payment of the dispatch. Values: `UNPAID`,
            `INVOICED`, `PARTIALLY_PAID`, `FULLY_PAID`. Set to `null` to remove
            status."
          example: PARTIALLY_PAID
      description: Details of dispatch payment status.
    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
```