Every Capillary org is built on a location structure: concepts group your channels or brands, zones divide your geography, stores are your physical outlets, and tills are the point-of-sale terminals inside each store. The Location APIs let you create and manage this structure in bulk — onboarding new stores, reorganizing zones, adding tills — and search across all location types to retrieve or verify what's configured in your org.
What you can do
- Create locations in bulk — add up to 100 concepts, zones, or stores per request, and up to 50 tills per request.
- Update locations in bulk — modify existing locations by code, ID, or external ID.
- Search and filter — retrieve locations by type, code, name, or external ID with pagination and sorting.
- Retrieve hierarchy — view each location's parent zone, parent concept, and child tills in a single response.
- Include custom fields — surface org-configured custom field values alongside standard location attributes.
Location types
Locations follow a four-level hierarchy. Higher-level entities must exist before child entities can be created.
| Type | Description | Belongs to |
|---|---|---|
| CONCEPT | Top-level grouping that represents a brand, channel, or business unit. | Another concept (optional — omit groupParentCode to create a root concept). |
| ZONE | Geographic or operational region. | Another zone (required via areaParentCode). |
| STORE | Physical retail location. | A zone (area parent) and a concept (group parent). Both are required. |
| TILL | Point-of-sale terminal inside a store. Inherits locale from its parent store automatically. | A store (required via storeParentCode). |
Locale settings
Concepts, zones, and stores each require a language (IETF BCP 47), currency (ISO 4217), and timezone (IANA). You can set these explicitly, or pass inheritLocale=true to inherit them from the parent entity. If the parent entity's locale is not configured, the request fails.
Tills inherit locale from their parent store automatically. Locale fields are not accepted in till requests.
API operations
Each write operation processes items independently — a failure on one item does not block the others. The HTTP status reflects the overall result: 201 if all items succeeded, 207 if some failed, or 400 if all failed.
| Operation | Method | Endpoint | Batch limit |
|---|---|---|---|
| Search locations | GET | /v2/locations | Up to 100 results per page |
| Create stores | POST | /v2/locations/stores | 100 stores per request |
| Create zones | POST | /v2/locations/zones | 100 zones per request |
| Create concepts | POST | /v2/locations/concepts | 100 concepts per request |
| Create tills | POST | /v2/locations/tills | 50 tills per request |
| Update stores | PUT | /v2/locations/stores | 100 stores per request |
| Update zones | PUT | /v2/locations/zones | 100 zones per request |
| Update concepts | PUT | /v2/locations/concepts | 100 concepts per request |
| Update tills | PUT | /v2/locations/tills | 50 tills per request |
QuickStart: set up your location hierarchy
Create entities in order — a child entity cannot be created before its parent exists.
Step 1 — Create concepts
Call Add concepts in bulk to create your top-level channel or brand groupings. Omit groupParentCode to create a root-level concept.
Step 2 — Create zones
Call Add zones in bulk to create geographic regions. Set areaParentCode to link each zone to its parent zone.
Step 3 — Create stores
Call Add stores in bulk to create physical retail locations. Set areaParentCode to the parent zone and groupParentCode to the parent concept.
Step 4 — Create tills
Call Add tills in bulk to create point-of-sale terminals inside stores. Set storeParentCode to the parent store. Locale is inherited automatically from the parent store.
Step 5 — Search and verify
Call Get locations to confirm your hierarchy. Use includeChildren=true with a single entityCodes value to retrieve a location's children, or filter by type to list all entities of a specific kind.