> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickpesa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update BillPay Reference

> Partially updates a BillPay reference. Use to update amount, description, payment mode, or status without recreating the reference.



## OpenAPI

````yaml PATCH /billpay/{billPayNumber}
openapi: 3.0.1
info:
  title: CORE API - BillPay Control Number Creation
  description: API for creating BillPay Control Numbers
  version: 1.0.0
servers:
  - url: https://api.clickpesa.com/third-parties
security:
  - bearerAuth: []
paths:
  /billpay/{billPayNumber}:
    patch:
      description: >-
        Partially updates a BillPay reference. Use to update amount,
        description, payment mode, or status without recreating the reference.
      parameters:
        - name: billPayNumber
          in: path
          required: true
          schema:
            type: string
          description: BillPay number to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                billStatus:
                  type: string
                  enum:
                    - ACTIVE
                    - INACTIVE
                  description: Status of the BillPay reference
                billAmount:
                  type: number
                  minimum: 0.01
                  description: Amount of the bill (positive, max 2 decimal places)
                billDescription:
                  type: string
                  maxLength: 500
                  description: Description of the bill
                billPaymentMode:
                  type: string
                  enum:
                    - ALLOW_PARTIAL_AND_OVER_PAYMENT
                    - EXACT
                  description: Payment mode
            example:
              billAmount: 50000
              billDescription: Updated order description
      responses:
        '200':
          description: Successfully updated BillPay reference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateBillPayReferenceResponse'
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
components:
  schemas:
    UpdateBillPayReferenceResponse:
      type: object
      properties:
        billPayNumber:
          type: string
          description: The BillPay reference number that was updated
          example: '55042914871931'
        billStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: The updated status of the BillPay reference
        billAmount:
          type: number
          description: Amount of the bill
        billDescription:
          type: string
          description: Description of the bill
        billPaymentMode:
          type: string
          enum:
            - ALLOW_PARTIAL_AND_OVER_PAYMENT
            - EXACT
          description: Payment mode
    ValidationError:
      type: object
      properties:
        message:
          type: string
          description: Validation error message
          example: billPayNumber is required
    UnauthorizedError:
      type: object
      properties:
        message:
          type: string
          description: Unauthorized Error
          example: Unauthorized
    NotFoundError:
      type: object
      properties:
        message:
          type: string
          example: BillPay Number does not exist
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization header containing the JWT access token returned from the
        generate token endpoint. The token already includes the Bearer prefix.
        Example: `Authorization: Bearer eyJhbGciOi...`
      bearerFormat: JWT

````