Zoho Inventory locations API

openapi: 3.0.0
info:
  title: batches locations API
  description: Batches help you track inventory items by batch numbers, manufacturing dates, and expiration dates.
  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
      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
  /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:
    country:
      description: Country Name of the location.
      type: string
      example: U.S.A
    status:
      description: 'Status of the locations. Allowed Values: <code>active</code>, <code>inactive</code>'
      example: active
    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
    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'
    phone:
      description: Mobile number for location
      type: string
      example: +1-925-921-9201
    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'
    location_name:
      description: Name of the location
      type: string
      example: Head Office
    attention:
      description: Attention of the location.
      type: string
    street_address2:
      description: Street Name of the location.
      type: string
      example: McMillan Avenue
    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
    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
    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
    user_ids:
      description: Comma separated user ids.
      type: string
      example: 460000000036868,460000000036869
    associated_series_ids:
      type: array
      description: List of associated series IDs
      items:
        type: string
      example:
      - '982000000870911'
      - '982000000870915'
    city:
      description: City Name of the location.
      type: string
      example: New York City
    email:
      description: Email id for the location
      type: string
      example: willsmith@bowmanfurniture.com
    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
    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
    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'
    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'
    is_primary:
      description: Whether it is primary location or not
      type: boolean
      example: true
    parent_location_id:
      description: Parent Location ID
      type: string
      example: '460000000041010'
    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'
    autonumbergenerationgroup_id:
      description: Autonumber generation group ID
      type: string
      example: '982000000870911'
    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'
    location_id:
      description: Location ID
      type: string
      example: '460000000038080'
    type:
      description: Type of the location
      type: string
      example: general / line_item_only
    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'
    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'
    state:
      description: State Name of the location.
      type: string
      example: New York
    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'
    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
    state_code:
      description: State code of the location.
      type: string
      example: NY
    tax_settings_id:
      description: Tax Settings ID
      type: string
      example: '460000000038080'
      x-node_available_in:
      - in
      x-node_unavailable_in: []
    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
    user_id:
      description: User ID
      type: string
      example: '460000000036868'
    street_address1:
      description: Street Name of the location.
      type: string
      example: No:234,90 Church Street
  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.items.CREATE: Create Items
            ZohoInventory.items.READ: Read Items
            ZohoInventory.items.UPDATE: Update Items
            ZohoInventory.items.DELETE: Delete Items