get_locations

List locations for a tenant via middleware, with merchant-access filtering. Use select (json-mask) for response trimming.

Locations are the physical or logical fulfillment points — warehouses, stores, dark stores, dropship endpoints. The agent needs them when creating a shipment (pickup location), routing decisions, or for reports sliced by location.

Parameters

Name	Type	Required	Description
tenantId	string	Yes	The tenant to list.
select	string	No	json-mask — useful for trimming the response.
merchant	string | string[]	No	Filter by one or more merchants.
country	string | string[]	No	Filter by location country.
status / statuses	string | string[]	No	Filter by status.
location_id / location_name / location_code	string | string[]	No	Filter by identifier or name.
country_access / location_access	string | string[]	No	Standard scope filters.
search_string	string	No	Free-text search.
page, page_size, sort_by, sort_direction	—	No	Pagination + sort.
creation_date_from / creation_date_to	string	No	Filter by creation date.
cache	string	No	Cache-control flag for the underlying query.

Returns

An array of location records — id, name, code, country, merchant scope, status.

Example agent prompts

"List our locations."

get_locations(
  tenantId="…",
  select="location_id,location_name,country,status"
)

"Find the warehouse codes for our UAE locations."

get_locations(
  tenantId="…",
  country="AE",
  select="location_code,location_name"
)

Related tools

• create_shipment — accepts pickup location ids.
• get_shipment_list — supports pickup_location / dropoff_location filters.
• Most reports support location_access for scoping.

Notes

• Lookup is cheap; cache for the session.
• Use select aggressively — location records can carry a lot of optional fields (operating hours, contact info) the agent rarely needs in chat.