openapi.yaml

openapi: 3.0.3
info:
  title: WHMCS API
  version: 1.0.0
  description: |
    Python client for the WHMCS API.
    
    WHMCS (Web Host Manager Complete Solution) provides a single API endpoint that handles
    multiple operations through different 'action' parameters. This specification presents
    each action as an independent path while routing all requests to the /api.php endpoint.

servers:
  - url: https://your-whmcs-instance.com/includes
    description: WHMCS API server

paths:
  /api.php?action=AddClient:
    post:
      summary: Add a new client
      description: Creates a new client account in WHMCS
      operationId: addClient
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - $ref: '#/components/schemas/WHMCSBaseRequest'
                - $ref: '#/components/schemas/AddClientRequest'
      responses:
        '200':
          description: Client created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddClientResponse'
        default:
          $ref: '#/components/responses/Error'

  /api.php?action=UpdateClient:
    post:
      summary: Update client details
      description: Modifies an existing client's information
      operationId: updateClient
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - $ref: '#/components/schemas/WHMCSBaseRequest'
                - $ref: '#/components/schemas/UpdateClientRequest'
      responses:
        '200':
          description: Client updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateClientResponse'
        default:
          $ref: '#/components/responses/Error'

  /api.php?action=AddOrder:
    post:
      summary: Create a new order
      description: Places a new order for products/services
      operationId: addOrder
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - $ref: '#/components/schemas/WHMCSBaseRequest'
                - $ref: '#/components/schemas/AddOrderRequest'
      responses:
        '200':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOrderResponse'
        default:
          $ref: '#/components/responses/Error'

  /api.php?action=GetClients:
    post:
      summary: Get clients
      description: Obtain the clients that match passed criteria
      operationId: getClients
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - $ref: '#/components/schemas/WHMCSBaseRequest'
                - $ref: '#/components/schemas/GetClientsRequest'
      responses:
        '200':
          description: Clients retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetClientsResponse'
        default:
          $ref: '#/components/responses/Error'

  /api.php?action=GetCurrencies:
    post:
      summary: Get currencies
      description: Obtain the currencies configured in the system
      operationId: getCurrencies
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/WHMCSBaseRequest'
      responses:
        '200':
          description: Currencies retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCurrenciesResponse'
        default:
          $ref: '#/components/responses/Error'

components:
  schemas:
    WHMCSBaseRequest:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
          description: Admin username/API identifier
        password:
          type: string
          description: Admin password/API secret
        accesskey:
          type: string
          description: Optional API access key
        responsetype:
          type: string
          enum: [json, xml]
          default: json
          description: Response format

    AddClientRequest:
      type: object
      required:
        - firstname
        - lastname
        - email
        - address1
        - city
        - state
        - postcode
        - country
        - phonenumber
      properties:
        owner_user_id:
          type: integer
          description: The ID of the user that should own the client
        firstname:
          type: string
          description: First name of the client
        lastname:
          type: string
          description: Last name of the client
        companyname:
          type: string
          description: Company name
        email:
          type: string
          description: Email address of the client
        address1:
          type: string
          description: Address line 1
        address2:
          type: string
          description: Address line 2
        city:
          type: string
          description: City
        state:
          type: string
          description: State
        postcode:
          type: string
          description: Postal code
        country:
          type: string
          description: 2 character ISO country code
        phonenumber:
          type: string
          description: Phone number
        tax_id:
          type: string
          description: Client's tax ID
        password2:
          type: string
          description: Password for the new user account
        securityqid:
          type: integer
          description: Security question ID
        securityqans:
          type: string
          description: Security question answer
        currency:
          type: integer
          description: Currency ID
        groupid:
          type: integer
          description: Client group ID
        customfields:
          type: string
          description: Base64 encoded serialized array of custom field values
        language:
          type: string
          description: Default language setting
        clientip:
          type: string
          description: Originating IP address
        notes:
          type: string
          description: Admin only notes
        marketingoptin:
          type: boolean
          description: Opt-in to marketing emails
        noemail:
          type: boolean
          description: Set to true to suppress the Order Confirmation email being sent
        skipvalidation:
          type: boolean
          description: Ignore required field validation

    UpdateClientRequest:
      type: object
      required:
        - clientid
      properties:
        clientid:
          type: integer
          description: The ID of the client to update
        clientemail:
          type: string
          description: The email address of the client to update
        firstname:
          type: string
          description: First name of the client
        lastname:
          type: string
          description: Last name of the client
        companyname:
          type: string
          description: Company name
        email:
          type: string
          description: Email address of the client
        address1:
          type: string
          description: Address line 1
        address2:
          type: string
          description: Address line 2
        city:
          type: string
          description: City
        state:
          type: string
          description: State
        postcode:
          type: string
          description: Postal code
        country:
          type: string
          description: 2 character ISO country code
        phonenumber:
          type: string
          description: Phone number
        tax_id:
          type: string
          description: Client's tax ID
        password2:
          type: string
          description: Password for the new user account
        securityqid:
          type: integer
          description: Security question ID
        securityqans:
          type: string
          description: Security question answer
        currency:
          type: integer
          description: Currency ID
        groupid:
          type: integer
          description: Client group ID
        customfields:
          type: string
          description: Base64 encoded serialized array of custom field values
        language:
          type: string
          description: Default language setting
        clientip:
          type: string
          description: Originating IP address
        notes:
          type: string
          description: Admin only notes
        status:
          type: string
          description: The status (e.g., Active)
        paymentmethod:
          type: string
          description: The payment method for the order in the system format (e.g., paypal, mailin)
        email_preferences_general:
          type: boolean
          description: Receive general emails
        email_preferences_product:
          type: boolean
          description: Receive product emails
        email_preferences_domain:
          type: boolean
          description: Receive domain emails
        email_preferences_invoice:
          type: boolean
          description: Receive invoice emails
        email_preferences_support:
          type: boolean
          description: Receive support emails
        email_preferences_affiliate:
          type: boolean
          description: Receive affiliate emails
        clearcreditcard:
          type: boolean
          description: Clear stored credit card details
        latefeeoveride:
          type: boolean
          description: Override Late Fees setting
        overideduenotices:
          type: boolean
          description: Override Overdue Notices setting
        taxexempt:
          type: boolean
          description: Exempt from tax collections
        separateinvoices:
          type: boolean
          description: Group items into one invoice
        disableautocc:
          type: boolean
          description: Enable/disable automatic credit card processing
        overrideautoclose:
          type: boolean
          description: Enable/disable automatic account closure

    AddOrderRequest:
      type: object
      required:
        - clientid
        - paymentmethod
      properties:
        clientid:
          type: integer
          description: The ID of the client to add the order for
        clientemail:
          type: string
          description: The email address of the client to update
        paymentmethod:
          type: string
          description: The payment method for the order in the system format (e.g., paypal, mailin)
        pid:
          type: array
          items:
            type: integer
          description: Array of product IDs to add to the order
        qty:
          type: array
          items:
            type: integer
          description: Array of product quantities
        domain:
          type: array
          items:
            type: string
          description: Array of domain names associated with the products/domains
        billingcycle:
          type: array
          items:
            type: string
          description: Array of billing cycles for the products
        domaintype:
          type: array
          items:
            type: string
          description: For domain registrations, array of register or transfer values
        regperiod:
          type: array
          items:
            type: integer
            minimum: 1
            maximum: 10
          description: For domain registrations, the registration periods for the domains
        idnlanguage:
          type: array
          items:
            type: string
          description: For IDN domain registrations, the language codes for the domains
        eppcode:
          type: array
          items:
            type: string
          description: For domain transfers, the EPP codes for the domains being transferred
        nameserver1:
          type: string
          description: The first nameserver to apply to all domains in the order
        nameserver2:
          type: string
          description: The second nameserver to apply to all domains in the order
        nameserver3:
          type: string
          description: The third nameserver to apply to all domains in the order
        nameserver4:
          type: string
          description: The fourth nameserver to apply to all domains in the order
        nameserver5:
          type: string
          description: The fifth nameserver to apply to all domains in the order
        configoptions:
          type: array
          items:
            type: string
          description: Array of base64 encoded serialized array of product configurable options values
        priceoverride:
          type: array
          items:
            type: number
            format: float
          description: Override the price of the product being ordered
        promocode:
          type: string
          description: The promotion code to apply to the order
        promooverride:
          type: boolean
          description: Should the promotion apply to the order even without matching promotional products
        affid:
          type: integer
          description: The affiliate ID to associate with the order
        noinvoice:
          type: boolean
          description: Set to true to suppress the invoice generating for the whole order
        noinvoiceemail:
          type: boolean
          description: Set to true to suppress the Invoice Created email being sent for the order
        addons:
          type: array
          items:
            type: string
          description: Array of comma separated lists of addons to create on order with the products
        addonsqty:
          type: array
          items:
            type: string
          description: Array of comma-separated lists of quantities for addons associated with products
        hostname:
          type: array
          items:
            type: string
          description: Array of hostnames for VPS/Dedicated Server orders
        ns1prefix:
          type: array
          items:
            type: string
          description: Array of first nameserver prefixes for VPS/Dedicated servers (e.g., ns1 in ns1.hostname.com)
        ns2prefix:
          type: array
          items:
            type: string
          description: Array of second nameserver prefixes for VPS/Dedicated servers (e.g., ns2 in ns2.hostname.com)
        rootpw:
          type: array
          items:
            type: string
          description: Array of desired root passwords for VPS/Dedicated servers
        contactid:
          type: integer
          description: The ID of the contact, associated with the client, that should apply to all domains in the order
        dnsmanagement:
          type: array
          items:
            type: boolean
          description: Add DNS Management to the Domain Order
        domainfields:
          type: array
          items:
            type: string
          description: Array of base64 encoded serialized array of TLD Specific Field Values
        emailforwarding:
          type: array
          items:
            type: boolean
          description: Add Email Forwarding to the Domain Order
        idprotection:
          type: array
          items:
            type: boolean
          description: Add ID Protection to the Domain Order
        domainpriceoverride:
          type: array
          items:
            type: number
            format: float
          description: Override the price of the registration price on the domain being ordered
        domainrenewoverride:
          type: array
          items:
            type: number
            format: float
          description: Override the price of the renewal price on the domain being ordered
        domainrenewals:
          type: object
          additionalProperties:
            type: integer
          description: A name -> value object of domainName -> renewalPeriod renewals to add an order for
        addonid:
          type: integer
          description: The Addon ID for an Addon Only Order
        addonidqty:
          type: integer
          description: The quantity of addons in an addon-only order
        serviceid:
          type: integer
          description: The service ID for the addon only order
        addonids:
          type: array
          items:
            type: integer
          description: Array of addon IDs for an Addon Only Order
        addonidsqty:
          type: array
          items:
            type: integer
          description: Array of quantities for an addon-only order
        serviceids:
          type: array
          items:
            type: integer
          description: Array of service IDs to associate the addons for an Addon Only order
        servicerenewals:
          type: array
          items:
            type: integer
          description: Array of service IDs to be on-demand renewed
        addonrenewals:
          type: array
          items:
            type: integer
          description: Array of service addon IDs to be on-demand renewed

    GetClientsRequest:
      type: object
      properties:
        limitstart:
          type: integer
          description: The offset for the returned log data
          default: 0
        limitnum:
          type: integer
          description: The number of records to return
          default: 25
        sorting:
          type: string
          enum: [ASC, DESC]
          default: ASC
          description: The direction to sort the results. ASC or DESC.
        status:
          type: string
          enum: [Active, Inactive, Closed]
          description: Optional desired Client Status. 'Active', 'Inactive', or 'Closed'.
        search:
          type: string
          description: The search term to look for at the start of email, firstname, lastname, fullname or companyname
        orderby:
          type: string
          enum: [id, firstname, lastname, companyname, email, groupid, datecreated, status]
          description: The column to order by. id, firstname, lastname, companyname, email, groupid, datecreated, status

    WHMCSBaseResponse:
      type: object
      properties:
        result:
          type: string
          description: Result status (success or error)
        message:
          type: string
          description: Response message

    WHMCSSuccessResponse:
      allOf:
        - $ref: '#/components/schemas/WHMCSBaseResponse'
        - type: object
          properties:
            result:
              type: string
              enum: [success]

    WHMCSErrorResponse:
      allOf:
        - $ref: '#/components/schemas/WHMCSBaseResponse'
        - type: object
          properties:
            result:
              type: string
              enum: [error]

    AddClientResponse:
      allOf:
        - $ref: '#/components/schemas/WHMCSSuccessResponse'
        - type: object
          properties:
            clientid:
              type: integer
              description: The ID of the newly created client
            owner_user_id:
              type: integer
              description: The ID of the user that owns the client

    UpdateClientResponse:
      allOf:
        - $ref: '#/components/schemas/WHMCSSuccessResponse'
        - type: object
          properties:
            clientid:
              type: string
              description: The ID of the updated client

    AddOrderResponse:
      allOf:
        - $ref: '#/components/schemas/WHMCSSuccessResponse'
        - type: object
          properties:
            orderid:
              type: string
              description: The ID of the newly created order
            productids:
              type: array
              items:
                type: string
              description: Array of product IDs that were created
            addonids:
              type: array
              items:
                type: string
              description: Array of addon IDs that were created
            domainids:
              type: array
              items:
                type: string
              description: Array of domain IDs that were created
            invoiceid:
              type: string
              description: The invoice ID if an invoice was generated

    GetClientsResponse:
      allOf:
        - $ref: '#/components/schemas/WHMCSSuccessResponse'
        - type: object
          properties:
            totalresults:
              type: integer
              description: The total number of results available
            startnumber:
              type: integer
              description: The starting number for the returned results
            numreturned:
              type: integer
              description: The number of results returned
            clients:
              type: object
              properties:
                client:
                  type: array
                  items:
                    $ref: '#/components/schemas/ClientInfo'
                  description: Array of client information

    GetCurrenciesResponse:
      allOf:
        - $ref: '#/components/schemas/WHMCSSuccessResponse'
        - type: object
          properties:
            totalresults:
              type: integer
              description: The total number of currencies available
            currencies:
              type: object
              properties:
                currency:
                  type: array
                  items:
                    $ref: '#/components/schemas/CurrencyInfo'
                  description: Array of currency information

    ClientInfo:
      type: object
      properties:
        id:
          type: integer
          description: The client ID
        firstname:
          type: string
          description: The client's first name
        lastname:
          type: string
          description: The client's last name
        companyname:
          type: string
          description: The client's company name
        email:
          type: string
          description: The client's email address
        datecreated:
          type: string
          format: date
          description: The date the client was created
        groupid:
          type: integer
          description: The client's group ID
        status:
          type: string
          description: The client's status (Active, Inactive, Closed)

    CurrencyInfo:
      type: object
      properties:
        id:
          type: integer
          description: The currency ID
        code:
          type: string
          description: The currency code (e.g., USD, EUR, GBP)
        prefix:
          type: string
          description: The currency prefix symbol (e.g., $, €, £)
        suffix:
          type: string
          description: The currency suffix (e.g., " USD")
        format:
          type: integer
          description: The currency format setting
        rate:
          type: string
          description: The currency exchange rate

  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WHMCSErrorResponse'

x-whmcs-config:
  singleEndpoint: true
  actualPath: /api.php
  description: |
    This OpenAPI spec uses virtual paths for different WHMCS actions, but all requests
    should be sent to the actual /api.php endpoint. The client implementation should:
    1. Route all requests to /api.php regardless of the path in this spec
    2. Automatically inject the 'action' parameter based on the operation
    3. Merge the base request fields with action-specific fields