openapi: 3.0.0
info:
  title: Employee Advances
  description: An employee advance entity allows you to manage advance payments made to employees.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/expense/v1
    description: API Endpoint
tags:
  - name: employee-advances
    description: Employee Advances Module
paths:
  /advancepayments:
    x-mcp-group:
      - Employee Advances
    post:
      tags:
        - employee-advances
      operationId: create_advance_payment
      summary: Create an advance payment
      description: Create a new advance payment for an employee. The <code>currency_id</code>, <code>amount</code>, <code>date</code>, and <code>user_id</code> fields are required.
      parameters:
        - name: delegate_user_id
          in: query
          description: ID of the user on whose behalf the advance is being created.
          required: false
          schema:
            type: string
          example: '16367000000073001'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-an-advance-payment-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-an-advance-payment-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoExpense.advance.CREATE
    get:
      tags:
        - employee-advances
      operationId: list_advance_payments
      summary: List advance payments
      description: List all advance payments for the organization.
      parameters:
        - name: filter_by
          in: query
          description: 'Filter advance payments by status or type. Allowed values: <code>Status.All</code>, <code>Status.Draft</code>, <code>Status.Submitted</code>, <code>Status.Approved</code>, <code>Status.UnApproved</code>, <code>Status.Rejected</code>, <code>Status.Unsubmitted</code>, <code>Status.ModifiableAdvances</code>, <code>Status.Void</code>, <code>Status.Exported</code>, <code>Status.Unexported</code>, <code>Type.All</code>, <code>Type.Approval</code>, <code>Type.Advance</code>, <code>Type.MyApproval</code>, <code>Type.SharedAdvance</code>.'
          required: false
          schema:
            type: string
            pattern: ^[Status(\.(All|Submitted|Draft|TakenBack|Approved|UnApproved|Rejected|Unsubmitted|Void|Exported|Unexported))|Type(\.(All|Approval|Advance|MyApproval|SharedAdvance))|,]+$
          example: Status.Approved
        - name: status
          in: query
          description: 'Filter by advance status. Allowed values: <code>all</code>, <code>submitted</code>, <code>draft</code>, <code>recalled</code>, <code>approved</code>, <code>unapproved</code>, <code>rejected</code>, <code>unsubmitted</code>, <code>modifiable</code>, <code>applied</code>, <code>unapplied</code>, <code>unrefunded</code>, <code>void</code>. Multiple values can be combined with commas.'
          required: false
          schema:
            type: string
            pattern: ^(all|submitted|draft|recalled|approved|unapproved|rejected|unsubmitted|modifiable|applied|unapplied|unrefunded|void|,)+$
          example: approved
        - name: type
          in: query
          description: 'Type of view. Allowed values: <code>approval</code>, <code>myapproval</code>, <code>advance</code>.'
          required: false
          schema:
            type: string
            pattern: ^(approval|myapproval|advance)$
          example: advance
        - name: advance_type
          in: query
          description: Type of advance. Allowed value <code>cash</code>.
          required: false
          schema:
            type: string
          example: cash
        - name: user_id
          in: query
          description: Filter by the employee's user ID.
          required: false
          schema:
            type: string
          example: '16367000000073001'
        - name: created_by
          in: query
          description: Filter advances by the user who created them.
          required: false
          schema:
            type: string
          example: '16367000000073001'
        - name: trip_id
          in: query
          description: Filter advances by trip.
          required: false
          schema:
            type: string
          example: '34017000000000103'
        - name: report_id
          in: query
          description: Filter advances by associated expense report.
          required: false
          schema:
            type: string
          example: '16367000000081005'
        - name: customer_id
          in: query
          description: Filter advances by customer.
          required: false
          schema:
            type: string
          example: '16367000000088005'
        - name: project_id
          in: query
          description: Filter advances by project.
          required: false
          schema:
            type: string
          example: '16367000000223045'
        - name: currency_id
          in: query
          description: Filter advances by currency.
          required: false
          schema:
            type: string
          example: '16367000000000099'
        - name: from_account_id
          in: query
          description: Filter advances by paid-through account.
          required: false
          schema:
            type: string
          example: '16367000000036003'
        - name: to_account_id
          in: query
          description: Filter advances by destination account.
          required: false
          schema:
            type: string
          example: '16367000000036005'
        - name: export_status
          in: query
          description: 'Filter by export status. Allowed values: <code>exported</code>, <code>unexported</code>.'
          required: false
          schema:
            type: string
            pattern: ^(exported|unexported)$
          example: unexported
        - name: approved_by
          in: query
          description: Filter advances by the user who approved them.
          required: false
          schema:
            type: string
          example: '16367000000073001'
        - name: submitted_by
          in: query
          description: Filter advances by the user who submitted them.
          required: false
          schema:
            type: string
          example: '16367000000073001'
        - name: submitted_to
          in: query
          description: Filter advances by the user to whom they were submitted.
          required: false
          schema:
            type: string
          example: '16367000000073001'
        - name: customview_id
          in: query
          description: ID of the custom view.
          required: false
          schema:
            type: string
          example: '16367000000280001'
        - name: search_text
          in: query
          description: Search advances by reference number, notes, or user name.
          required: false
          schema:
            type: string
          example: ADV
        - name: sort_column
          in: query
          description: 'Column to sort the results by. Allowed values: <code>user_name</code>, <code>date</code>, <code>reference_number</code>, <code>created_by_name</code>, <code>amount</code>, <code>status</code>, <code>approver_name</code>, <code>customer_name</code>, <code>employee_no</code>, <code>account_name</code>, <code>project_name</code>, <code>report_number</code>, <code>report_name</code>, <code>submitted_date</code>, <code>last_submitted_date</code>, <code>trip_number</code>.'
          required: false
          schema:
            type: string
            default: created_time
            pattern: ^(user_name|date|reference_number|created_by_name|amount|status|approver_name|customer_name|employee_no|account_name|project_name|report_number|report_name|submitted_date|last_submitted_date|trip_number|cf_(\w+))$
          example: date
        - name: sort_order
          in: query
          description: 'Sort order. Allowed values: <code>A</code> for ascending, <code>D</code> for descending.'
          required: false
          schema:
            type: string
            default: D
            enum:
              - A
              - D
          example: D
        - name: page
          in: query
          description: Page number to be fetched. Default value is 1.
          required: false
          schema:
            type: integer
            default: 1
          example: 1
        - name: per_page
          in: query
          description: Number of records to be fetched per page. Default value is 200.
          required: false
          schema:
            type: integer
            default: 200
          example: 200
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-advance-payments-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoExpense.advance.READ
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /advancepayments/{advance_payment_id}:
    x-mcp-group:
      - Employee Advances
    put:
      tags:
        - employee-advances
      operationId: update_advance_payment
      summary: Update an advance payment
      description: Update the details of an existing advance payment. Only draft advances can be edited.
      parameters:
        - name: send
          in: query
          description: Whether to submit the advance for approval after update. Allowed values <code>true</code> and <code>false</code>.
          required: false
          schema:
            type: boolean
          example: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-an-advance-payment-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-an-advance-payment-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoExpense.advance.UPDATE
    delete:
      tags:
        - employee-advances
      operationId: delete_advance_payment
      summary: Delete an advance payment
      description: Delete an existing advance payment.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-advance-payment-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoExpense.advance.DELETE
    get:
      tags:
        - employee-advances
      operationId: get_advance_payment
      summary: Retrieve an advance payment
      description: Retrieve the details of an existing advance payment.
      parameters:
        - name: print
          in: query
          description: Whether the response is requested in a printable format. Allowed values <code>true</code> and <code>false</code>.
          required: false
          schema:
            type: boolean
          example: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-advance-payment-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoExpense.advance.READ
    parameters:
      - name: advance_payment_id
        in: path
        required: true
        description: Unique identifier of the advance payment.
        schema:
          type: string
        example: '16367000000243203'
      - $ref: '#/components/parameters/organization_id'
components:
  parameters:
    organization_id:
      name: X-com-zoho-expense-organizationid
      description: ID of the organization
      in: header
      required: true
      schema:
        type: string
      example: '10234695'
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/advance-payment-response'
    advance-payment-response:
      type: object
      properties:
        advance_payment_id:
          $ref: '#/components/schemas/advance_payment_id'
        currency_id:
          $ref: '#/components/schemas/currency_id'
        currency_code:
          $ref: '#/components/schemas/currency_code'
        rcy_currency_id:
          $ref: '#/components/schemas/rcy_currency_id'
        rcy_currency_code:
          $ref: '#/components/schemas/rcy_currency_code'
        refund_currency_id:
          $ref: '#/components/schemas/refund_currency_id'
        account_id:
          $ref: '#/components/schemas/account_id'
        account_name:
          $ref: '#/components/schemas/account_name'
        to_account_id:
          $ref: '#/components/schemas/to_account_id'
        to_account_name:
          $ref: '#/components/schemas/to_account_name'
        reference_number:
          $ref: '#/components/schemas/reference_number'
        notes:
          $ref: '#/components/schemas/notes'
        refund_notes:
          $ref: '#/components/schemas/refund_notes'
        refund_reference_number:
          $ref: '#/components/schemas/refund_reference_number'
        status:
          $ref: '#/components/schemas/status'
        sub_status:
          $ref: '#/components/schemas/sub_status'
        advance_status:
          $ref: '#/components/schemas/advance_status'
        exchange_rate:
          $ref: '#/components/schemas/exchange_rate'
        rcy_exchange_rate:
          $ref: '#/components/schemas/rcy_exchange_rate'
        refund_exchange_rate:
          $ref: '#/components/schemas/refund_exchange_rate'
        amount:
          $ref: '#/components/schemas/amount'
        bcy_amount:
          $ref: '#/components/schemas/bcy_amount'
        rcy_amount:
          $ref: '#/components/schemas/rcy_amount'
        refund_amount:
          $ref: '#/components/schemas/refund_amount'
        refund_bcy_amount:
          $ref: '#/components/schemas/refund_bcy_amount'
        refund_rcy_amount:
          $ref: '#/components/schemas/refund_rcy_amount'
        date:
          $ref: '#/components/schemas/date'
        refund_date:
          $ref: '#/components/schemas/refund_date'
        price_precision:
          $ref: '#/components/schemas/price_precision'
        created_time:
          $ref: '#/components/schemas/created_time'
        created_date:
          $ref: '#/components/schemas/created_date'
        last_modified_time:
          $ref: '#/components/schemas/last_modified_time'
        user_id:
          $ref: '#/components/schemas/user_id'
        user_name:
          $ref: '#/components/schemas/user_name'
        user_email:
          $ref: '#/components/schemas/user_email'
        user_zuid:
          $ref: '#/components/schemas/user_zuid'
        user_photo_url:
          $ref: '#/components/schemas/user_photo_url'
        employee_no:
          $ref: '#/components/schemas/employee_no'
        department_name:
          $ref: '#/components/schemas/department_name'
        policy_id:
          $ref: '#/components/schemas/policy_id'
        policy_name:
          $ref: '#/components/schemas/policy_name'
        created_by:
          $ref: '#/components/schemas/created_by'
        created_by_id:
          $ref: '#/components/schemas/created_by_id'
        created_by_name:
          $ref: '#/components/schemas/created_by_name'
        created_by_email:
          $ref: '#/components/schemas/created_by_email'
        created_by_employee_no:
          $ref: '#/components/schemas/created_by_employee_no'
        creator_photo_url:
          $ref: '#/components/schemas/creator_photo_url'
        submitted_date:
          $ref: '#/components/schemas/submitted_date'
        last_submitted_date:
          $ref: '#/components/schemas/last_submitted_date'
        approved_date:
          $ref: '#/components/schemas/approved_date'
        approver_id:
          $ref: '#/components/schemas/approver_id'
        approver_name:
          $ref: '#/components/schemas/approver_name'
        approver_email:
          $ref: '#/components/schemas/approver_email'
        approver_photo_url:
          $ref: '#/components/schemas/approver_photo_url'
        approver_employee_no:
          $ref: '#/components/schemas/approver_employee_no'
        approver_zuid:
          $ref: '#/components/schemas/approver_zuid'
        submitted_to_id:
          $ref: '#/components/schemas/submitted_to_id'
        submitted_to_name:
          $ref: '#/components/schemas/submitted_to_name'
        submitted_to_email:
          $ref: '#/components/schemas/submitted_to_email'
        submitted_to_employee_no:
          $ref: '#/components/schemas/submitted_to_employee_no'
        customer_id:
          $ref: '#/components/schemas/customer_id'
        customer_name:
          $ref: '#/components/schemas/customer_name'
        project_id:
          $ref: '#/components/schemas/project_id'
        project_name:
          $ref: '#/components/schemas/project_name'
        report_id:
          $ref: '#/components/schemas/report_id'
        report_name:
          $ref: '#/components/schemas/report_name'
        report_number:
          $ref: '#/components/schemas/report_number'
        report_status:
          $ref: '#/components/schemas/report_status'
        trip_id:
          $ref: '#/components/schemas/trip_id'
        trip_number:
          $ref: '#/components/schemas/trip_number'
        trip_name:
          $ref: '#/components/schemas/trip_name'
        trip_status:
          $ref: '#/components/schemas/trip_status'
        is_carried_forward_advance:
          $ref: '#/components/schemas/is_carried_forward_advance'
        reference_report_id:
          $ref: '#/components/schemas/reference_report_id'
        refund_recorded_by:
          $ref: '#/components/schemas/refund_recorded_by'
        refund_recorded_by_id:
          $ref: '#/components/schemas/refund_recorded_by_id'
        location_id:
          $ref: '#/components/schemas/location_id'
        documents:
          $ref: '#/components/schemas/documents'
        expense_reports:
          $ref: '#/components/schemas/expense_reports'
        comments:
          $ref: '#/components/schemas/comments'
        custom_fields:
          $ref: '#/components/schemas/custom_fields'
    advance_payment_id:
      description: Unique identifier of the advance payment.
      type: string
      example: '16367000000243203'
    currency_id:
      description: Unique identifier of the currency.
      type: string
      example: '16367000000000099'
    currency_code:
      description: Currency code.
      type: string
      example: USD
    rcy_currency_id:
      description: Unique identifier of the reimbursement currency.
      type: string
      example: '16367000000000099'
    rcy_currency_code:
      description: Reimbursement currency code.
      type: string
      example: USD
    refund_currency_id:
      description: Unique identifier of the refund currency.
      type: string
      example: '16367000000000099'
    account_id:
      description: Unique identifier of the paid-through account.
      type: string
      example: '16367000000036003'
    account_name:
      description: Name of the paid-through account.
      type: string
      example: Petty Cash
    to_account_id:
      description: Unique identifier of the destination account.
      type: string
      example: '16367000000036007'
    to_account_name:
      description: Name of the destination account.
      type: string
      example: Employee Advance
    reference_number:
      description: Reference number of the advance payment. Max-length [50].
      type: string
      example: ADV-00001
    notes:
      description: Notes on the advance payment. Max-length [255].
      type: string
      example: Advance for business trip to New York.
    refund_notes:
      description: Notes recorded with the refund.
      type: string
      example: Refund credited to petty cash.
    refund_reference_number:
      description: Reference number of the refund.
      type: string
      example: REF-00001
    status:
      description: 'Status of the advance payment. Possible values: <code>draft</code>, <code>submitted</code>, <code>approved</code>, <code>rejected</code>, <code>recalled</code>, <code>void</code>.'
      type: string
      example: approved
    sub_status:
      description: Custom status of the advance payment.
      type: string
      example: ''
    advance_status:
      description: 'Applied status of the advance against expense reports. Possible values: <code>applied</code>, <code>unapplied</code>.'
      type: string
      example: unapplied
    exchange_rate:
      description: Exchange rate of the foreign currency.
      type: number
      format: double
      example: 1
    rcy_exchange_rate:
      description: Exchange rate for the reimbursement currency.
      type: number
      format: double
      example: 1
    refund_exchange_rate:
      description: Exchange rate for the refund currency.
      type: number
      format: double
      example: 1
    amount:
      description: Amount of the advance payment in the transaction currency.
      type: number
      format: double
      example: 5000
    bcy_amount:
      description: Advance amount in base currency.
      type: number
      format: double
      example: 5000
    rcy_amount:
      description: Advance amount in reimbursement currency.
      type: number
      format: double
      example: 5000
    refund_amount:
      description: Refund amount in the transaction currency.
      type: number
      format: double
      example: 5000
    refund_bcy_amount:
      description: Refund amount in base currency.
      type: number
      format: double
      example: 5000
    refund_rcy_amount:
      description: Refund amount in reimbursement currency.
      type: number
      format: double
      example: 5000
    date:
      description: Date of the advance payment in <code>yyyy-MM-dd</code> format.
      type: string
      example: '2024-01-15'
    refund_date:
      description: Date on which the refund was recorded.
      type: string
      example: '2024-01-30'
    price_precision:
      description: Decimal precision for amounts.
      type: integer
      example: 2
    created_time:
      description: Date and time when the advance payment was created.
      type: string
      example: 2024-01-15T10:30:00+0530
    created_date:
      description: Date when the advance payment was created.
      type: string
      example: '2024-01-15'
    last_modified_time:
      description: Date and time when the advance payment was last modified.
      type: string
      example: 2024-01-15T12:00:00+0530
    user_id:
      description: Unique identifier of the employee receiving the advance.
      type: string
      example: '16367000000073001'
    user_name:
      description: Name of the employee receiving the advance.
      type: string
      example: Will Smith
    user_email:
      description: Email address of the employee receiving the advance.
      type: string
      example: will.smith@zillum.com
    user_zuid:
      description: ZUID of the employee receiving the advance.
      type: string
      example: '12345678'
    user_photo_url:
      description: Photo URL of the employee receiving the advance.
      type: string
      example: https://contacts.zoho.com/file?ID=abc123&fs=thumb
    employee_no:
      description: Employee number of the employee.
      type: string
      example: E001
    department_name:
      description: Department of the employee.
      type: string
      example: Finance
    policy_id:
      description: Unique identifier of the policy.
      type: string
      example: '16367000000092011'
    policy_name:
      description: Name of the policy.
      type: string
      example: Default Policy
    created_by:
      description: Name of the user who created the advance payment.
      type: string
      example: Will Smith
    created_by_id:
      description: Unique identifier of the user who created the advance payment.
      type: string
      example: '16367000000073071'
    created_by_name:
      description: Name of the user who created the advance payment.
      type: string
      example: Will Smith
    created_by_email:
      description: Email address of the user who created the advance payment.
      type: string
      example: will.smith@zillum.com
    created_by_employee_no:
      description: Employee number of the user who created the advance payment.
      type: string
      example: E002
    creator_photo_url:
      description: Photo URL of the user who created the advance payment.
      type: string
      example: https://contacts.zoho.com/file?ID=abc123&fs=thumb
    submitted_date:
      description: Date when the advance payment was submitted.
      type: string
      example: '2024-01-16'
    last_submitted_date:
      description: Date when the advance payment was last submitted.
      type: string
      example: '2024-01-16'
    approved_date:
      description: Date when the advance payment was approved.
      type: string
      example: '2024-01-17'
    approver_id:
      description: Unique identifier of the approver.
      type: string
      example: '16367000000073001'
    approver_name:
      description: Name of the approver.
      type: string
      example: PATRICIA BOYLE
    approver_email:
      description: Email address of the approver.
      type: string
      example: patriciab@zillum.com
    approver_photo_url:
      description: Photo URL of the approver.
      type: string
      example: https://contacts.zoho.com/file?ID=abc123&fs=thumb
    approver_employee_no:
      description: Employee number of the approver.
      type: string
      example: E001
    approver_zuid:
      description: ZUID of the approver.
      type: string
      example: '23456789'
    submitted_to_id:
      description: Unique identifier of the user the advance was submitted to.
      type: string
      example: '16367000000073001'
    submitted_to_name:
      description: Name of the user the advance was submitted to.
      type: string
      example: PATRICIA BOYLE
    submitted_to_email:
      description: Email address of the user the advance was submitted to.
      type: string
      example: patriciab@zillum.com
    submitted_to_employee_no:
      description: Employee number of the user the advance was submitted to.
      type: string
      example: E001
    customer_id:
      description: Unique identifier of the customer.
      type: string
      example: '16367000000088005'
    customer_name:
      description: Name of the customer.
      type: string
      example: Zillum Corp
    project_id:
      description: Unique identifier of the project.
      type: string
      example: '16367000000223045'
    project_name:
      description: Name of the project.
      type: string
      example: Brochure Design
    report_id:
      description: Unique identifier of the linked expense report.
      type: string
      example: '16367000000081005'
    report_name:
      description: Name of the linked expense report.
      type: string
      example: Trip to SFA
    report_number:
      description: Number of the linked expense report.
      type: string
      example: ER-00001
    report_status:
      description: Status of the linked expense report.
      type: string
      example: approved
    trip_id:
      description: Unique identifier of the associated trip.
      type: string
      example: '16367000000312001'
    trip_number:
      description: Trip number of the associated trip.
      type: string
      example: TR-00001
    trip_name:
      description: Name of the associated trip.
      type: string
      example: Business trip to New York
    trip_status:
      description: Status of the associated trip.
      type: string
      example: approved
    is_carried_forward_advance:
      description: Whether the advance is carried forward from a previous report. Allowed values <code>true</code> and <code>false</code>.
      type: boolean
      example: false
    reference_report_id:
      description: Unique identifier of the reference report for a carried-forward advance.
      type: string
      example: '16367000000081005'
    refund_recorded_by:
      description: Name of the user who recorded the refund.
      type: string
      example: Will Smith
    refund_recorded_by_id:
      description: Unique identifier of the user who recorded the refund.
      type: string
      example: '16367000000073071'
    location_id:
      description: Unique identifier of the location.
      type: string
      example: '16367000000401005'
    file_name:
      description: Name of the attached document.
      type: string
      example: receipt.pdf
    file_size_formatted:
      description: Formatted file size of the attached document.
      type: string
      example: 45.2 KB
    document_id:
      description: Unique identifier of the document.
      type: string
      example: '16367000000078085'
    attachment_order:
      description: Order of the attached document.
      type: integer
      example: 1
    documents:
      description: Documents attached to the advance payment.
      type: array
      items:
        type: object
        properties:
          document_id:
            $ref: '#/components/schemas/document_id'
          file_name:
            $ref: '#/components/schemas/file_name'
          file_size_formatted:
            $ref: '#/components/schemas/file_size_formatted'
          attachment_order:
            $ref: '#/components/schemas/attachment_order'
    reimbursement_entity_id:
      description: Unique identifier of the reimbursement entity.
      type: string
      example: '16367000000501001'
    report_amount:
      description: Amount applied from the advance to the expense report.
      type: number
      format: double
      example: 3000
    report_date:
      description: Date the advance was applied to the expense report.
      type: string
      example: '2024-01-20'
    expense_reports:
      description: Expense reports associated with the advance payment.
      type: array
      items:
        type: object
        properties:
          reimbursement_entity_id:
            $ref: '#/components/schemas/reimbursement_entity_id'
          report_id:
            $ref: '#/components/schemas/report_id'
          report_name:
            $ref: '#/components/schemas/report_name'
          amount:
            $ref: '#/components/schemas/report_amount'
          date:
            $ref: '#/components/schemas/report_date'
          report_number:
            $ref: '#/components/schemas/report_number'
          report_status:
            $ref: '#/components/schemas/report_status'
    comment_id:
      description: Unique identifier of the comment.
      type: string
      example: '16367000000601001'
    commented_by:
      description: Name of the person who posted the comment.
      type: string
      example: PATRICIA BOYLE
    commented_by_id:
      description: Unique identifier of the commenter.
      type: string
      example: '16367000000073001'
    comment_date:
      description: Date the comment was posted.
      type: string
      example: '2024-01-17'
    comment_type:
      description: Type of comment entry.
      type: string
      example: comment
    comment_previous_status:
      description: Previous status of the advance before the comment action.
      type: string
      example: submitted
    comment_approval_status:
      description: Approval status at the time of the comment.
      type: string
      example: approved
    comments:
      description: Comments and approval history of the advance payment.
      type: array
      items:
        type: object
        properties:
          comment_id:
            $ref: '#/components/schemas/comment_id'
          advance_id:
            $ref: '#/components/schemas/advance_payment_id'
          commented_by:
            $ref: '#/components/schemas/commented_by'
          commented_by_id:
            $ref: '#/components/schemas/commented_by_id'
          date:
            $ref: '#/components/schemas/comment_date'
          type:
            $ref: '#/components/schemas/comment_type'
          previous_status:
            $ref: '#/components/schemas/comment_previous_status'
          approval_status:
            $ref: '#/components/schemas/comment_approval_status'
    customfield_id:
      description: Unique identifier of the custom field.
      type: string
      example: '16367000000277001'
    label:
      description: Label of the custom field.
      type: string
      example: Department Code
    value:
      description: Value of the custom field.
      type: string
      example: FIN-001
    custom_fields:
      description: Custom fields associated with the advance payment.
      type: array
      items:
        type: object
        properties:
          customfield_id:
            $ref: '#/components/schemas/customfield_id'
          label:
            $ref: '#/components/schemas/label'
          value:
            $ref: '#/components/schemas/value'
    page:
      description: Current page number.
      type: integer
      example: 1
    per_page:
      description: Number of records per page. Default value is 200.
      type: integer
      example: 200
    has_more_page:
      description: Whether more pages are available. Allowed values <code>true</code> and <code>false</code>.
      type: boolean
      example: false
    sort_column_page_context:
      description: Column by which results are sorted.
      type: string
      example: created_time
    sort_order_page_context:
      description: 'Sort order applied. Allowed values: <code>A</code> for ascending, <code>D</code> for descending.'
      type: string
      example: D
    report_name_page_context:
      description: Name of the internal report used for this list.
      type: string
      example: Advance Payment Details
    applied_filter:
      description: Filter applied to the list.
      type: string
      example: Status.All
    page_context:
      type: object
      properties:
        page:
          $ref: '#/components/schemas/page'
        per_page:
          $ref: '#/components/schemas/per_page'
        has_more_page:
          $ref: '#/components/schemas/has_more_page'
        report_name:
          $ref: '#/components/schemas/report_name_page_context'
        applied_filter:
          $ref: '#/components/schemas/applied_filter'
        sort_column:
          $ref: '#/components/schemas/sort_column_page_context'
        sort_order:
          $ref: '#/components/schemas/sort_order_page_context'
    create-an-advance-payment-request:
      type: object
      required:
        - currency_id
        - amount
        - date
        - user_id
      properties:
        date:
          description: Date of the advance in <code>yyyy-MM-dd</code> format.
          type: string
          example: '2024-02-15'
        amount:
          description: Advance amount in the document currency.
          type: number
          format: double
          example: 5000
        exchange_rate:
          description: Exchange rate to base currency.
          type: number
          format: double
          example: 1
        rcy_exchange_rate:
          description: Exchange rate to reimbursement currency.
          type: number
          format: double
          example: 1
        notes:
          description: Notes on the advance. Max-length [255].
          type: string
          maxLength: 255
          example: Travel advance for client visit.
        reference_number:
          description: Reference number. Max-length [50].
          type: string
          maxLength: 50
          example: ADV-00001
        currency_id:
          description: Unique ID of the currency.
          type: string
          example: '16367000000000099'
        account_id:
          description: Unique ID of the paid-through account.
          type: string
          example: '16367000000036003'
        user_id:
          description: Unique ID of the user receiving the advance.
          type: string
          example: '16367000000073001'
        trip_id:
          description: Unique ID of the linked trip.
          type: string
          example: '34017000000000103'
        customer_id:
          description: Unique ID of the customer.
          type: string
          example: '16367000000088005'
        project_id:
          description: Unique ID of the project.
          type: string
          example: '16367000000223045'
        location_id:
          description: Unique ID of the location.
          type: string
          example: '16367000000110001'
        custom_fields:
          description: Custom fields recorded against the advance.
          type: array
          items:
            type: object
            properties:
              customfield_id:
                $ref: '#/components/schemas/customfield_id'
              value:
                $ref: '#/components/schemas/value'
    update-an-advance-payment-request:
      type: object
      allOf:
        - $ref: '#/components/schemas/create-an-advance-payment-request'
    create-an-advance-payment-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Employee advance has been created successfully.
          readOnly: true
        advance_payment:
          $ref: '#/components/schemas/advance-payment-response'
    update-an-advance-payment-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Employee advance has been updated successfully.
          readOnly: true
        advance_payment:
          $ref: '#/components/schemas/advance-payment-response'
    delete-advance-payment-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Employee advance has been deleted successfully.
          readOnly: true
    get-advance-payment-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        advance_payment:
          $ref: '#/components/schemas/advance-payment-response'
    list-advance-payments-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        advance_payments:
          type: array
          items:
            $ref: '#/components/schemas/advance-payment-response'
        page_context:
          $ref: '#/components/schemas/page_context'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoExpense.advance.CREATE: Create advance payment
            ZohoExpense.advance.READ: Read advance payment
            ZohoExpense.advance.UPDATE: Update advance payment
            ZohoExpense.advance.DELETE: Delete advance payment
