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.

GET /v1/locations/{id}

Retrieve a location

cURL

curl --request GET \
  --url https://api.vexioncards.one/v1/locations/{id} \
  --header 'Authorization: Bearer <token>'

200

POS-bridged store

{
  "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
}

Authorizations

Authorization · string · header · required

Your secret API key as a Bearer token: Authorization: Bearer vxn_sk_.... Keys are created and scoped in the dashboard - see Authentication.

Path Parameters

id · string · required

Location identifier (loc_ prefix).

Pattern: ^loc_[A-Za-z0-9]+$

Response

200

application/json

Location.

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.

id · string · required

Location identifier, loc_ prefix.

Pattern: ^loc_[A-Za-z0-9]+$

Example:

"loc_01HW9R4P2ZK7N8MTX1RVLOCS01"

object · string · required

Always "location".

Allowed value: "location"

name · string · required

Display name shown in the dashboard, scanner, and transaction attribution.

Required string length: 1 - 60

Example:

"Demo Coffee - City Center"

address · string | null · required

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 · object | null · required

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).

Show child attributes

Example:

{ "latitude": 48.1486, "longitude": 17.1077 }

geo_message_enabled · boolean · required

Master switch for the geo notification at this location. The message text is kept when you toggle off.

Example:

true

enabled_card_ids · string[] · required

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).

Pattern: ^crd_[A-Za-z0-9]+$

Example:

[
  "crd_56gd3jpqoipsfjoa7cjabfqope",
  "crd_2hh2fekk5zazfyyvian4uhepyq"
]

cards · object[] · required

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.

Show child attributes

team_members · object[] · required

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.

Show child attributes

pos_connected · boolean · required

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 · boolean · required

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 · boolean · required

Read-only lifecycle flag. Deactivating a location is a billing action - dashboard only.

Example:

true

created_at · integer · required

Unix seconds.

Example:

1735689600

country · string | null

ISO 3166-1 alpha-2, derived from the geocoded address. Null while no address is set.

Example:

"SK"

geo_message · string | null

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.

Maximum string length: 500

Example:

"You're near Demo Coffee - your 10th coffee is on us today! ☕"

updated_at · integer

Unix seconds of last change.

Example:

1751500000