Zoho Inventory Locations API

openapi: 3.2.0
info:
  title: Locations API
  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
    parameters:
    - $ref: '#/components/parameters/organization_id'
    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
  /locations:
    x-mcp-group:
    - Locations
    parameters:
    - $ref: '#/components/parameters/organization_id'
    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
  /locations/{location_id}:
    x-mcp-group:
    - Locations
    parameters:
    - name: location_id
      in: path
      required: true
      description: Unique identifier of the location.
      schema:
        type: string
      example: 130426000000664020
    - $ref: '#/components/parameters/organization_id'
    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
      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
  /locations/{location_id}/active:
    x-mcp-group:
    - Locations
    parameters:
    - name: location_id
      in: path
      required: true
      description: Unique identifier of the location.
      schema:
        type: string
      example: 130426000000664020
    - $ref: '#/components/parameters/organization_id'
    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
  /locations/{location_id}/inactive:
    x-mcp-group:
    - Locations
    parameters:
    - name: location_id
      in: path
      required: true
      description: Unique identifier of the location.
      schema:
        type: string
      example: 130426000000664020
    - $ref: '#/components/parameters/organization_id'
    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
  /locations/{location_id}/markasprimary:
    x-mcp-group:
    - Locations
    parameters:
    - name: location_id
      in: path
      required: true
      description: Unique identifier of the location.
      schema:
        type: string
      example: 130426000000664020
    - $ref: '#/components/parameters/organization_id'
    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
  /locations/{location_id}/users:
    x-mcp-group:
    - Locations
    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
    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
components:
  schemas:
    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'
    is_primary:
      description: Whether it is primary location or not
      type: boolean
      example: true
    street_address2:
      description: Street Name of the location.
      type: string
      example: McMillan Avenue
    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'
    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
    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
    attention:
      description: Attention of the location.
      type: string
    city:
      description: City Name of the location.
      type: string
      example: New York City
    country:
      description: Country Name of the location.
      type: string
      example: U.S.A
    user_id:
      description: User ID
      type: string
      example: '460000000036868'
    state_code:
      description: State code of the location.
      type: string
      example: NY
    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
    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'
    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'
    state:
      description: State Name of the location.
      type: string
      example: New York
    parent_location_id:
      description: Parent Location ID
      type: string
      example: '460000000041010'
    street_address1:
      description: Street Name of the location.
      type: string
      example: No:234,90 Church Street
    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'
    email:
      description: Email id for the location
      type: string
      example: willsmith@bowmanfurniture.com
    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
    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'
    status:
      description: 'Status of the locations. Allowed Values: <code>active</code>, <code>inactive</code>'
      example: active
    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'
    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
    tax_settings_id:
      description: Tax Settings ID
      type: string
      example: '460000000038080'
      x-node_available_in:
      - in
      x-node_unavailable_in: []
    location_id:
      description: Location ID
      type: string
      example: '460000000038080'
    user_ids:
      description: Comma separated user ids.
      type: string
      example: 460000000036868,460000000036869
    user_name:
      description: User Name
      type: string
      example: John Doe
    is_all_users_selected:
      description: Whether all users are selected or not
      type: boolean
      example: false
    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
    type:
      description: Type of the location
      type: string
      example: general / line_item_only
    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
    associated_series_ids:
      type: array
      description: List of associated series IDs
      items:
        type: string
      example:
      - '982000000870911'
      - '982000000870915'
    phone:
      description: Mobile number for location
      type: string
      example: +1-925-921-9201
    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'
    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
    location_name:
      description: Name of the location
      type: string
      example: Head Office
    autonumbergenerationgroup_id:
      description: Autonumber generation group ID
      type: string
      example: '982000000870911'
  parameters:
    organization_id:
      name: organization_id
      description: ID of the organization
      in: query
      required: true
      schema:
        type: string
      example: '10234695'
  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