> ## Documentation Index > Fetch the complete documentation index at: https://vexioncards.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a location > Returns one location - the complete picture in a single call. Scope: `locations:read`. - **Identity & place** - `name`, `address`, `coordinates` (the pin), `country` - **Geo notification** - `geo_message` + `geo_message_enabled` (fires within ~100 m; radius fixed by the wallet platforms) - **Cards here** - `cards[]`: every enabled card with its stable per-location `signup_url` (render your own QR; signups stamp `Customer.signup_location_id`) - **Team** - `team_members[]` read-only summary (write path: `PATCH /v1/team_members/{id}`) - **POS** - `pos_connected` flag; the mapping itself is dashboard-managed and never editable via API There are no sub-endpoints to assemble - this object is the whole location. ## OpenAPI ````yaml /openapi.json get /v1/locations/{id} openapi: 3.1.0 info: title: VEXiON cards Public API description: >- ## Rate limiting Two independent layers, checked in this order: 1. **Per-IP throttle (pre-authentication).** Applied to every `/v1` request BEFORE the API key is checked, keyed on the caller's IP address: - **600 requests/minute** per IP - a flood ceiling, `429 rate_limit_error` / `rate_limited`. - **20 failed authentications per 15 minutes** per IP - a key-guessing ceiling. Only responses that are `401` (missing/invalid/revoked key) count against this ceiling; a `403` from a valid key that simply lacks a scope does not. `429 rate_limit_error` / `too_many_failed_attempts`. Both ceilings send `Retry-After` (seconds). 2. **Per-key, per-bucket limiter (post-authentication).** Documented per endpoint (see each operation's `429` response and the `rate_limit` field on the API Key resource) - e.g. 60/min default, 120/min for transactions, plus the notification-broadcast and lookup-filter buckets described on their own endpoints. ### Rate-limit response headers Every rate-limited response carries the legacy `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` family (the last is an **epoch timestamp**) AND the IETF standards-track headers, side by side: - `RateLimit-Policy: "";q=;w=` - the static policy for the bucket that was hit. - `RateLimit: "";r=;t=` - live state. **`t` is a DURATION (seconds remaining), not the epoch timestamp `X-RateLimit-Reset` carries - the two are never the same value.** version: 1.0.0 servers: - url: https://api.vexioncards.one description: Production - url: https://migration.api.vexioncards.one description: Sandbox security: - apiKey: [] tags: - name: Customers - name: Cards - name: Transactions - name: Notifications - name: Locations - name: Products - name: API keys - name: Organization - name: Webhook endpoints - name: Events - name: Custom fields - name: Team members - name: Icons paths: /v1/locations/{id}: get: tags: - Locations summary: Retrieve a location description: >- Returns one location - the complete picture in a single call. Scope: `locations:read`. - **Identity & place** - `name`, `address`, `coordinates` (the pin), `country` - **Geo notification** - `geo_message` + `geo_message_enabled` (fires within ~100 m; radius fixed by the wallet platforms) - **Cards here** - `cards[]`: every enabled card with its stable per-location `signup_url` (render your own QR; signups stamp `Customer.signup_location_id`) - **Team** - `team_members[]` read-only summary (write path: `PATCH /v1/team_members/{id}`) - **POS** - `pos_connected` flag; the mapping itself is dashboard-managed and never editable via API There are no sub-endpoints to assemble - this object is the whole location. operationId: getLocation parameters: - name: id in: path description: Location identifier (`loc_` prefix). required: true example: loc_01HW9R9Z4EF7N8MTX1RVLOCDEF schema: type: string pattern: ^loc_[A-Za-z0-9]+$ responses: '200': description: Location. content: application/json: schema: $ref: '#/components/schemas/Location' examples: POS-bridged store: summary: Everything populated value: id: loc_01HW9R4P2ZK7N8MTX1RVLOCS01 object: location name: Demo Coffee - City Center address: Hlavná 12, 811 01 Bratislava, Slovakia coordinates: latitude: 48.1486 longitude: 17.1077 country: SK geo_message: >- You're near Demo Coffee - your 10th coffee is on us today! ☕ geo_message_enabled: true enabled_card_ids: - crd_56gd3jpqoipsfjoa7cjabfqope - crd_2hh2fekk5zazfyyvian4uhepyq cards: - card_id: crd_56gd3jpqoipsfjoa7cjabfqope name: Coffee Stamp Card type: stamp signup_url: >- https://vexioncards.one/signup/?id=crd_56gd3jpqoipsfjoa7cjabfqope&loc=loc_01HW9R4P2ZK7N8MTX1RVLOCS01 - card_id: crd_2hh2fekk5zazfyyvian4uhepyq name: Coffee Points type: reward signup_url: >- https://vexioncards.one/signup/?id=crd_2hh2fekk5zazfyyvian4uhepyq&loc=loc_01HW9R4P2ZK7N8MTX1RVLOCS01 team_members: - team_member_id: tm_01HW9R6M4XQ2N8MTX1RVTM0001 name: Anna K. role: scanner - team_member_id: tm_01HW9R6M4XQ2N8MTX1RVTM0002 name: Peter V. role: manager pos_connected: true is_default: true is_active: true created_at: 1735689600 updated_at: 1751500000 No POS, geo off: summary: Second store, quieter setup value: id: loc_01HW9R4P2ZK7N8MTX1RVLOCS02 object: location name: Demo Coffee - Riverside address: Nábrežná 3, 811 02 Bratislava, Slovakia coordinates: latitude: 48.1411 longitude: 17.1093 country: SK geo_message: null geo_message_enabled: false enabled_card_ids: - crd_56gd3jpqoipsfjoa7cjabfqope cards: - card_id: crd_56gd3jpqoipsfjoa7cjabfqope name: Coffee Stamp Card type: stamp signup_url: >- https://vexioncards.one/signup/?id=crd_56gd3jpqoipsfjoa7cjabfqope&loc=loc_01HW9R4P2ZK7N8MTX1RVLOCS01 team_members: [] pos_connected: false is_default: false is_active: true created_at: 1735689600 updated_at: 1751500000 headers: {} '400': description: Malformed body or missing required field. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '403': description: API key lacks the required scope. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '404': description: Resource not found in your organization. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '429': description: Per-minute or per-day rate limit exceeded. Respect Retry-After. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} '500': description: Server error. Retry-safe on idempotent calls. content: application/json: schema: $ref: '#/components/schemas/Error' headers: {} deprecated: false components: schemas: Location: type: object description: >- A physical store - the unit of POS bridging, team assignment, geo notifications, and per-location card availability. Locations are **created and deleted in the dashboard only** (each is a billing unit); the API reads and edits them. required: - id - object - name - address - coordinates - geo_message_enabled - enabled_card_ids - cards - team_members - pos_connected - is_default - is_active - created_at properties: id: type: string pattern: ^loc_[A-Za-z0-9]+$ description: Location identifier, `loc_` prefix. example: loc_01HW9R4P2ZK7N8MTX1RVLOCS01 object: type: string const: location description: Always `"location"`. name: type: string minLength: 1 maxLength: 60 description: >- Display name shown in the dashboard, scanner, and transaction attribution. example: Demo Coffee - City Center address: type: - string - 'null' description: >- Human-readable street address, one line. Writable - see PATCH for the address ↔ coordinates interplay (sending a new address alone re-geocodes the pin server-side). example: Hlavná 12, 811 01 Bratislava, Slovakia coordinates: type: - object - 'null' description: >- The pin - drives the wallet-pass geofence and map display. Kept in sync with `address` by geocoding, or set directly to fine-tune (the API equivalent of dragging the map pin). required: - latitude - longitude properties: latitude: type: number minimum: -90 maximum: 90 description: WGS84 latitude. example: 48.1486 longitude: type: number minimum: -180 maximum: 180 description: WGS84 longitude. example: 17.1077 example: latitude: 48.1486 longitude: 17.1077 country: type: - string - 'null' description: >- ISO 3166-1 alpha-2, derived from the geocoded address. Null while no address is set. example: SK geo_message: type: - string - 'null' maxLength: 500 description: >- The push text shown on the customer's lock screen when they come near this location (wallet-pass geofencing; the trigger radius is fixed by Apple/Google at roughly 100 m - not configurable). Null = no message configured. Only fires while `geo_message_enabled` is true. example: You're near Demo Coffee - your 10th coffee is on us today! ☕ geo_message_enabled: type: boolean description: >- Master switch for the geo notification at this location. The message text is kept when you toggle off. example: true enabled_card_ids: type: array items: type: string pattern: ^crd_[A-Za-z0-9]+$ description: >- Which card templates are active at this location - the writable source of truth behind `cards[]`. PATCH with SET semantics to toggle cards on/off. Enabling a card also pushes this location's geofence onto that card's wallet passes (Apple Wallet caps geofences at 10 locations per pass). example: - crd_56gd3jpqoipsfjoa7cjabfqope - crd_2hh2fekk5zazfyyvian4uhepyq cards: type: array description: >- Read-only expansion of `enabled_card_ids` - **only the cards turned ON at this location**, each with its per-(card, location) `signup_url`. The URL is long-lived and never rotates: render your own QR from it for counter cards and window decals. Customers who sign up through it get this location stamped as `Customer.signup_location_id`. Distinct from the per-customer `claim_url` (wallet handoff). Deliberately NOT the full org catalog with on/off flags: embedding every card template in every location response would bloat list calls and go stale as templates are added. To build a toggle UI like the dashboard's, join two clean resources: `GET /v1/cards` (the full catalog) against this location's `enabled_card_ids` (the on/off state). To toggle, PATCH `enabled_card_ids` with the new SET. items: type: object required: - card_id - name - type - signup_url properties: card_id: type: string pattern: ^crd_[A-Za-z0-9]+$ description: The enabled card template. example: crd_56gd3jpqoipsfjoa7cjabfqope name: type: string description: Card display name (default language). example: Coffee Stamp Card type: type: string enum: - stamp - reward - discount - coupon - membership - gift_card - custom description: Card family. example: stamp signup_url: type: string format: uri description: Stable signup landing URL for this card at this location. example: >- https://vexioncards.one/signup/?id=crd_56gd3jpqoipsfjoa7cjabfqope&loc=loc_01HW9R4P2ZK7N8MTX1RVLOCS01 team_members: type: array description: >- Read-only summary of who is assigned here. The write path is `PATCH /v1/team_members/{id}` with `location_ids` - one relationship, one owner; this is the location-side read. items: type: object required: - team_member_id - role properties: team_member_id: type: string pattern: ^tm_[A-Za-z0-9]+$ description: The assigned team member. example: tm_01HW9R6M4XQ2N8MTX1RVTM0001 name: type: - string - 'null' description: Display name. example: Anna K. role: type: string enum: - manager - scanner description: >- Their role at this location. Admins never appear here - they have implicit access to all locations. example: scanner pos_connected: type: boolean description: >- True when this location has a live POS bridge - sales at the till flow in automatically as `source: "pos"` transactions. **Boolean by design:** the one integration decision this flag serves is "do I need to push transactions via the API, or does the till already report them?". The POS vendor, connection ids, and mapping details are internal (vendor privacy) and dashboard-owned - they are never surfaced or editable via API. example: true is_default: type: boolean description: >- The organization's default location (used when a write carries no explicit `location_id` and the org has exactly one candidate). example: true is_active: type: boolean description: >- Read-only lifecycle flag. Deactivating a location is a billing action - dashboard only. example: true created_at: type: integer description: Unix seconds. example: 1735689600 updated_at: type: integer description: Unix seconds of last change. example: 1751500000 Error: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - idempotency_error - api_error code: type: string message: type: string retry_after: type: integer description: >- Seconds to wait before retrying. Present on rate-limit (429) and idempotency-key-in-use (409) errors; mirrors the `Retry-After` HTTP header. Absent on error types that carry no retry guidance. example: 5 param: type: - string - 'null' request_id: type: string doc_url: type: string format: uri field_errors: type: array description: >- Per-field errors on a 422. At most 100 entries: a request with more errors gets the first 100. items: type: object properties: param: type: string code: type: string message: type: string expected_currency: type: string description: >- On `currency_mismatch`: the business currency the request must use. Absent on every other field error. description: >- The error payload: type (category), code (machine-readable), message (human-readable), retry_after (seconds, on rate-limit/idempotency-in-use errors only), param (offending field), request_id, doc_url, field_errors[]. description: >- Standard error envelope. Branch on `error.code`; include `error.request_id` in support requests. See the Errors guide. securitySchemes: apiKey: type: http scheme: bearer description: >- Your secret API key as a Bearer token: `Authorization: Bearer vxn_sk_...`. Keys are created and scoped in the dashboard - see [Authentication](/api-reference/introduction#authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.