> ## 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. # Create a terminal Location > Creates a Location in the authenticated key's test or live mode. Use the returned `loc_…` when creating a simulated Terminal or requesting physical hardware for this business location. `external_reference` is an optional identifier from your system. When present, it must be unique for the Merchant within this key mode. ## OpenAPI ````yaml /openapi/terminal-locations.yaml post /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: post: tags: - Terminal Locations summary: Create a terminal Location description: | Creates a Location in the authenticated key's test or live mode. Use the returned `loc_…` when creating a simulated Terminal or requesting physical hardware for this business location. `external_reference` is an optional identifier from your system. When present, it must be unique for the Merchant within this key mode. operationId: createTerminalLocation parameters: - $ref: '#/components/parameters/IonicAccount' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTerminalLocationRequest' example: display_name: Chicago flagship address: line1: 401 N Morgan St line2: Suite 200 city: Chicago state: IL postal_code: '60642' country: US timezone: America/Chicago merchant_category_code: '5812' external_reference: store_chicago_01 metadata: region: midwest responses: '201': description: The created Location. content: application/json: schema: $ref: '#/components/schemas/TerminalLocation' example: id: loc_R7pA3nB9qK2mX5 object: terminal.location merchant_id: mer_J4wF8tL6hC9vN2 livemode: false display_name: Chicago flagship address: line1: 401 N Morgan St line2: Suite 200 city: Chicago state: IL postal_code: '60642' country: US timezone: America/Chicago merchant_category_code: '5812' external_reference: store_chicago_01 metadata: region: midwest created_at: 1787625600 updated_at: 1787625600 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/WriteForbidden' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - locations:write 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}$ IdempotencyKey: name: Idempotency-Key in: header required: true description: Reuse only when retrying the same route and request body. schema: type: string minLength: 1 maxLength: 255 schemas: CreateTerminalLocationRequest: type: object additionalProperties: false required: - display_name - address - timezone - merchant_category_code properties: display_name: type: string minLength: 1 maxLength: 100 address: $ref: '#/components/schemas/TerminalAddress' timezone: type: string minLength: 1 description: Valid IANA timezone name, such as `America/Chicago`. merchant_category_code: type: string pattern: ^[0-9]{4}$ description: Four-digit Merchant Category Code. external_reference: type: string maxLength: 128 description: >- Optional identifier from your system, unique per Merchant and key mode. metadata: $ref: '#/components/schemas/Metadata' 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. 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 Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string 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' WriteForbidden: description: >- Inactive Merchant, invalid delegation, or missing `locations:write` permission. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- Idempotency conflict, duplicate external reference, or concurrent update. 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. ````