openapi: 3.0.0
info:
  title: 'Locations'
  description: "Create locations for each branch and warehouse in your organisation and manage them all in one place.\nIn this document, you can learn how to create and manage locations in Zoho Books."
  contact: {}
  version: 1.0.0
servers:
  -
    url: 'https://www.zohoapis.com/books/v3'
    description: 'API Endpoint'
tags:
  -
    name: locations
    description: 'Locations Module'
paths:
  /settings/locations/enable:
    post:
      tags:
        - locations
      operationId: 'enable_locations'
      summary: 'Enable Locations'
      description: 'Enable Locations for an organisation.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/enable-location-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      -
        $ref: '#/components/parameters/organization_id'
  /locations:
    post:
      tags:
        - locations
      operationId: 'create_location'
      summary: 'Create a location'
      description: 'Create a location.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-a-location-request'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-a-location-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.settings.CREATE
    get:
      tags:
        - locations
      operationId: 'list_locations'
      summary: 'List all locations'
      description: 'List all the available locations in your zoho inventory.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-all-location-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.settings.READ
    parameters:
      -
        $ref: '#/components/parameters/organization_id'
  '/locations/{location_id}':
    put:
      tags:
        - locations
      operationId: 'update_location'
      summary: 'Update location'
      description: 'Update location'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-location-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-location-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.settings.UPDATE
    delete:
      tags:
        - locations
      operationId: 'delete_location'
      summary: 'Delete a location'
      description: 'Delete a location.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-a-location-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.settings.DELETE
    parameters:
      -
        name: location_id
        in: path
        required: true
        schema:
          type: string
        example: 130426000000664020
      -
        $ref: '#/components/parameters/organization_id'
  '/locations/{location_id}/active':
    post:
      tags:
        - locations
      operationId: 'mark_location_active'
      summary: 'Mark as Active'
      description: 'Mark location as Active.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mark-as-active-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      -
        name: location_id
        in: path
        required: true
        schema:
          type: string
        example: 130426000000664020
      -
        $ref: '#/components/parameters/organization_id'
  '/locations/{location_id}/inactive':
    post:
      tags:
        - locations
      operationId: 'mark_location_inactive'
      summary: 'Mark as Inactive'
      description: 'Mark location as Inactive.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mark-as-inactive-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      -
        name: location_id
        in: path
        required: true
        schema:
          type: string
        example: 130426000000664020
      -
        $ref: '#/components/parameters/organization_id'
  '/locations/{location_id}/markasprimary':
    post:
      tags:
        - locations
      operationId: 'mark_location_primary'
      summary: 'Mark as Primary'
      description: 'Mark location as primary.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mark-as-primary-response'
      deprecated: false
      security:
        -
          Zoho_Auth:
            - ZohoBooks.settings.CREATE
    parameters:
      -
        name: location_id
        in: path
        required: true
        schema:
          type: string
        example: 130426000000664020
      -
        $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/locations'
    location_id:
      description: 'Location ID'
      type: string
      example: '460000000038080'
    location_name:
      description: 'Name of the location'
      type: string
      example: 'Head Office'
    type:
      description: 'Type of the location'
      type: string
      example: 'general / line_item_only'
    parent_location_id:
      description: 'Parent Location ID'
      type: string
      example: '460000000041010'
    tax_settings_id:
      description: 'Tax Settings ID'
      type: string
      example: '460000000038080'
      x-node_available_in:
        - in
      x-node_unavailable_in: [ ]
    city:
      description: 'City Name of the location.'
      type: string
      example: 'New York City'
    state:
      description: 'State Name of the location.'
      type: string
      example: 'New York'
    country:
      description: 'Country Name of the location.'
      type: string
      example: U.S.A
    attention:
      description: 'Attention of the location.'
      type: string
    state_code:
        description: 'State code of the location.'
        type: string
        example: NY
    zip:
      description: 'Zipcode of the location.'
      type: string
      example: 11364
    street_address1:
      description: 'Street Name of the location.'
      type: string
      example: 'No:234,90 Church Street'
    street_address2:
      description: 'Street Name of the location.'
      type: string
      example: 'McMillan Avenue'
    autonumbergenerationgroup_id:
      description: 'Autonumber generation group ID'
      type: string
      example: '982000000870911'
    address:
      type: object
      properties:
        city:
          $ref: '#/components/schemas/city'
        state:
          $ref: '#/components/schemas/state'
        country:
          $ref: '#/components/schemas/country'
        attention:
          $ref: '#/components/schemas/attention'
        state_code:
          $ref: '#/components/schemas/state_code'
        street_address1:
          $ref: '#/components/schemas/street_address1'
        street_address2:
          $ref: '#/components/schemas/street_address2'
    associated_series_ids:
      type: array
      items:
        type: string
      example:
        - '982000000870911'
        - '982000000870915'
    user_id:
        description: 'User ID'
        type: string
        example: '460000000036868'
    user_name:
        description: 'User Name'
        type: string
        example: 'John Doe'
    user_ids:
      description: 'Comma separated user ids.'
      type: string
      example: '460000000036868,460000000036869'
    is_all_users_selected:
      description: 'Whether all users are selected or not'
      type: boolean
      example: false
    is_primary:
      description: 'Whether it is primary location or not'
      type: boolean
      example: true
    locations:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/address'
        email:
          $ref: '#/components/schemas/email'
        is_primary:
          $ref: '#/components/schemas/is_primary'
        phone:
          $ref: '#/components/schemas/phone'
        status:
          $ref: '#/components/schemas/status'
        location_id:
          $ref: '#/components/schemas/location_id'
        location_name:
          $ref: '#/components/schemas/location_name'
        type:
          $ref: '#/components/schemas/type'
        parent_location_id:
          $ref: '#/components/schemas/parent_location_id'
        associated_series_ids:
          $ref: '#/components/schemas/associated_series_ids'
        auto_number_generation_id:
          $ref: '#/components/schemas/autonumbergenerationgroup_id'
        associated_users:
          type: array
          items:
            type: object
            properties:
              user_id:
                $ref: '#/components/schemas/user_id'
              user_name:
                $ref: '#/components/schemas/user_name'
        tax_settings_id:
            $ref: '#/components/schemas/tax_settings_id'
    status:
      description: 'Status of the locations. Allowed Values: <code>active</code>, <code>inactive</code>'
      example: active
    phone:
      description: 'Mobile number for location'
      type: string
      example: +1-925-921-9201
    email:
      description: 'Email id for the location'
      type: string
      example: willsmith@bowmanfurniture.com
    enable-location-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: "We're enabling locations for your organization."
          readOnly: true
    create-a-location-request:
      required:
        - location_name
        - country
        - tax_settings_id
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type'
        email:
          $ref: '#/components/schemas/email'
        phone:
          $ref: '#/components/schemas/phone'
        address:
          $ref: '#/components/schemas/address'
        location_name:
          $ref: '#/components/schemas/location_name'
        tax_settings_id:
          $ref: '#/components/schemas/tax_settings_id'
        parent_location_id:
          $ref: '#/components/schemas/parent_location_id'
        associated_series_ids:
          $ref: '#/components/schemas/associated_series_ids'
        auto_number_generation_id:
          $ref: '#/components/schemas/autonumbergenerationgroup_id'
        is_all_users_selected:
          $ref: '#/components/schemas/is_all_users_selected'
        user_ids:
          $ref: '#/components/schemas/user_ids'
    create-a-location-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'Location has been created.'
          readOnly: true
        locations:
          $ref: '#/components/schemas/locations'
    list-all-location-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        locations:
          type: array
          items:
            type: object
            properties:
              type:
                $ref: '#/components/schemas/type'
              email:
                $ref: '#/components/schemas/email'
              phone:
                $ref: '#/components/schemas/phone'
              address:
                $ref: '#/components/schemas/address'
              location_id:
                $ref: '#/components/schemas/location_id'
              location_name:
                $ref: '#/components/schemas/location_name'
              tax_settings_id:
                $ref: '#/components/schemas/tax_settings_id'
              parent_location_id:
                $ref: '#/components/schemas/parent_location_id'
              associated_series_ids:
                $ref: '#/components/schemas/associated_series_ids'
              auto_number_generation_id:
                $ref: '#/components/schemas/autonumbergenerationgroup_id'
              is_all_users_selected:
                $ref: '#/components/schemas/is_all_users_selected'
              associated_users:
                type: array
                items:
                  type: object
                  properties:
                    user_id:
                      $ref: '#/components/schemas/user_id'
                    user_name:
                      $ref: '#/components/schemas/user_name'
    update-location-request:
      required:
        - location_name
        - country
        - tax_settings_id
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type'
        email:
          $ref: '#/components/schemas/email'
        phone:
          $ref: '#/components/schemas/phone'
        address:
          $ref: '#/components/schemas/address'
        location_name:
          $ref: '#/components/schemas/location_name'
        tax_settings_id:
          $ref: '#/components/schemas/tax_settings_id'
        parent_location_id:
          $ref: '#/components/schemas/parent_location_id'
        associated_series_ids:
          $ref: '#/components/schemas/associated_series_ids'
        auto_number_generation_id:
          $ref: '#/components/schemas/autonumbergenerationgroup_id'
        is_all_users_selected:
          $ref: '#/components/schemas/is_all_users_selected'
        user_ids:
          $ref: '#/components/schemas/user_ids'
    update-location-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'Location has been updated.'
          readOnly: true
        locations:
          $ref: '#/components/schemas/locations'
    delete-a-location-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'The location has been deleted..'
          readOnly: true
    mark-as-active-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'The location has been marked as active.'
          readOnly: true
    mark-as-inactive-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'The location has been marked as inactive.'
          readOnly: true
    mark-as-primary-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: 'The location has been marked as primary.'
          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'
