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.
    In this document, you can learn how to create and manage locations in Zoho Inventory.
  contact: {}
  version: 1.0.0
servers:
  - url: https://www.zohoapis.com/inventory/v1
    description: API Endpoint
tags:
  - name: locations
    description: Locations Module
paths:
  /settings/locations/enable:
    x-mcp-group:
      - Locations
    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:
            - ZohoInventory.settings.CREATE
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /locations:
    x-mcp-group:
      - 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:
            - ZohoInventory.settings.CREATE
    get:
      tags:
        - locations
      operationId: list_locations
      summary: List all locations
      description: List all the available locations in your zoho inventory.
      parameters:
        - name: is_hierarchical_response
          in: query
          description: When set to <code>true</code>, returns the locations in a parent-child hierarchical structure instead of a flat list.
          required: false
          schema:
            type: boolean
          example: false
        - name: location_type
          in: query
          description: 'Filter locations by type. Allowed Values: <code>general</code> and <code>line_item_only</code>.'
          required: false
          schema:
            type: string
            enum:
              - general
              - line_item_only
          example: general
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-all-location-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.READ
    parameters:
      - $ref: '#/components/parameters/organization_id'
  /locations/{location_id}:
    x-mcp-group:
      - Locations
    get:
      tags:
        - locations
      operationId: get_location
      summary: Get a location
      description: Get the details of a location.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-a-location-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.READ
    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:
            - ZohoInventory.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:
            - ZohoInventory.settings.DELETE
    parameters:
      - name: location_id
        in: path
        required: true
        description: Unique identifier of the location.
        schema:
          type: string
        example: 130426000000664020
      - $ref: '#/components/parameters/organization_id'
  /locations/{location_id}/active:
    x-mcp-group:
      - Locations
    post:
      tags:
        - locations
      operationId: mark_location_as_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:
            - ZohoInventory.settings.CREATE
    parameters:
      - name: location_id
        in: path
        required: true
        description: Unique identifier of the location.
        schema:
          type: string
        example: 130426000000664020
      - $ref: '#/components/parameters/organization_id'
  /locations/{location_id}/inactive:
    x-mcp-group:
      - Locations
    post:
      tags:
        - locations
      operationId: mark_location_as_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:
            - ZohoInventory.settings.CREATE
    parameters:
      - name: location_id
        in: path
        required: true
        description: Unique identifier of the location.
        schema:
          type: string
        example: 130426000000664020
      - $ref: '#/components/parameters/organization_id'
  /locations/{location_id}/markasprimary:
    x-mcp-group:
      - Locations
    post:
      tags:
        - locations
      operationId: mark_location_as_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:
            - ZohoInventory.settings.CREATE
    parameters:
      - name: location_id
        in: path
        required: true
        description: Unique identifier of the location.
        schema:
          type: string
        example: 130426000000664020
      - $ref: '#/components/parameters/organization_id'
  /locations/{location_id}/users:
    x-mcp-group:
      - Locations
    get:
      tags:
        - locations
      operationId: list_users_of_a_location
      summary: List users of a location
      description: List the users associated with a location.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-users-of-a-location-response'
      deprecated: false
      security:
        - Zoho_Auth:
            - ZohoInventory.settings.READ
    parameters:
      - name: location_id
        in: path
        required: true
        description: Unique identifier of the location.
        schema:
          type: string
        example: 130426000000664020
      - $ref: '#/components/parameters/organization_id'
      - name: page
        in: query
        required: false
        description: Page number for paginated results.
        schema:
          type: integer
        example: 1
      - name: per_page
        in: query
        required: false
        description: Number of records to return per page.
        schema:
          type: integer
        example: 50
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
      description: List of associated series IDs
      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
        - 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
        - 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
    location-details:
      type: object
      properties:
        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'
        address:
          $ref: '#/components/schemas/address'
        phone:
          $ref: '#/components/schemas/phone'
        fax:
          description: Fax number for the location.
          type: string
          example: +1-925-921-9202
        email:
          $ref: '#/components/schemas/email'
        website:
          description: Website of the location.
          type: string
          example: www.bowmanfurniture.com
        tax_settings_id:
          $ref: '#/components/schemas/tax_settings_id'
        tax_reg_no:
          description: Tax registration number of the location.
          type: string
          example: 29AAAAA0000A1Z5
        is_primary_location:
          $ref: '#/components/schemas/is_primary'
        is_location_active:
          description: Whether the location is currently active.
          type: boolean
          example: true
        autonumbergenerationgroup_id:
          $ref: '#/components/schemas/autonumbergenerationgroup_id'
        autonumbergenerationgroup_name:
          description: Name of the auto number generation group associated with the location.
          type: string
          example: Default Series
        associated_series_ids:
          $ref: '#/components/schemas/associated_series_ids'
        customer_id:
          description: Unique identifier of the customer associated with the location.
          type: string
          example: '460000000038090'
        customer_name:
          description: Name of the customer associated with the location.
          type: string
          example: Bowman Furniture
        vendor_id:
          description: Unique identifier of the vendor associated with the location.
          type: string
          example: '460000000038092'
        vendor_name:
          description: Name of the vendor associated with the location.
          type: string
          example: Bowman Furniture
        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'
        location_identification_number:
          description: Unique identification number assigned to the location.
          type: string
          example: BR-001
        location_identification_label:
          description: Label used to identify the location.
          type: string
          example: BR
    get-a-location-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        location:
          $ref: '#/components/schemas/location-details'
    location-user:
      type: object
      properties:
        user_id:
          $ref: '#/components/schemas/user_id'
        name:
          description: Name of the user.
          type: string
          example: John Doe
        email:
          description: Email address of the user.
          type: string
          example: john.doe@bowmanfurniture.com
        mobile:
          description: Mobile number of the user.
          type: string
          example: +1-925-921-9201
        user_role:
          description: Role assigned to the user.
          type: string
          example: admin
        status:
          description: 'Status of the user. Allowed Values: <code>active</code>, <code>inactive</code>, <code>invited</code>.'
          type: string
          example: active
        photo_url:
          description: URL of the user's photo.
          type: string
          example: https://contacts.zoho.com/file?ID=12345
    page-context:
      type: object
      properties:
        page:
          description: Current page number.
          type: integer
          example: 1
        per_page:
          description: Number of records returned per page.
          type: integer
          example: 50
        has_more_page:
          description: Whether more pages of results are available.
          type: boolean
          example: false
        report_name:
          description: Name of the report.
          type: string
          example: Users
        sort_column:
          description: Column used to sort the results.
          type: string
          example: name
        sort_order:
          description: 'Order in which the results are sorted. Allowed Values: <code>A</code> (ascending), <code>D</code> (descending).'
          type: string
          example: A
    list-users-of-a-location-response:
      type: object
      properties:
        code:
          type: integer
          example: 0
          readOnly: true
        message:
          type: string
          example: success
          readOnly: true
        users:
          type: array
          items:
            $ref: '#/components/schemas/location-user'
        page_context:
          $ref: '#/components/schemas/page-context'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoInventory.settings.CREATE: Create Settings
            ZohoInventory.settings.UPDATE: Update Settings
            ZohoInventory.settings.READ: Read Settings
            ZohoInventory.settings.DELETE: Delete Settings