Locations

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

locations

{id}

Retrieve a location

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vexioncards.one/v1/locations/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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

string

required

Location identifier (loc_ prefix).

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

Response

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.

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

Retrieve a location

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vexioncards.one/v1/locations/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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

API Reference

MCP server

Customers

Cards

Transactions

Products

Notifications

Locations

Team members

Custom fields

Events

Webhook endpoints

API keys

Organization

Icons

API Reference

Retrieve a location

Authorizations

Path Parameters

Response