> ## 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.

# Bulk Create Order Control Numbers

> Bulk creates BillPay Order Control Numbers (max 50 per request). Supports partial success: valid items are created while invalid items are reported in the errors array.



## OpenAPI

````yaml POST /billpay/bulk-create-order-control-numbers
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/bulk-create-order-control-numbers:
    post:
      description: >-
        Bulk creates BillPay Order Control Numbers (max 50 per request).
        Supports partial success: valid items are created while invalid items
        are reported in the errors array.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - controlNumbers
              properties:
                controlNumbers:
                  type: array
                  minItems: 1
                  maxItems: 50
                  description: Array of order control number items
                  items:
                    type: object
                    properties:
                      billReference:
                        type: string
                        description: Custom bill reference (alphanumeric, max 20 chars)
                      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. Applied only when billAmount is set
            example:
              controlNumbers:
                - billAmount: 25000
                  billDescription: Order 1
                - billReference: ORD002
                  billAmount: 50000
      responses:
        '200':
          description: >-
            Bulk create result - may include partial success with per-item
            errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCreateResponse'
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
components:
  schemas:
    BulkCreateResponse:
      type: object
      properties:
        billPayNumbers:
          type: array
          items:
            type: string
          description: Array of successfully created BillPay numbers
        created:
          type: number
          description: Count of successfully created control numbers
        failed:
          type: number
          description: Count of failed items
        errors:
          type: array
          items:
            type: object
            properties:
              index:
                type: number
                description: 0-based index of the failed item in the request array
              reason:
                type: string
                description: Error message for the failed item
          description: Present only when failed > 0
    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
  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

````