openapi: 3.0.0
info:
  title: Currency
  description: In case your organization sells products or provides services to customer from different countries, you can add those currencies and exchange rates you deal with, to your Zoho Books account.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/books/v3
    description: API Endpoint
tags:
  - name: currency
    description: Currency Module
paths:
  /settings/currencies:
    post:
      tags:
        - currency
      operationId: create_currency
      summary: Create a Currency
      description: Create a currency for transaction.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-a-currency-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-a-currency-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    get:
      tags:
        - currency
      operationId: list_currencies
      summary: List Currencies
      description: Get list of currencies configured.
      parameters:
        - name: filter_by
          in: query
          description: 'Filter currencies excluding base currency. Allowed Values: <code>Currencies.ExcludeBaseCurrency</code>'
          required: false
          schema:
            type: string
          example: ''
        - 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-currencies-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /settings/currencies/{currency_id}:
    put:
      tags:
        - currency
      operationId: update_currency
      summary: Update a Currency
      description: Update the details of a currency.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-a-currency-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-a-currency-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    get:
      tags:
        - currency
      operationId: get_currency
      summary: Get a Currency
      description: Get the details of a currency.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-a-currency-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    delete:
      tags:
        - currency
      operationId: delete_currency
      summary: Delete a currency
      description: Delete a currency. Currency that is associated to transactions cannot be deleted.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-a-currency-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.DELETE
    parameters:
      - name: currency_id
        in: path
        schema:
          type: string
        required: true
        description: Unique identifier of the currency.
        example: '982000000004012'
      - $ref: '#/components/parameters/organization_id'
  /settings/currencies/{currency_id}/exchangerates:
    get:
      tags:
        - currency
      operationId: list_exchange_rates
      summary: List exchange rates
      description: List of exchange rates configured for the currency.
      parameters:
        - name: from_date
          in: query
          description: Returns the exchange rate details from the given date or from previous closest match in the absence of the exchange rate on the given date.
          required: false
          schema:
            type: string
          example: '2017-01-02'
        - name: is_current_date
          in: query
          description: To return the exchange rate only if available for current date.
          required: false
          schema:
            type: boolean
          example: true
        - name: sort_column
          in: query
          description: 'Sorts the exchange rate according to this column. Allowed Values : <code>effective_date</code>'
          required: false
          schema:
            type: string
          example: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-exchange-rates-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    post:
      tags:
        - currency
      operationId: create_exchange_rate
      summary: Create an exchange rate
      description: Create an exchange rate for the specified currency.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-an-exchange-rate-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-an-exchange-rate-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      - name: currency_id
        in: path
        required: true
        description: Unique identifier of the currency.
        schema:
          type: string
        example: '982000000004012'
      - $ref: '#/components/parameters/organization_id'
  /settings/currencies/{currency_id}/exchangerates/{exchange_rate_id}:
    get:
      tags:
        - currency
      operationId: get_exchange_rate
      summary: Get an exchange rate.
      description: Get the details of an exchange rate that has been asscoiated to the currency.
      parameters:
        - name: exchange_rate_id
          in: path
          required: true
          description: Unique identifier of the exchange rate.
          schema:
            type: string
          example: '460000000038035'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-an-exchange-rate-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.READ
    put:
      tags:
        - currency
      operationId: update_exchange_rate
      summary: Update an exchange rate
      description: Update the details of exchange rate for a currency.
      parameters:
        - name: exchange_rate_id
          in: path
          required: true
          description: Unique identifier of the exchange rate.
          schema:
            type: string
          example: '460000000038035'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-an-exchange-rate-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-an-exchange-rate-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    delete:
      tags:
        - currency
      operationId: delete_exchange_rate
      summary: Delete an exchage rate
      description: Delete an exchange rate for the specified currency.
      parameters:
        - name: exchange_rate_id
          in: path
          required: true
          description: Unique identifier of the exchange rate.
          schema:
            type: string
          example: '460000000038035'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-an-exchage-rate-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoBooks.settings.DELETE
    parameters:
      - name: currency_id
        in: path
        required: true
        description: Unique identifier of the currency.
        schema:
          type: string
        example: '982000000004012'
      - $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:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/currency'
    currency_id:
      description: A unique ID for the currency.
      type: string
      example: '982000000004012'
    currency_code:
      description: A unique standard code for the currency. Max-len [100]
      type: string
      example: AUD
    currency_name:
      description: The name for the currency.
      type: string
      example: AUD- Australian Dollar
    currency_symbol:
      description: A unique symbol for the currency. Max-len [4]
      type: string
      example: $
    price_precision:
      description: The precision for the price
      type: integer
      example: 2
    currency_format:
      description: The format for the currency to be displayed. Max-len [100]
      type: string
      example: 1,234,567.89
    is_base_currency:
      description: Is it the base currency of the organization.
      type: boolean
      example: false
    exchange_rate:
      description: Exchange rate for the currency.
      type: number
      format: double
      example: 1
    page:
      type: integer
      example: 1
    per_page:
      type: integer
      example: 200
    report_name:
      type: string
      example: Currencies
    exchange_rate_id:
      description: ID of the exchange rate
      type: string
      example: '460000000038035'
    effective_date:
      description: Date which the exchange rate is applicable for the currency.
      type: string
      example: '2013-09-04'
    rate:
      description: Rate of exchange for the currency with respect to base currency.
      type: number
      format: double
      example: 1.23
    has_more_page:
      type: boolean
      example: false
    from_date:
      description: Returns the exchange rate details from the given date or from previous closest match in the absence of the exchange rate on the given date.
      type: string
      example: '2017-01-02'
    is_current_date:
      description: To return the exchange rate only if available for current date.
      type: boolean
      example: true
    filter_by:
      description: 'Filter currencies excluding base currency. Allowed Values: <code>Currencies.ExcludeBaseCurrency</code>'
      type: string
    currency:
      type: object
      properties:
        currency_id:
          $ref: '#/components/schemas/currency_id'
        currency_code:
          $ref: '#/components/schemas/currency_code'
        currency_name:
          $ref: '#/components/schemas/currency_name'
        currency_symbol:
          $ref: '#/components/schemas/currency_symbol'
        price_precision:
          $ref: '#/components/schemas/price_precision'
        currency_format:
          $ref: '#/components/schemas/currency_format'
        is_base_currency:
          $ref: '#/components/schemas/is_base_currency'
    sort_column:
      description: 'Sorts the exchange rate according to this column. Allowed Values : <code>effective_date</code>'
      type: string
    create-a-currency-request:
      required:
        - currency_code
        - currency_format
      type: object
      properties:
        currency_code:
          $ref: '#/components/schemas/currency_code'
        currency_symbol:
          $ref: '#/components/schemas/currency_symbol'
        price_precision:
          $ref: '#/components/schemas/price_precision'
        currency_format:
          $ref: '#/components/schemas/currency_format'
    create-a-currency-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The currency has been added.
          readOnly: true
        currency:
          $ref: '#/components/schemas/currency'
    list-currencies-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        currencies:
          type: array
          items:
            type: object
            properties:
              currency_id:
                $ref: '#/components/schemas/currency_id'
              currency_code:
                $ref: '#/components/schemas/currency_code'
              currency_name:
                $ref: '#/components/schemas/currency_name'
              currency_symbol:
                $ref: '#/components/schemas/currency_symbol'
              price_precision:
                $ref: '#/components/schemas/price_precision'
              currency_format:
                $ref: '#/components/schemas/currency_format'
              is_base_currency:
                $ref: '#/components/schemas/is_base_currency'
              exchange_rate:
                $ref: '#/components/schemas/exchange_rate'
              effective_date:
                $ref: '#/components/schemas/effective_date'
    update-a-currency-request:
      required:
        - currency_code
        - currency_format
      type: object
      properties:
        currency_code:
          $ref: '#/components/schemas/currency_code'
        currency_symbol:
          $ref: '#/components/schemas/currency_symbol'
        price_precision:
          $ref: '#/components/schemas/price_precision'
        currency_format:
          $ref: '#/components/schemas/currency_format'
    update-a-currency-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Currency information has been saved.
          readOnly: true
        currency:
          $ref: '#/components/schemas/currency'
    get-a-currency-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        currency:
          $ref: '#/components/schemas/currency'
    delete-a-currency-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The currency has been deleted.
          readOnly: true
    list-exchange-rates-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        exchange_rates:
          type: array
          items:
            type: object
            properties:
              exchange_rate_id:
                $ref: '#/components/schemas/exchange_rate_id'
              currency_id:
                $ref: '#/components/schemas/currency_id'
              currency_code:
                $ref: '#/components/schemas/currency_code'
              effective_date:
                $ref: '#/components/schemas/effective_date'
              rate:
                $ref: '#/components/schemas/rate'
    create-an-exchange-rate-request:
      type: object
      properties:
        effective_date:
          $ref: '#/components/schemas/effective_date'
        rate:
          $ref: '#/components/schemas/rate'
    create-an-exchange-rate-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The exchange rate has been added.
          readOnly: true
        exchange_rate:
          $ref: '#/components/schemas/exchange_rate'
    get-an-exchange-rate-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        exchange_rate:
          $ref: '#/components/schemas/exchange_rate'
    update-an-exchange-rate-request:
      type: object
      properties:
        effective_date:
          $ref: '#/components/schemas/effective_date'
        rate:
          $ref: '#/components/schemas/rate'
    update-an-exchange-rate-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: The exchange rate has been updated.
          readOnly: true
    delete-an-exchage-rate-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: Exchange rate successfully deleted
          readOnly: true
  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
