# List services

Returns the services of the Location as a cursor-paginated list. Prices are integer
minor units; `duration_seconds` is the default duration, and `team_members[]` lists the
Team Members providing the service by id.
Cursor-paginated list. Default ordering: `id` ascending. Cursors use the `cursor` query parameter, expire after one hour, and are bound to the credential, tenant, list, and filters. Expired, malformed, foreign, or re-filtered cursors fail with `422 validation_failed` using field codes `expired_cursor`, `invalid_cursor`, `foreign_cursor`, or `filter_changed`.

Endpoint: GET /locations/{location_id}/services
Version: 3.0.0-preview
Security: OAuth2, ApiKey

## Security:

  - `OAuth2` (unknown)
    oauth2 scopes: services:read

  - `ApiKey` (unknown)
    http bearer

## Path parameters:

  - `location_id` (integer, required)
    Identifier of the Location. Verified against the credential on every call — a Location the credential cannot access responds with `404`.

## Query parameters:

  - `limit` (integer)
    Page size for cursor pagination. Default is 25; maximum is 100. Values outside 1..100 or non-integers fail with `422 validation_failed`; the value is never clamped.

  - `cursor` (string)
    Opaque cursor from `next_cursor`. An empty value is the same as omitting the parameter and returns the first page. Cursors expire one hour after the response that issued them (every page issues a fresh cursor) and are bound to credential, tenant, list, filters, and ordering; for OAuth the credential is the user's authorization, so a cursor survives a token refresh; a row whose ordering column changed between pages may be skipped or returned twice, and a row created while you page may be missing from this pass if it sorts before the current position (start a new pass to pick it up); expired, malformed, foreign, or re-filtered cursors fail with `422 validation_failed` using field codes `expired_cursor`, `invalid_cursor` (also a cursor whose number of key values does not match the list's ordering), `foreign_cursor` (another credential or tenant), or `filter_changed` (another list, ordering, or filters).

## Response 200:

  - `200` (unknown)
    A page of services.

## Response 200 fields (application/json):

  - `object` (string, required)
    Enum: "list"

  - `has_more` (boolean, required)
    Whether more items exist beyond this page.

  - `next_cursor` (string | null, required)
    Opaque cursor for the next page; `null` on the last page.

  - `data` (array, required)

  - `data.id` (integer, required)

  - `data.object` (string, required)
    Enum: "service"

  - `data.type` (string, required)
    Service kind. Immutable after creation (`422 field_immutable`). A package service bundles several simple services of the same Location; it appears in the same list and is scheduled by the same `service_id`.
    Enum: "simple", "package"

  - `data.package` (any, required)
    Package settings and components; `null` when `type` is `simple`.

  - `data.package.exec_order` (string, required)
    Order in which component services are performed.
    Enum: "sequential", "sequential_multi", "parallel"

  - `data.package.pricing_type` (string, required)
    How the package price derives from its components.
    Enum: "sum", "manual", "discount"

  - `data.package.price_discount_percent` (number, required)
    Discount applied to the component sum; used only when `pricing_type` is `discount`, ignored otherwise.

  - `data.package.components` (array, required)
    Component services in execution order; empty while the package is `not_configured`.

  - `data.package.components.id` (integer, required)
    Stable package-component identifier used by availability and package appointment creation.

  - `data.package.components.service_id` (integer, required)
    A `simple` service of the same Location.

  - `data.package.components.position` (integer, required)
    1-based order of the component.

  - `data.package.status` (string, required)
    Read-only package configuration status.
    Enum: "not_configured", "ready"

  - `data.name` (string, required)
    Internal name shown to the business in Altegio, as the business entered it; not translated.

  - `data.online_booking_name` (string, required)
    Client-facing name shown in online booking, as the business entered it; equals `name` when no separate online booking name is set. Not translated.

  - `data.category_id` (integer | null, required)
    Service category (`listServiceCategories`); `null` when the category is not listed in this Location.

  - `data.duration_seconds` (integer, required)
    Default duration of the service in seconds (the Location-wide default, `3600` when none is set).

  - `data.weight` (integer, required)
    Display order the business set in Altegio (higher first). Lists are ordered by `id`; sort by `weight` on the client.

  - `data.currency` (string, required)
    ISO 4217, server-controlled by the Location.

  - `data.online_booking_enabled` (boolean, required)
    The business's online booking setting for this service in the Location. It does not mean that free time is available; free slots come from the availability operations.

  - `data.team_members` (array, required)
    Team Members providing this service, by id. Read-only here; links are written through `updateTeamMemberServices`.

  - `data.team_members.team_member_id` (integer, required)

  - `data.created_at` (string | null, required)
    UTC; `null` when the creation date is not stored.

  - `data.price_min_minor` (integer, required)
    Base price of the service in this Location, integer minor units of the Location currency, as set by the business: a single price or the lower bound of a range. For a package, the package price stored in Altegio. Team Member prices by grade can differ.

  - `data.price_max_minor` (integer | null, required)
    Upper bound of the base price range, integer minor units of the Location currency; equals `price_min_minor` for a single price; `null` for a legacy "from" price without an upper bound.

## Response 200 headers (application/json):

  - `RateLimit-Remaining` (integer)
    Requests left in the most constrained policy window that applies to this request.

  - `RateLimit-Reset` (integer)
    On `429`, seconds until the most constrained policy frees up; it equals `Retry-After` there.
On a successful response it reports the **length** of that policy's window rather than the
time left in the current one, so treat it as the window size, not as a countdown — the
counter to pace against is `RateLimit-Remaining`.

  - `RateLimit-Policy` (string)
    Most constrained policy applied to the request, as `<limit>;w=<window in seconds>`.
    Example: 10;w=60

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 400:

  - `400` (unknown)
    Client error without a more specific registered code (`bad_request` — status default for
bare 400 and unknown 4xx), or protocol/syntax failure (`malformed_request` — broken JSON /
unparseable body only; must be thrown explicitly, never used as a synonym for every 400).
Semantic field validation is `422 validation_failed`, not 400.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 400 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 401:

  - `401` (unknown)
    The request has no valid Bearer credential (`invalid_token`).

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 401 headers (application/problem+json):

  - `WWW-Authenticate` (string)
    Bearer challenge with the URL of the protected resource metadata (RFC 9728 §5.1),
where the client finds the authorization server.
    Example: Bearer resource_metadata="https://api.alteg.io/.well-known/oauth-protected-resource/api/v3"

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 403:

  - `403` (unknown)
    The token lacks the required scope (`missing_scope`), the scope is present but the token subject lacks the business permission (`permission_denied`), or the Location has no active license (`subscription_inactive`).

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 403 headers (application/problem+json):

  - `WWW-Authenticate` (string)
    Only on `missing_scope`: Bearer challenge with `error="insufficient_scope"`, the scope the
operation requires and the URL of the protected resource metadata (RFC 6750 §3.1, RFC 9728 §5.1).
    Example: Bearer error="insufficient_scope", scope="team_members:read", resource_metadata="https://api.alteg.io/.well-known/oauth-protected-resource/api/v3"

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 404:

  - `404` (unknown)
    The resource does not exist or is hidden by tenant policy. Prefer a resource-specific
code (`appointment_not_found`, `location_not_found`, …). Routing/gate/unknown-path 404s
use the generic `resource_not_found` (same shape, so "no pin" and "missing" are not distinguished).

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 404 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 406:

  - `406` (unknown)
    Requested `Accept` media type cannot be satisfied (`not_acceptable`).

## Response 406 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 406 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 409:

  - `409` (unknown)
    Domain conflict (`slot_taken`, `duplicate_location`, `last_location_owner`), idempotency conflict, or generic `conflict` when no more specific registered code applies.

## Response 409 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 409 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

  - `Retry-After` (integer)
    Seconds to wait before retrying.

## Response 422:

  - `422` (unknown)
    Semantic validation failed (`validation_failed`); field-level details are in `errors[]`. Merge-patch violations use `field_not_nullable` / `field_immutable`.

## Response 422 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 422 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 429:

  - `429` (unknown)
    Rate limit exceeded (`rate_limit_exceeded`). Retry after `Retry-After`.

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 429 headers (application/problem+json):

  - `Retry-After` (integer)
    Seconds to wait before retrying.

  - `RateLimit-Remaining` (integer)
    Requests left in the most constrained policy window that applies to this request.

  - `RateLimit-Reset` (integer)
    On `429`, seconds until the most constrained policy frees up; it equals `Retry-After` there.
On a successful response it reports the **length** of that policy's window rather than the
time left in the current one, so treat it as the window size, not as a countdown — the
counter to pace against is `RateLimit-Remaining`.

  - `RateLimit-Policy` (string)
    Most constrained policy applied to the request, as `<limit>;w=<window in seconds>`.
    Example: 10;w=60

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 500:

  - `500` (unknown)
    Unexpected server error (`internal_error`).

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 500 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 503:

  - `503` (unknown)
    A dependency required for safe processing (e.g. the idempotency store) is unavailable; the write was **not** performed (`dependency_unavailable`). Retry with the same `Idempotency-Key` after a backoff.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    Stable URL identifying the problem type; links to documentation.

  - `title` (string, required)
    Human-readable summary of the problem type.

  - `status` (integer, required)
    HTTP status code of this response.

  - `detail` (string)
    Human-readable explanation of this occurrence.

  - `instance` (string, required)
    Request identifier for support and log correlation.

  - `code` (string, required)
    Stable machine-readable reason code.

  - `errors` (array)
    Field-level issues (present on validation problems).

  - `errors.code` (string, required)
    Stable machine-readable reason for this field.

  - `errors.pointer` (string, required)
    JSON Pointer for `body`; parameter name for `query`, `path`, or `header`.

  - `errors.message` (string, required)
    Human-readable explanation.

  - `errors.source` (string, required)
    Where the invalid value came from.
    Enum: "body", "query", "path", "header"

## Response 503 headers (application/problem+json):

  - `X-Request-Id` (string)
    Request identifier for support and log correlation.

## Response 400 examples:

  - `Generic client reject (status default)` (unknown)

  - `Broken JSON / protocol only` (unknown)

## Response 403 examples:

  - `Token scope is insufficient` (unknown)

  - `Subject lacks the business permission` (unknown)

  - `Location license is not active` (unknown)

## Response 404 examples:

  - `Generic 404 (routing / gate / hidden)` (unknown)

  - `Resource-specific 404` (unknown)