openapi: 3.0.0
info:
  title: Approvals
  description: Approval rules determine who must approve a transaction (invoice, sales order, purchase order, bill, etc.) before it moves forward. Use these endpoints to create, list, retrieve, update, delete, and reorder approval rules in Zoho Inventory.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/inventory/v1
    description: API Endpoint
tags:
  - name: approvals
    description: Approvals Module
paths:
  /settings/approvals:
    post:
      tags:
        - approvals
      operationId: create_approval
      summary: Create an approval rule
      description: Create a new approval rule for a transaction type in your organization.
      parameters:
        - $ref: '#/components/parameters/organization_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-an-approval-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-an-approval-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.CREATE
    get:
      tags:
        - approvals
      operationId: list_approvals
      summary: List approval rules
      description: Get the list of approval rules configured for a specific transaction type.
      parameters:
        - $ref: '#/components/parameters/organization_id'
        - name: entity_type
          in: query
          description: 'Transaction type for which to list approval rules. Required. Examples: <code>purchaseorder</code>, <code>bill</code>, <code>salesorder</code>, <code>invoice</code>.'
          required: true
          schema:
            type: string
          example: purchaseorder
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-approvals-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.READ
  /settings/approvals/{approval_id}:
    get:
      tags:
        - approvals
      operationId: get_approval
      summary: Retrieve an approval rule
      description: Get the details of an approval rule.
      parameters:
        - $ref: '#/components/parameters/organization_id'
        - name: approval_id
          in: path
          description: Unique ID of the approval rule.
          required: true
          schema:
            type: string
          example: '982000000567204'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-an-approval-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.READ
    put:
      tags:
        - approvals
      operationId: update_approval
      summary: Update an approval rule
      description: Update the details of an existing approval rule.
      parameters:
        - $ref: '#/components/parameters/organization_id'
        - name: approval_id
          in: path
          description: Unique ID of the approval rule.
          required: true
          schema:
            type: string
          example: '982000000567204'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-an-approval-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-an-approval-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.UPDATE
    delete:
      tags:
        - approvals
      operationId: delete_approval
      summary: Delete an approval rule
      description: Delete an approval rule from your organization.
      parameters:
        - $ref: '#/components/parameters/organization_id'
        - name: approval_id
          in: path
          description: Unique ID of the approval rule.
          required: true
          schema:
            type: string
          example: '982000000567204'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-an-approval-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.DELETE
  /settings/approvals/reorder:
    post:
      tags:
        - approvals
      operationId: reorder_approvals
      summary: Reorder approval rules
      description: Change the priority order of approval rules for a transaction type.
      parameters:
        - $ref: '#/components/parameters/organization_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/reorder-approvals-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reorder-approvals-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.CREATE
components:
  parameters:
    organization_id:
      name: organization_id
      description: 'ID of the organization. Note: This value is a set of numeric characters.'
      in: query
      required: true
      schema:
        type: string
      example: '10234695'
  schemas:
    approval:
      type: object
      properties:
        approval_id:
          description: Unique ID of the approval rule.
          type: string
          example: '982000000567204'
        name:
          description: Name of the approval rule. Max-length [100].
          type: string
          example: Purchase Order Approval
        description:
          description: Description of the approval rule.
          type: string
          example: Requires manager approval for all purchase orders.
        entity_type:
          description: Transaction type the rule applies to (e.g. <code>purchaseorder</code>, <code>bill</code>, <code>invoice</code>).
          type: string
          example: purchaseorder
        entity_type_formatted:
          description: Display label for the transaction type.
          type: string
          example: Purchase Order
          readOnly: true
        is_default:
          description: Whether this is the default approval rule for the transaction type.
          type: boolean
          example: false
        approval_type:
          description: Type of the approval rule.
          type: string
          example: manual
        rule:
          description: Condition rule that triggers this approval.
          type: object
          properties:
            criteria_string:
              description: Criteria expression string (e.g. <code>1 AND 2</code>).
              type: string
              example: '1'
            columns:
              description: Array of rule condition columns.
              type: array
              items:
                $ref: '#/components/schemas/rule-column'
        approval_levels:
          description: Ordered list of approvers for this rule.
          type: array
          items:
            $ref: '#/components/schemas/approval-level'
    rule-column:
      type: object
      properties:
        index:
          description: Position index of this condition.
          type: integer
          example: 1
        field:
          description: Field name to evaluate.
          type: string
          example: total
        comparator:
          description: Comparison operator (e.g. <code>greater_than</code>, <code>equals</code>).
          type: string
          example: greater_than
        value:
          description: Value to compare against.
          type: string
          example: '5000'
    approval-level:
      type: object
      properties:
        user_id:
          description: Unique ID of the approver.
          type: string
          example: '982000000554041'
        user_name:
          description: Name of the approver.
          type: string
          example: John Smith
        email:
          description: Email address of the approver.
          type: string
          example: john.smith@example.com
        order:
          description: Position of this approver in the approval sequence.
          type: integer
          example: 1
    approval-summary:
      type: object
      properties:
        approval_id:
          description: Unique ID of the approval rule.
          type: string
          example: '982000000567204'
        name:
          description: Name of the approval rule.
          type: string
          example: Purchase Order Approval
        description:
          description: Description of the approval rule.
          type: string
          example: Requires manager approval for all purchase orders.
        entity_type:
          description: Transaction type the rule applies to.
          type: string
          example: purchaseorder
        is_default:
          description: Whether this is the default approval rule for the transaction type.
          type: boolean
          example: false
    list-approvals-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        approvals:
          type: array
          items:
            $ref: '#/components/schemas/approval-summary'
    get-an-approval-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        approval:
          $ref: '#/components/schemas/approval'
    create-an-approval-request:
      required:
        - name
        - entity_type
      type: object
      properties:
        name:
          description: Name of the approval rule. Max-length [100].
          type: string
          example: Purchase Order Approval
        description:
          description: Description of the approval rule.
          type: string
          example: Requires manager approval for all purchase orders.
        entity_type:
          description: Transaction type the rule applies to (e.g. <code>purchaseorder</code>, <code>bill</code>, <code>invoice</code>).
          type: string
          example: purchaseorder
        is_default:
          description: Set to <code>true</code> to make this the default rule for the transaction type.
          type: boolean
          example: false
        approval_type:
          description: Type of the approval rule.
          type: string
          example: manual
        rule:
          description: Condition rule that triggers this approval.
          type: object
          properties:
            criteria_string:
              description: Criteria expression string (e.g. <code>1 AND 2</code>).
              type: string
              example: '1'
            columns:
              description: Array of rule condition columns.
              type: array
              items:
                $ref: '#/components/schemas/rule-column'
        approval_levels:
          description: Ordered list of approvers for this rule.
          type: array
          items:
            $ref: '#/components/schemas/approval-level-input'
    approval-level-input:
      type: object
      required:
        - type
        - order
      properties:
        type:
          description: 'Approver type. Allowed values: <code>none</code>, <code>user</code>, <code>lookup</code>.'
          type: string
          enum:
            - none
            - user
            - lookup
          example: user
        order:
          description: Position of this approver in the approval sequence.
          type: integer
          example: 1
        user_id:
          description: Unique ID of the approver. Required when type is <code>user</code>.
          type: string
          example: '982000000554041'
        approval_policy_id:
          description: ID of the associated approval policy.
          type: string
          example: '982000000567204'
        lookup_id:
          description: ID of the lookup field. Required when type is <code>lookup</code>.
          type: string
          example: '982000000567300'
        sub_type:
          description: 'Hierarchy sub-type when using lookup. Allowed values: <code>one_level</code>, <code>two_level</code>, <code>three_level</code>, <code>four_level</code>, <code>five_level</code>, <code>single_level</code>, <code>multi_level</code>.'
          type: string
          enum:
            - one_level
            - two_level
            - three_level
            - four_level
            - five_level
            - single_level
            - multi_level
          example: one_level
        notes:
          description: Notes for this approval level. Max-length [500].
          type: string
          example: Manager review required
    create-an-approval-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The approval rule has been created.
          readOnly: true
        approval:
          $ref: '#/components/schemas/approval'
    update-an-approval-request:
      type: object
      allOf:
        - $ref: '#/components/schemas/create-an-approval-request'
    update-an-approval-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The approval rule has been updated.
          readOnly: true
        approval:
          $ref: '#/components/schemas/approval'
    delete-an-approval-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The approval rule has been deleted.
          readOnly: true
    reorder-approvals-request:
      required:
        - entity_type
        - order
      type: object
      properties:
        entity_type:
          description: Transaction type for which to reorder approvals (e.g. <code>purchaseorder</code>, <code>bill</code>, <code>invoice</code>).
          type: string
          example: purchaseorder
        order:
          description: Array of objects specifying the new priority order.
          type: array
          items:
            $ref: '#/components/schemas/reorder-item'
    reorder-item:
      type: object
      properties:
        index:
          description: Position index for the approval rule in the new order.
          type: integer
          example: 0
        approval_id:
          description: Unique ID of the approval rule.
          type: string
          example: '982000000567204'
    reorder-approvals-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Approval rules have been reordered.
          readOnly: true
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoInventory.settings.CREATE: Create Settings
            ZohoInventory.settings.READ: Read Settings
            ZohoInventory.settings.UPDATE: Update Settings
            ZohoInventory.settings.DELETE: Delete Settings
