Organizations - Chataigne Docs

An organization is the top-level account object. It owns one or more locations (restaurants) and is the entity your API key is scoped to.

Every API key (prefix ch_org_) is bound to exactly one organization. Endpoints under /v1/organizations therefore operate on your organization. The Admin API (/admin/v1, keys prefixed ch_admin_) can manage organizations across accounts.

The organization object

string

Unique identifier, prefixed org_.

object

string

Always organization.

name

string

Human-readable name of the organization.

location_ids

string[]

All location IDs (loc_…) belonging to this organization.

active_location_ids

string[]

Subset of location_ids that are currently active.

created_at

string

ISO 8601 UTC timestamp of creation.

updated_at

string

ISO 8601 UTC timestamp of the last update.

locations

location[]

The expanded location objects. Returned only when you request expand[]=locations.

The organization object

{
  "id": "org_8f2k1d9a",
  "object": "organization",
  "name": "Trattoria Group",
  "location_ids": ["loc_7c3b1e", "loc_9a4f2d"],
  "active_location_ids": ["loc_7c3b1e"],
  "created_at": "2025-01-12T09:30:00Z",
  "updated_at": "2025-04-03T14:22:10Z"
}

Expanding locations

Pass expand[]=locations on retrieve endpoints to inline full location objects under the locations field instead of receiving only location_ids.

curl https://server.chataigne.ai/v1/organizations/org_8f2k1d9a?expand[]=locations \
  -H "x-api-key: ch_org_live_xxx"

List organizations

GET /v1/organizations

Returns organizations accessible to your API key. With an organization key this list contains the single organization the key is scoped to. Auth: organization API key (ch_org_…). Admin keys are rejected with 403.

Query parameters

limit

integer

default:"10"

Page size, between 1 and 100.

starting_after

string

Cursor: return results after this object ID. Mutually exclusive with ending_before.

ending_before

string

Cursor: return results before this object ID. Mutually exclusive with starting_after.

created_after

string

Only return organizations created at or after this ISO 8601 timestamp.

created_before

string

Only return organizations created at or before this ISO 8601 timestamp.

updated_after

string

Only return organizations updated at or after this ISO 8601 timestamp.

updated_before

string

Only return organizations updated at or before this ISO 8601 timestamp.

expand[]

string

Expand related fields on each item, e.g. expand[]=locations.

Request

curl "https://server.chataigne.ai/v1/organizations?limit=10" \
  -H "x-api-key: ch_org_live_xxx"

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "org_8f2k1d9a",
      "object": "organization",
      "name": "Trattoria Group",
      "location_ids": ["loc_7c3b1e", "loc_9a4f2d"],
      "active_location_ids": ["loc_7c3b1e"],
      "created_at": "2025-01-12T09:30:00Z",
      "updated_at": "2025-04-03T14:22:10Z"
    }
  ],
  "has_more": false,
  "url": "/v1/organizations"
}

Error example

401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No API key provided. Pass your key in the x-api-key header.",
    "request_id": "req_1a2b3c4d"
  }
}

Retrieve an organization

GET /v1/organizations/{organization_id}

Retrieves a single organization by ID. Auth: organization API key. The key must be scoped to the requested organization, otherwise a not_found_error (404) is returned.

Path parameters

organization_id

string

required

The organization ID, e.g. org_8f2k1d9a.

Query parameters

expand[]

string

Expand related fields, e.g. expand[]=locations.

Request

curl "https://server.chataigne.ai/v1/organizations/org_8f2k1d9a?expand[]=locations" \
  -H "x-api-key: ch_org_live_xxx"

Response

200 OK

{
  "id": "org_8f2k1d9a",
  "object": "organization",
  "name": "Trattoria Group",
  "location_ids": ["loc_7c3b1e", "loc_9a4f2d"],
  "active_location_ids": ["loc_7c3b1e"],
  "created_at": "2025-01-12T09:30:00Z",
  "updated_at": "2025-04-03T14:22:10Z",
  "locations": [
    {
      "id": "loc_7c3b1e",
      "object": "location",
      "organization_id": "org_8f2k1d9a",
      "name": "Trattoria Lausanne",
      "currency": "CHF",
      "country": "CH",
      "timezone": "Europe/Zurich",
      "default_language": "fr",
      "address": {
        "line1": "Rue de Bourg 12",
        "line2": null,
        "postal_code": "1003",
        "city": "Lausanne",
        "country": "CH",
        "latitude": 46.5197,
        "longitude": 6.6323
      },
      "created_at": "2025-01-12T09:31:00Z",
      "updated_at": "2025-03-20T11:05:00Z"
    }
  ]
}

Error example

404 Not Found

{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No organization found with id 'org_unknown'.",
    "param": "organization_id",
    "request_id": "req_5e6f7g8h"
  }
}

Update an organization

PATCH /v1/organizations/{organization_id}

Updates the organization identified by {organization_id} (which your API key must have access to). Only the fields you supply are changed. Auth: organization API key.

Body parameters

name

string

New name for the organization.

location_ids, active_location_ids, and all timestamps are managed by Chataigne and cannot be set directly. To add a location, use Create a location.

Request

curl -X PATCH "https://server.chataigne.ai/v1/organizations/org_8f2k1d9a" \
  -H "x-api-key: ch_org_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Trattoria Group SA" }'

Response

200 OK

{
  "id": "org_8f2k1d9a",
  "object": "organization",
  "name": "Trattoria Group SA",
  "location_ids": ["loc_7c3b1e", "loc_9a4f2d"],
  "active_location_ids": ["loc_7c3b1e"],
  "created_at": "2025-01-12T09:30:00Z",
  "updated_at": "2025-05-29T08:14:00Z"
}

Error example

400 Bad Request

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_empty",
    "message": "The 'name' field must be a non-empty string.",
    "param": "name",
    "request_id": "req_9i0j1k2l"
  }
}

List an organization’s locations

GET /v1/organizations/{organization_id}/locations

Lists the locations belonging to an organization. Supports the standard cursor pagination and timestamp filters. Auth: organization API key scoped to the organization.

Path parameters

organization_id

string

required

The organization ID, e.g. org_8f2k1d9a.

Query parameters

limit

integer

default:"10"

Page size, between 1 and 100.

starting_after

string

Cursor: return results after this location ID. Mutually exclusive with ending_before.

ending_before

string

Cursor: return results before this location ID. Mutually exclusive with starting_after.

created_after

string

Only locations created at or after this ISO 8601 timestamp.

created_before

string

Only locations created at or before this ISO 8601 timestamp.

updated_after

string

Only locations updated at or after this ISO 8601 timestamp.

updated_before

string

Only locations updated at or before this ISO 8601 timestamp.

Request

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

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "loc_7c3b1e",
      "object": "location",
      "organization_id": "org_8f2k1d9a",
      "name": "Trattoria Lausanne",
      "currency": "CHF",
      "country": "CH",
      "timezone": "Europe/Zurich",
      "default_language": "fr",
      "address": {
        "line1": "Rue de Bourg 12",
        "line2": null,
        "postal_code": "1003",
        "city": "Lausanne",
        "country": "CH",
        "latitude": 46.5197,
        "longitude": 6.6323
      },
      "created_at": "2025-01-12T09:31:00Z",
      "updated_at": "2025-03-20T11:05:00Z"
    },
    {
      "id": "loc_9a4f2d",
      "object": "location",
      "organization_id": "org_8f2k1d9a",
      "name": "Trattoria Geneva",
      "currency": "CHF",
      "country": "CH",
      "timezone": "Europe/Zurich",
      "default_language": "fr",
      "address": null,
      "created_at": "2025-02-01T10:00:00Z",
      "updated_at": "2025-02-01T10:00:00Z"
    }
  ],
  "has_more": false,
  "url": "/v1/organizations/org_8f2k1d9a/locations"
}

Paginate by passing the last item’s id as starting_after until has_more is false.

Error example

403 Forbidden

{
  "error": {
    "type": "authorization_error",
    "code": "key_type_not_allowed",
    "message": "Admin API keys cannot be used on the /v1 surface.",
    "request_id": "req_3m4n5o6p"
  }
}

Create a location

POST /v1/organizations/{organization_id}/locations

Creates a new location under the organization. Auth: organization API key scoped to the organization.

This endpoint creates a resource, so the Idempotency-Key header is required. Replaying the same key with the same body returns the original response with Idempotent-Replayed: true. The same key with a different body returns an idempotency_error (409); a concurrent in-flight duplicate returns a conflict_error (409). Keys are retained for 24 hours.

Path parameters

organization_id

string

required

The organization ID, e.g. org_8f2k1d9a.

Headers

Idempotency-Key

string

required

A unique key for safely retrying the request, e.g. a UUID you generate.

Body parameters

name

string

required

Display name of the location.

currency

string

required

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

country

string

required

ISO country code. One of FR, CH, GB, BR, LU, MX, US.

timezone

string

required

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

default_language

string

Default language code for the location, e.g. fr. Optional — when omitted it is inferred from the country. Countries without a single default language (e.g. CH) require it, and a missing value returns a 400 invalid_request_error.

address

object

Postal address. Set to null or omit if unknown.

Show address

line1

string

line2

string

postal_code

string

city

string

country

string

latitude

number

longitude

number

Request

curl -X POST "https://server.chataigne.ai/v1/organizations/org_8f2k1d9a/locations" \
  -H "x-api-key: ch_org_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "name": "Trattoria Montreux",
    "currency": "CHF",
    "country": "CH",
    "timezone": "Europe/Zurich",
    "default_language": "fr",
    "address": {
      "line1": "Grand-Rue 50",
      "postal_code": "1820",
      "city": "Montreux",
      "country": "CH"
    }
  }'

Response

201 Created

{
  "id": "loc_2e5d8c",
  "object": "location",
  "organization_id": "org_8f2k1d9a",
  "name": "Trattoria Montreux",
  "currency": "CHF",
  "country": "CH",
  "timezone": "Europe/Zurich",
  "default_language": "fr",
  "address": {
    "line1": "Grand-Rue 50",
    "line2": null,
    "postal_code": "1820",
    "city": "Montreux",
    "country": "CH",
    "latitude": null,
    "longitude": null
  },
  "created_at": "2025-05-29T08:20:00Z",
  "updated_at": "2025-05-29T08:20:00Z"
}

Error example

409 Conflict

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_in_use",
    "message": "This Idempotency-Key was already used with a different request body.",
    "request_id": "req_7q8r9s0t"
  }
}

Errors

All errors return an HTTP status with a body shaped as:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "A required parameter is missing.",
    "param": "name",
    "request_id": "req_abc123"
  }
}

Type	HTTP	When it happens
`invalid_request_error`	400	Malformed request or invalid parameter.
`authentication_error`	401	Missing API key.
`authorization_error`	403	Wrong key type for the surface (admin key on `/v1`, org key on `/admin/v1`).
`not_found_error`	404	Organization or location not found / not accessible to the key.
`conflict_error`	409	Concurrent in-flight duplicate of an idempotent request.
`idempotency_error`	409	Same `Idempotency-Key` reused with a different body.
`rate_limit_error`	429	Per-key, per-surface rate limit exceeded. Honor `Retry-After`.
`api_error`	500	Unexpected server error.

Every response carries an X-Request-Id header, mirrored in error bodies as error.request_id. You may echo your own with the x-request-id header. Include it when contacting support. Rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are present on every response.

Locations

Retrieve and update locations, settings, opening hours, and special closings.

​The organization object

​Expanding locations

​List organizations

​Query parameters

​Request

​Response

​Error example

​Retrieve an organization

​Path parameters

​Query parameters

​Request

​Response

​Error example

​Update an organization

​Body parameters

​Request

​Response

​Error example

​List an organization’s locations

​Path parameters

​Query parameters

​Request

​Response

​Error example

​Create a location

​Path parameters

​Headers

​Body parameters

​Request

​Response

​Error example

​Errors

​Related resources

Locations

The organization object

Expanding locations

List organizations

Query parameters

Request

Response

Error example

Retrieve an organization

Path parameters

Query parameters

Request

Response

Error example

Update an organization

Body parameters

Request

Response

Error example

List an organization’s locations

Path parameters

Query parameters

Request

Response

Error example

Create a location

Path parameters

Headers

Body parameters

Request

Response

Error example

Errors

Related resources