Locations

Manage physical store locations

Locations represent the physical addresses of a store. Each store can have multiple locations (e.g. branches, pop-ups).

When you create or update a location with an address, the address is automatically geocoded to latitude/longitude coordinates. These coordinates are used for Apple Wallet relevance - customers receive lock-screen notifications when they are near one of your locations.

All location endpoints are scoped to a store via the :account_id URL parameter. You must have access to the parent store.

index

GET /api/v1/accounts/:account_id/locations

List all locations

Returns every physical location belonging to the specified store.

Parameters

Name	Type	Required	Description
`account_id`	Must be a Integer	Required	Parent store ID

Error Codes

Code	Description
`401`	Unauthorized – invalid or missing API token
`404`	Store not found or not accessible

Returns

Code: 200

An array of location objects

Name	Type	Required	Description
`id`	Must be a Integer	Required	Unique location ID
`account_id`	Must be a Integer	Required	Parent store ID
`name`	Must be a String	Required	Location name (e.g. ‘Downtown Branch’)
`address`	Must be a String	Required	Full street address
`latitude`	Must be a Float	Required	Geocoded latitude (auto-derived from address) (nil allowed)
`longitude`	Must be a Float	Required	Geocoded longitude (auto-derived from address) (nil allowed)
`created_at`	Must be a String	Required	ISO 8601 creation timestamp
`updated_at`	Must be a String	Required	ISO 8601 last-update timestamp

show

GET /api/v1/accounts/:account_id/locations/:id

Show a location

Returns a single location by ID.

Parameters

Name	Type	Required	Description
`account_id`	Must be a Integer	Required	Parent store ID
`id`	Must be a Integer	Required	Location ID

Error Codes

Code	Description
`401`	Unauthorized – invalid or missing API token
`404`	Location not found

Returns

Code: 200

A location object

Name	Type	Required	Description
`id`	Must be a Integer	Required	Unique location ID
`account_id`	Must be a Integer	Required	Parent store ID
`name`	Must be a String	Required	Location name (e.g. ‘Downtown Branch’)
`address`	Must be a String	Required	Full street address
`latitude`	Must be a Float	Required	Geocoded latitude (auto-derived from address) (nil allowed)
`longitude`	Must be a Float	Required	Geocoded longitude (auto-derived from address) (nil allowed)
`created_at`	Must be a String	Required	ISO 8601 creation timestamp
`updated_at`	Must be a String	Required	ISO 8601 last-update timestamp

create

POST /api/v1/accounts/:account_id/locations

Create a location

Creates a new physical location for the store. The provided address is automatically geocoded to latitude and longitude coordinates in the background.

Parameters

Name	Type	Required	Description
`account_id`	Must be a Integer	Required	Parent store ID
`location`	Must be a Hash	Required	Location attributes
`location[name]`	Must be a String	Required	Location name (e.g. ‘High Street Branch’)
`location[address]`	Must be a String	Required	Full street address – automatically geocoded to lat/lng

Error Codes

Code	Description
`401`	Unauthorized – invalid or missing API token
`404`	Store not found or not accessible
`422`	Validation failed – check the `errors` object for details

Returns

Code: 201

The newly created location object

Name	Type	Required	Description
`id`	Must be a Integer	Required	Unique location ID
`account_id`	Must be a Integer	Required	Parent store ID
`name`	Must be a String	Required	Location name (e.g. ‘Downtown Branch’)
`address`	Must be a String	Required	Full street address
`latitude`	Must be a Float	Required	Geocoded latitude (auto-derived from address) (nil allowed)
`longitude`	Must be a Float	Required	Geocoded longitude (auto-derived from address) (nil allowed)
`created_at`	Must be a String	Required	ISO 8601 creation timestamp
`updated_at`	Must be a String	Required	ISO 8601 last-update timestamp

update

PATCH /api/v1/accounts/:account_id/locations/:id

Update a location

Updates an existing location. If the address is changed, it will be re-geocoded automatically.

Parameters

Name	Type	Required	Description
`account_id`	Must be a Integer	Required	Parent store ID
`id`	Must be a Integer	Required	Location ID
`location`	Must be a Hash	Required	Location attributes
`location[name]`	Must be a String	Optional	Location name
`location[address]`	Must be a String	Optional	Full street address – automatically geocoded to lat/lng

Error Codes

Code	Description
`401`	Unauthorized – invalid or missing API token
`404`	Location not found
`422`	Validation failed – check the `errors` object for details

Returns

Code: 200

The updated location object

Name	Type	Required	Description
`id`	Must be a Integer	Required	Unique location ID
`account_id`	Must be a Integer	Required	Parent store ID
`name`	Must be a String	Required	Location name (e.g. ‘Downtown Branch’)
`address`	Must be a String	Required	Full street address
`latitude`	Must be a Float	Required	Geocoded latitude (auto-derived from address) (nil allowed)
`longitude`	Must be a Float	Required	Geocoded longitude (auto-derived from address) (nil allowed)
`created_at`	Must be a String	Required	ISO 8601 creation timestamp
`updated_at`	Must be a String	Required	ISO 8601 last-update timestamp

destroy

DELETE /api/v1/accounts/:account_id/locations/:id

Delete a location

Permanently deletes a location. This action cannot be undone.

Parameters

Name	Type	Required	Description
`account_id`	Must be a Integer	Required	Parent store ID
`id`	Must be a Integer	Required	Location ID

Error Codes

Code	Description
`401`	Unauthorized – invalid or missing API token
`404`	Location not found

Returns

Code: 204

No content – location successfully deleted