> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List terminal Locations

> Lists Locations belonging to the authenticated Merchant and key mode,
ordered for cursor pagination. Test keys never return live Locations,
and live keys never return test Locations.




## OpenAPI

````yaml /openapi/terminal-locations.yaml get /locations
openapi: 3.0.3
info:
  title: Ionic Terminal Locations API
  version: '2026-08-25'
  description: |
    Create and manage the Merchant locations where physical and simulated
    Terminals operate. A Location is an Ionic resource; it does not represent
    a hardware serial number or device credential.

    Test and live Locations are isolated automatically by the mode of the
    secret key. Create the Location with the same key mode that you will use
    to create or provision its Terminals. There is no delete operation; update
    the Location when its business profile changes.
servers:
  - url: '{baseUrl}/v1'
    variables:
      baseUrl:
        default: https://api.ionicfi.com
        description: API base URL for the selected environment.
security:
  - secretKey: []
tags:
  - name: Terminal Locations
    description: Manage Merchant-owned deployment locations for Terminals.
paths:
  /locations:
    get:
      tags:
        - Terminal Locations
      summary: List terminal Locations
      description: |
        Lists Locations belonging to the authenticated Merchant and key mode,
        ordered for cursor pagination. Test keys never return live Locations,
        and live keys never return test Locations.
      operationId: listTerminalLocations
      parameters:
        - $ref: '#/components/parameters/IonicAccount'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
      responses:
        '200':
          description: A page of Locations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminalLocationList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ReadForbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - secretKey:
            - locations:read
components:
  parameters:
    IonicAccount:
      name: Ionic-Account
      in: header
      required: false
      description: |
        Merchant ID when an authorized Platform acts for a connected Merchant.
        Omit when authenticating directly as that Merchant.
      schema:
        type: string
        pattern: ^mer_[0-9A-Za-z]{14}$
    Limit:
      name: limit
      in: query
      required: false
      description: Page size. Defaults to 20 and cannot exceed 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    StartingAfter:
      name: starting_after
      in: query
      required: false
      description: Return objects after this Location ID.
      schema:
        type: string
        pattern: ^loc_[0-9A-Za-z]{14}$
  schemas:
    TerminalLocationList:
      type: object
      additionalProperties: false
      required:
        - object
        - data
        - has_more
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/TerminalLocation'
        has_more:
          type: boolean
        next_cursor:
          type: string
          pattern: ^loc_[0-9A-Za-z]{14}$
          description: Present only when `has_more` is true.
    TerminalLocation:
      type: object
      additionalProperties: false
      required:
        - id
        - object
        - merchant_id
        - livemode
        - display_name
        - address
        - timezone
        - merchant_category_code
        - external_reference
        - metadata
        - created_at
        - updated_at
      properties:
        id:
          type: string
          pattern: ^loc_[0-9A-Za-z]{14}$
        object:
          type: string
          enum:
            - terminal.location
        merchant_id:
          type: string
          pattern: ^mer_[0-9A-Za-z]{14}$
        livemode:
          type: boolean
          description: Derived from the secret key; it cannot be set in the request body.
        display_name:
          type: string
        address:
          $ref: '#/components/schemas/TerminalAddress'
        timezone:
          type: string
        merchant_category_code:
          type: string
          pattern: ^[0-9]{4}$
        external_reference:
          type: string
          description: Empty when no external reference is assigned.
        metadata:
          $ref: '#/components/schemas/Metadata'
        created_at:
          type: integer
          format: int64
          description: Unix epoch seconds.
        updated_at:
          type: integer
          format: int64
          description: Unix epoch seconds.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
    TerminalAddress:
      type: object
      additionalProperties: false
      required:
        - line1
        - city
        - state
        - postal_code
        - country
      properties:
        line1:
          type: string
          minLength: 1
        line2:
          type: string
        city:
          type: string
          minLength: 1
        state:
          type: string
          minLength: 1
        postal_code:
          type: string
          minLength: 1
        country:
          type: string
          pattern: ^[A-Za-z]{2}$
          description: >-
            ISO 3166-1 alpha-2 country code. Responses normalize it to
            uppercase.
    Metadata:
      type: object
      description: >-
        Up to 50 string keys; keys are at most 40 characters and values are at
        most 500 characters.
      maxProperties: 50
      additionalProperties:
        type: string
        maxLength: 500
  responses:
    BadRequest:
      description: Invalid JSON, fields, Location ID, or pagination cursor.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ReadForbidden:
      description: Invalid delegation or missing `locations:read` permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: Ionic secret key
      description: >-
        Merchant secret key, or an authorized Platform secret key with
        delegation.

````