Locations - Chataigne Docs

A location represents a single restaurant venue: its currency, country, timezone, language, and physical address. Locations belong to an organization and carry their own settings (opening hours, delivery, acceptance, AI instructions) and special closings. On the public API you can list, retrieve, and update locations. Locations are created through the Admin API or the organization endpoint — see Creating locations.

The location object

string

Unique identifier, prefixed with loc_.

object

string

Always location.

organization_id

string | null

The organization this location belongs to (org_…), or null if it is standalone.

name

string

Display name of the location.

currency

string

ISO 4217 currency code. One of CHF, EUR, GBP, BRL, USD, MXN.

country

string

ISO 3166-1 alpha-2 country code. One of FR, CH, GB, BR, LU, MX, US.

timezone

string

IANA timezone identifier, e.g. Europe/Zurich.

default_language

string

Default language used for customer-facing messaging at this location.

address

object | null

Physical address of the location, or null if not set.

Show address properties

line1

string

Street address, first line.

line2

string

Street address, second line (apartment, suite, floor).

postal_code

string

Postal or ZIP code.

city

string

City.

country

string

ISO 3166-1 alpha-2 country code.

latitude

number

Geographic latitude in decimal degrees.

longitude

number

Geographic longitude in decimal degrees.

created_at

string

Creation timestamp, ISO 8601 in UTC.

updated_at

string

Last update timestamp, ISO 8601 in UTC.

The location object

{
  "id": "loc_8sKq2bXt9mZ1",
  "object": "location",
  "organization_id": "org_3aN7vP0kLeQ4",
  "name": "Châtaigne Genève — Plainpalais",
  "currency": "CHF",
  "country": "CH",
  "timezone": "Europe/Zurich",
  "default_language": "fr",
  "address": {
    "line1": "12 Rue de Carouge",
    "line2": "Rez-de-chaussée",
    "postal_code": "1205",
    "city": "Genève",
    "country": "CH",
    "latitude": 46.1959,
    "longitude": 6.1402
  },
  "created_at": "2025-01-14T09:32:11Z",
  "updated_at": "2025-03-02T17:48:55Z"
}

List locations

Returns a paginated list of locations accessible to your API key, ordered by created_at.

GET /v1/locations

limit

integer

default:"10"

Number of objects to return, between 1 and 100.

starting_after

string

Cursor for forward pagination — a location id. Mutually exclusive with ending_before.

ending_before

string

Cursor for backward pagination — a location id. Mutually exclusive with starting_after.

created_after

string

Return locations created at or after this ISO 8601 timestamp.

created_before

string

Return locations created at or before this ISO 8601 timestamp.

updated_after

string

Return locations updated at or after this ISO 8601 timestamp.

updated_before

string

Return locations updated at or before this ISO 8601 timestamp.

curl https://server.chataigne.ai/v1/locations?limit=2 \
  -H "x-api-key: ch_org_live_8f3kP2nQ..."

Response

{
  "object": "list",
  "data": [
    {
      "id": "loc_8sKq2bXt9mZ1",
      "object": "location",
      "organization_id": "org_3aN7vP0kLeQ4",
      "name": "Châtaigne Genève — Plainpalais",
      "currency": "CHF",
      "country": "CH",
      "timezone": "Europe/Zurich",
      "default_language": "fr",
      "address": {
        "line1": "12 Rue de Carouge",
        "line2": "Rez-de-chaussée",
        "postal_code": "1205",
        "city": "Genève",
        "country": "CH",
        "latitude": 46.1959,
        "longitude": 6.1402
      },
      "created_at": "2025-01-14T09:32:11Z",
      "updated_at": "2025-03-02T17:48:55Z"
    },
    {
      "id": "loc_5dWm0fYr4tH7",
      "object": "location",
      "organization_id": "org_3aN7vP0kLeQ4",
      "name": "Châtaigne Lausanne — Flon",
      "currency": "CHF",
      "country": "CH",
      "timezone": "Europe/Zurich",
      "default_language": "fr",
      "address": null,
      "created_at": "2025-02-20T11:05:43Z",
      "updated_at": "2025-02-20T11:05:43Z"
    }
  ],
  "has_more": true,
  "url": "/v1/locations"
}

To list only the locations within a specific organization, use GET /v1/organizations/{organization_id}/locations. See Organizations.

Retrieve a location

Retrieves a single location by its id.

GET /v1/locations/{location_id}

location_id

string

required

The identifier of the location, e.g. loc_8sKq2bXt9mZ1.

curl https://server.chataigne.ai/v1/locations/loc_8sKq2bXt9mZ1 \
  -H "x-api-key: ch_org_live_8f3kP2nQ..."

Response

{
  "id": "loc_8sKq2bXt9mZ1",
  "object": "location",
  "organization_id": "org_3aN7vP0kLeQ4",
  "name": "Châtaigne Genève — Plainpalais",
  "currency": "CHF",
  "country": "CH",
  "timezone": "Europe/Zurich",
  "default_language": "fr",
  "address": {
    "line1": "12 Rue de Carouge",
    "line2": "Rez-de-chaussée",
    "postal_code": "1205",
    "city": "Genève",
    "country": "CH",
    "latitude": 46.1959,
    "longitude": 6.1402
  },
  "created_at": "2025-01-14T09:32:11Z",
  "updated_at": "2025-03-02T17:48:55Z"
}

A loc_… that does not exist or is not accessible to your key returns a 404 not_found_error. See Errors.

Update a location

Updates the specified location. Only the fields you pass are changed; omitted fields are left untouched.

PATCH /v1/locations/{location_id}

location_id

string

required

The identifier of the location to update.

name

string

Display name of the location.

currency

string

ISO 4217 currency code. One of CHF, EUR, GBP, BRL, USD, MXN.

country

string

ISO 3166-1 alpha-2 country code. One of FR, CH, GB, BR, LU, MX, US.

timezone

string

IANA timezone identifier, e.g. Europe/Zurich.

default_language

string

Default language for customer-facing messaging.

address

object

Address fields to merge. See Partial address merge below.

Show address properties

line1

string

line2

string

postal_code

string

city

string

country

string

latitude

number

longitude

number

Partial address merge

When you include an address object in a PATCH, the keys you provide are merged into the existing address — fields you omit keep their current values. This lets you correct a single line without re-sending the full address.

Merge applies only when the location already has an address. The address as a whole remains optional on existing locations, but address (with latitude and longitude) is required at creation time — see Creating locations.

curl -X PATCH https://server.chataigne.ai/v1/locations/loc_8sKq2bXt9mZ1 \
  -H "x-api-key: ch_org_live_8f3kP2nQ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Châtaigne Genève — Plainpalais (Carouge)",
    "address": {
      "line2": "1er étage",
      "postal_code": "1227"
    }
  }'

Response

{
  "id": "loc_8sKq2bXt9mZ1",
  "object": "location",
  "organization_id": "org_3aN7vP0kLeQ4",
  "name": "Châtaigne Genève — Plainpalais (Carouge)",
  "currency": "CHF",
  "country": "CH",
  "timezone": "Europe/Zurich",
  "default_language": "fr",
  "address": {
    "line1": "12 Rue de Carouge",
    "line2": "1er étage",
    "postal_code": "1227",
    "city": "Genève",
    "country": "CH",
    "latitude": 46.1959,
    "longitude": 6.1402
  },
  "created_at": "2025-01-14T09:32:11Z",
  "updated_at": "2025-03-02T18:14:09Z"
}

Note in the response that only name, address.line2, and address.postal_code changed — line1, city, country, and the coordinates were preserved from the merge.

Editing address does not automatically re-geocode the location. If you move the venue or correct the street, update latitude and longitude in the same request so delivery zones and distance calculations stay accurate.

Creating locations

Locations cannot be created on the public read/update routes above. Create them through one of:

Within an organization

POST /v1/organizations/{organization_id}/locations — creates a location under an existing organization.

Admin API

POST /admin/v1/locations or POST /admin/v1/organizations/{organization_id}/locations — for provisioning across organizations.

On creation, address is required and must include latitude and longitude. Coordinates power delivery radius checks, distance-based fees, and customer ETA — a location without them cannot accept geo-aware orders.

Resource-creating POSTs require an Idempotency-Key header so retries are safe.

Create a location under an organization

curl -X POST https://server.chataigne.ai/v1/organizations/org_3aN7vP0kLeQ4/locations \
  -H "x-api-key: ch_org_live_8f3kP2nQ..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c2a9e-7b4d-4e2a-9c3f-0a1b2c3d4e5f" \
  -d '{
    "name": "Châtaigne Genève — Eaux-Vives",
    "currency": "CHF",
    "country": "CH",
    "timezone": "Europe/Zurich",
    "default_language": "fr",
    "address": {
      "line1": "8 Rue Versonnex",
      "postal_code": "1207",
      "city": "Genève",
      "country": "CH",
      "latitude": 46.2044,
      "longitude": 6.1577
    }
  }'

Authentication & errors

All endpoints on this page live on the public /v1 surface and authenticate with an organization/location API key (prefix ch_org_) sent in the x-api-key header.

Admin keys (ch_admin_) are rejected with 403 on /v1, and a missing key returns 401. Dashboard sessions cannot be used on the API. See Authentication.

Status	Type	When
`401`	`authentication_error`	Missing or invalid API key.
`403`	`authorization_error`	Wrong key type for this surface, or no access to the location.
`404`	`not_found_error`	The `loc_…` does not exist or is not visible to your key.
`400`	`invalid_request_error`	Invalid field value (e.g. unsupported `currency`, malformed `address`).

Every response includes an X-Request-Id; error bodies mirror it as error.request_id. See Errors for the full error shape.

Organizations

Group locations and expand them inline.

Location settings

Opening hours, delivery, acceptance, AI instructions.

Special closings

Schedule one-off closures for a location.

​The location object

​List locations

​Retrieve a location

​Update a location

​Partial address merge

​Creating locations

Within an organization

Admin API

​Authentication & errors

​Related

Organizations

Location settings

Special closings

The location object

List locations

Retrieve a location

Update a location

Partial address merge

Creating locations

Authentication & errors

Related