Update a location

Edits a location. Scope: locations:write.

What’s writable - and what owns the rest

You can change	Owner of the rest
name	-
address / coordinates (interplay below)	-
geo_message, geo_message_enabled	-
enabled_card_ids (SET - toggle cards on/off)	-
POS mapping	Dashboard Integrations flow - never via API
Team assignment	PATCH /v1/team_members/{id} (location_ids)
Lifecycle (is_active) & billing	Dashboard - each location is a billing unit

Address ↔ coordinates

Mirrors the dashboard (type address → geocode → drag pin to fine-tune):

• address alone → server geocodes → coordinates + country update. Ungeocodable → 422 address_not_geocodable.
• coordinates alone → the pin moves, the displayed address stays - the “drag to fine-tune” gesture as an API call.
• Both → stored exactly as sent, no geocode (you already resolved them - this is what the dashboard submits).

Card toggles

enabled_card_ids is SET semantics: send the complete list you want active. Enabling a card pushes this location’s geofence onto that card’s wallet passes; disabling removes it and the card stops appearing in cards[] (its signup URL for this location stops accepting signups). Unknown card → 422 card_not_found. A location must keep at least one card enabled (422 location_needs_card; delete the location instead). A card must stay enabled at at least one location: disabling it at its last one returns 422 card_needs_location (pause the card to stop offering it; a paused or archived card with members also keeps one location so they can still redeem).

PATCH /v1/locations/{id}

cURL

New push message

curl --request PATCH \
  --url https://api.vexioncards.one/v1/locations/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "geo_message": "Fresh batch out of the oven - come say hi! 🥐",
  "geo_message_enabled": true
}
'

200

Updated

{
  "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": "Fresh batch out of the oven - come say hi! 🥐",
  "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": 1751600000
}

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.

Headers

Idempotency-Key · string

Recommended on PATCH and DELETE for safe retries.

Path Parameters

id · string · required

Location identifier (loc_ prefix).

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

Body

application/json

Partial update - only supplied fields change.

Address ↔ coordinates interplay (mirrors the dashboard: type an address → it geocodes → drag the pin to fine-tune):

• address alone → the server geocodes it and updates coordinates + country. Ungeocodable → 422 address_not_geocodable.
• coordinates alone → moves the pin only; address stays as displayed (the "drag to fine-tune" gesture).
• Both → stored exactly as sent, no geocoding (you already resolved them).

Everything else on the location (POS mapping, team assignment, lifecycle, billing) has its own owner and is not writable here.

name · string

New display name.

Required string length: 1 - 60

address · string

New street address. Sent without coordinates, the server geocodes it.

Minimum string length: 1

coordinates · object

New pin position (both values required together). Sent without address, only the pin moves.

Show child attributes

geo_message · string | null

New geo push text (max 500 chars), or null to clear.

Maximum string length: 500

geo_message_enabled · boolean

Toggle the geo notification. Text is preserved when toggling off.

enabled_card_ids · string[]

SET semantics - the full list of cards active at this location after the update. A card id not in your organization → 422 card_not_found. Enabling pushes this location's geofence onto the card's passes; disabling removes it.

Maximum array length: 100

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

Response

200

application/json

Updated location (full object echoed).

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