openapi: 3.0.0
info:
  title: Custom Buttons
  description: Custom buttons allow you to add buttons to Zoho Books modules that can trigger custom actions, navigate to URLs, or execute custom functions when clicked.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/books/v3
    description: API Endpoint
tags:
  - name: custom-buttons
    description: Custom Buttons Module
paths:
  /settings/custombuttons:
    get:
      tags:
        - custom-buttons
      operationId: list_custom_buttons
      summary: List custom buttons
      description: List all the custom buttons configured for the organization.
      parameters:
        - name: filter_by
          in: query
          description: Filter custom buttons by entity type.
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          required: false
          schema:
            type: integer
            default: 1
          example: 1
        - name: per_page
          in: query
          description: Number of records per page. Default is 200.
          required: false
          schema:
            type: integer
            default: 200
          example: 200
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-custom-buttons-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    post:
      tags:
        - custom-buttons
      operationId: create_custom_button
      summary: Create a custom button
      description: Create a new custom button for a module.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-custom-button-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-custom-button-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /settings/custombuttons/{custombutton_id}:
    get:
      tags:
        - custom-buttons
      operationId: get_custom_button
      summary: Get a custom button
      description: Get the details of a specific custom button.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-custom-button-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    put:
      tags:
        - custom-buttons
      operationId: update_custom_button
      summary: Update a custom button
      description: Update an existing custom button.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-custom-button-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-custom-button-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    delete:
      tags:
        - custom-buttons
      operationId: delete_custom_button
      summary: Delete a custom button
      description: Delete an existing custom button.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-custom-button-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.DELETE
    parameters:
      - name: custombutton_id
        in: path
        required: true
        description: Unique identifier of the custom button.
        schema:
          type: string
        example: '982000000567001'
      - $ref: '#/components/parameters/organization_id'
  /custombuttons/meta:
    get:
      tags:
        - custom-buttons
      operationId: list_custom_buttons_meta
      summary: List custom buttons meta
      description: Get the meta information of custom buttons available for a specific entity and page view. This is used to render buttons on entity detail or list pages.
      parameters:
        - name: entity_type
          in: query
          description: Entity type to filter buttons for (e.g., invoice, contact, bill).
          required: false
          schema:
            type: string
          example: invoice
        - name: page_view
          in: query
          description: 'Page view context. Allowed values: <code>all</code>, <code>details_page</code>, <code>list_page</code>, <code>list_page_utility_menu</code> and <code>list_page_bulkaction_menu</code>.'
          required: false
          schema:
            type: string
          example: details_page
        - name: entity_id
          in: query
          description: Entity ID to check button availability for.
          required: false
          schema:
            type: string
          example: '982000000030049'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-custom-buttons-meta-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /settings/custombuttons/histories/{history_id}:
    get:
      tags:
        - custom-buttons
      operationId: get_custom_button_history
      summary: Get custom button history
      description: Get the details of a specific custom button execution history entry.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-custom-button-history-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    parameters:
      - name: history_id
        in: path
        required: true
        description: Unique identifier of the history entry.
        schema:
          type: string
        example: '982000000567050'
      - $ref: '#/components/parameters/organization_id'
components:
  parameters:
    organization_id:
      name: organization_id
      description: ID of the organization
      in: query
      required: true
      schema:
        type: string
      example: '10234695'
  schemas:
    custom_button:
      type: object
      properties:
        custombutton_id:
          type: string
          description: Unique identifier of the custom button.
          example: '982000000567001'
        button_name:
          type: string
          description: Name of the custom button.
          example: Send to CRM
        entity:
          type: string
          description: The module/entity this custom button is associated with.
          example: invoice
        location:
          type: string
          description: Location where the button appears.
          example: detail_page
        is_active:
          type: boolean
          description: Whether the custom button is active.
          example: true
    create-custom-button-request:
      type: object
      required:
        - button_name
        - entity
      properties:
        button_name:
          type: string
          description: Name of the custom button.
          example: Send to CRM
        entity:
          type: string
          description: The module/entity this custom button is associated with.
          example: invoice
        location:
          type: string
          description: Location where the button should appear.
          example: detail_page
    update-custom-button-request:
      type: object
      properties:
        button_name:
          type: string
          description: Name of the custom button.
          example: Send to CRM
        location:
          type: string
          description: Location where the button should appear.
          example: detail_page
    create-custom-button-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom button has been created.
        custom_button:
          $ref: '#/components/schemas/custom_button'
    update-custom-button-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom button has been updated.
        custom_button:
          $ref: '#/components/schemas/custom_button'
    get-custom-button-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        custom_button:
          $ref: '#/components/schemas/custom_button'
    list-custom-buttons-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        custom_buttons:
          type: array
          items:
            $ref: '#/components/schemas/custom_button'
    delete-custom-button-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: The custom button has been deleted.
    list-custom-buttons-meta-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        custom_buttons:
          type: array
          items:
            $ref: '#/components/schemas/custom_button'
    custom_button_history:
      type: object
      properties:
        history_id:
          type: string
          description: Unique identifier of the history entry.
          example: '982000000567050'
        custombutton_id:
          type: string
          description: Custom button that was triggered.
          example: '982000000567001'
        execution_time:
          type: string
          description: Time of execution.
          example: 2024-01-15T10:30:00+0530
        status:
          type: string
          description: Status of the execution.
          example: success
    get-custom-button-history-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        custom_button_history:
          $ref: '#/components/schemas/custom_button_history'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoBooks.settings.CREATE: Create Settings
            ZohoBooks.settings.UPDATE: Update Settings
            ZohoBooks.settings.READ: Read Settings
            ZohoBooks.settings.DELETE: Delete Settings
