Elastic Path Locations API

openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26 19:10:23+00:00
  title: Addresses Introduction Account Addresses Locations API
  description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.


    You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- BearerToken: []
tags:
- name: Locations
paths:
  /inventories/locations:
    get:
      parameters:
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/Filter'
      - description: Only supported value is `location`. When specified, the results are sorted in ascending order based on the value of the field. For `location`, this means ascending distance from the supplied geolocation. For more information, see [Sorting](/guides/Getting-Started/sorting). For location sorting, `Ep-Geolocation` header must be provided as well.
        name: sort
        in: query
        schema:
          type: string
          enum:
          - location
      - $ref: '#/components/parameters/EpGeolocation'
      summary: List Locations
      description: Lists all Inventory Locations
      tags:
      - Locations
      operationId: ListLocations
      responses:
        '200':
          description: Success. A list of locations is returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'
                  links:
                    $ref: '#/components/schemas/Links'
              example:
                data:
                - id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                  type: inventory_location
                  attributes:
                    name: Milton Keynes Warehouse
                    external_ref: mk-stock-warehouse-walnut-tree
                    slug: milton-keynes-warehouse
                    description: Southern dispatch location for all inventory
                    address:
                    - Troughton Supplies
                    - 38 Pipernel Grove
                    - Walnut Tree
                    - MK7 4UL
                    geolocation:
                      lat: -90
                      lon: 180
        '400':
          $ref: '#/components/responses/ValidationError'
    post:
      summary: Create a Location
      description: Creates an Inventory Location
      tags:
      - Locations
      operationId: CreateLocation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/LocationRequest'
      responses:
        '201':
          description: Success. The location was created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Location'
              example:
                data:
                  id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                  type: inventory_location
                  attributes:
                    name: Milton Keynes Warehouse
                    external_ref: mk-stock-warehouse-walnut-tree
                    slug: milton-keynes-warehouse
                    description: Southern dispatch location for all inventory
                    address:
                    - Troughton Supplies
                    - 38 Pipernel Grove
                    - Walnut Tree
                    - MK7 4UL
                    geolocation:
                      lat: -90
                      lon: 180
        '400':
          $ref: '#/components/responses/ValidationError'
  /inventories/locations/{location_uuid}:
    parameters:
    - name: location_uuid
      in: path
      description: The unique identifier of the location.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    get:
      summary: Get a Location
      description: Get an Inventory Location
      tags:
      - Locations
      operationId: GetLocation
      responses:
        '200':
          description: Success. The location is returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Location'
              example:
                data:
                  id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                  type: inventory_location
                  attributes:
                    name: Milton Keynes Warehouse
                    external_ref: mk-stock-warehouse-walnut-tree
                    slug: milton-keynes-warehouse
                    description: Southern dispatch location for all inventory
                    address:
                    - Troughton Supplies
                    - 38 Pipernel Grove
                    - Walnut Tree
                    - MK7 4UL
                    geolocation:
                      lat: -90
                      lon: 180
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      summary: Update a Location
      description: Updates an Inventory Location
      tags:
      - Locations
      operationId: UpdateLocation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/LocationUpdateRequest'
      responses:
        '200':
          description: Success. The location was updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Location'
              example:
                data:
                  id: ebc7652d-bb7d-4359-9a83-78f2998208d9
                  type: inventory_location
                  attributes:
                    name: Milton Keynes Warehouse
                    external_ref: mk-stock-warehouse-walnut-tree
                    slug: milton-keynes-warehouse
                    description: Southern dispatch location for all inventory
                    address:
                    - Troughton Supplies
                    - 38 Pipernel Grove
                    - Walnut Tree
                    - MK7 4UL
                    geolocation:
                      lat: -90
                      lon: 180
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    delete:
      summary: Delete a Location
      description: Delete an Inventory Location
      tags:
      - Locations
      operationId: DeleteLocation
      responses:
        '204':
          description: Success. The location is deleted
components:
  parameters:
    PageOffset:
      name: page[offset]
      description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.
      in: query
      required: false
      schema:
        type: integer
        format: int
        minimum: 0
        maximum: 10000
        example: 10
    Filter:
      name: filter
      in: query
      required: false
      schema:
        type: string
        format: string
        description: 'Some Inventories API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.

          '
        example: eq(location,new-york)
    PageLimit:
      description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the the [**page length**](https://elasticpath.dev/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.
      name: page[limit]
      in: query
      required: false
      schema:
        type: integer
        format: int
        minimum: 0
        example: 100
    EpGeolocation:
      description: Latitude, Longitude representing current location
      name: Ep-Geolocation
      in: header
      schema:
        type: string
        pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?$
      example: 49.2847027,-123.1109329
  responses:
    NotFoundError:
      description: Not found. The requested entity does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            not-found:
              value:
                errors:
                - title: Not Found
                  status: '404'
                  detail: No location found
    ValidationError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing-name:
              value:
                errors:
                - title: Validation Error
                  status: '400'
                  detail: Your request was invalid
  schemas:
    LocationAttributes:
      required:
      - name
      - slug
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 1024
          example: Milton Keynes Warehouse
        external_ref:
          type: string
          minLength: 3
          maxLength: 1024
          example: mk-stock-warehouse-walnut-tree
        slug:
          type: string
          minLength: 1
          maxLength: 128
          example: milton-keynes-warehouse
        description:
          type: string
          minLength: 3
          maxLength: 1024
          example: Southern dispatch location for all inventory
        address:
          type: array
          minItems: 1
          maxItems: 8
          items:
            type: string
            maxLength: 1024
        geolocation:
          $ref: '#/components/schemas/GeolocationDetails'
    Timestamps:
      required:
      - created_at
      properties:
        updated_at:
          description: The date and time a resource was updated.
          type: string
          example: '2017-01-10T11:41:19.244842Z'
        created_at:
          description: The date and time a resource was created.
          type: string
          example: '2017-01-10T11:41:19.244842Z'
    Link:
      anyOf:
      - $ref: '#/components/schemas/LinkURI'
      - $ref: '#/components/schemas/LinkObject'
    LocationRequest:
      type: object
      required:
      - attributes
      properties:
        type:
          $ref: '#/components/schemas/InventoryLocationType'
        attributes:
          $ref: '#/components/schemas/LocationAttributes'
    Error:
      type: object
      required:
      - status
      - title
      properties:
        status:
          type: string
          description: The HTTP response code of the error.
          example: 500
        title:
          type: string
          description: A brief summary of the error.
          example: Internal server error
        detail:
          type: string
          description: Optional additional detail about the error.
          example: An internal error has occurred.
        meta:
          type: object
          description: Additional supporting meta data for the error.
          example:
            missing_ids:
            - e7d50bd5-1833-43c0-9848-f9d325b08be8
    Meta:
      type: object
      required:
      - timestamps
      properties:
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    ErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    LocationUpdateRequest:
      type: object
      required:
      - id
      - type
      - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/InventoryLocationType'
        attributes:
          $ref: '#/components/schemas/LocationUpdateAttributes'
    Links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Link'
    LinkObject:
      type: object
      properties:
        href:
          type: string
          format: uri
          example: http://example.com/articles/1/comments
        title:
          type: string
          example: Comments
        describedby:
          type: string
          format: uri
          example: http://example.com/schemas/article-comments
    Location:
      type: object
      required:
      - id
      - type
      - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/InventoryLocationType'
        attributes:
          $ref: '#/components/schemas/LocationAttributes'
        meta:
          $ref: '#/components/schemas/Meta'
    LocationUpdateAttributes:
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 1024
          example: Milton Keynes Warehouse
        external_ref:
          type: string
          minLength: 3
          maxLength: 1024
          example: mk-stock-warehouse-walnut-tree
          nullable: true
        slug:
          type: string
          minLength: 1
          maxLength: 128
          example: milton-keynes-warehouse
        description:
          type: string
          minLength: 3
          maxLength: 1024
          example: Southern dispatch location for all inventory
          nullable: true
        address:
          type: array
          minItems: 1
          maxItems: 8
          nullable: true
          items:
            type: string
            maxLength: 1024
            nullable: true
        geolocation:
          $ref: '#/components/schemas/GeolocationDetails'
    UUID:
      type: string
      description: The unique identifier.
      x-go-type: uuid.UUID
      x-go-type-import:
        name: uuid
        path: github.com/google/uuid
      example: 00000000-0000-0000-0000-000000000000
    LinkURI:
      type: string
      format: uri
      example: http://example.com/articles/1/comments
      nullable: true
    InventoryLocationType:
      type: string
      enum:
      - inventory_location
      example: inventory_location
    GeolocationDetails:
      type: object
      nullable: true
      description: The longitude and latitude of a location.
      required:
      - lat
      - lon
      properties:
        lat:
          type: number
          format: double
          nullable: false
          example: 51.477928
        lon:
          type: number
          format: double
          nullable: false
          example: -0.001545
      example:
        lat: 51.477928
        lon: -0.001545
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer