---
title: "Create or replace a tenant configuration entry by type"
method: POST
path: "/tenant-configurations/by-configuration-type/{configurationTypeId}"
tags: ["Tenant Configuration"]
---

# Create or replace a tenant configuration entry by type

`POST /tenant-configurations/by-configuration-type/{configurationTypeId}`

Creates or replaces (upserts) the configuration record for the given `configurationTypeId` and the tenant identified by the required `tenant-id` header.

Currently accepted type: only `tenant-timezone-config` is supported. Any other `configurationTypeId` value returns 400.

Request body — a JSON object with a single required field: `timezone` (string) must be a valid IANA time-zone identifier (e.g. `"America/New_York"`). An unrecognized zone ID returns 400.

Behavior: if no record exists for this tenant and type it is created; if one already exists it is fully replaced. Calling this endpoint twice with the same `timezone` value is safe and produces the same result (idempotent with respect to state).

Response — on success returns a flat `TenantTimezoneResponse` with fields `tenantId`, `configurationTypeId`, `timezone`, and `timezoneAbbreviation`. This shape differs from the `TenantConfigurationItemDto` envelope returned by the GET endpoints on this tag.

400 causes (three distinct triggers): (a) missing `tenant-id` header; (b) unsupported `configurationTypeId`; (c) missing or invalid `timezone` in the request body.

Side effects: persists the record to the data store. There is no automatic retry on write failures; a 500 indicates a persistent data-store error — consider a manual retry after a delay. The write is served by a different path than the cached GET-by-type read, so a successful write may not be immediately reflected by that read.

## Path parameters

- `configurationTypeId` string, required

## Headers

- `tenant-id` string, required

## Request body

- unknown

## Response `200`

The persisted timezone configuration as a flat `TenantTimezoneResponse`, including the resolved timezone abbreviation for the current date.

- TenantTimezoneResponse — Tenant timezone configuration response
  - `tenantId` string — Tenant ID this configuration belongs to
  - `configurationTypeId` string — Configuration type ID
  - `timezone` string — IANA timezone ID
  - `timezoneAbbreviation` string — Timezone abbreviation for the current date

## Other responses

- `400` — Request rejected for one of: missing `tenant-id` header (returns the nested `ApiError` shape via the header-validation filter); unsupported `configurationTypeId`; or a missing or invalid `timezone` in the body (the latter two are raised directly by this endpoint and return the flat `BadRequestErrorResponse` shape — a list of error strings, not the structured `ApiError` object). Correct the offending value and retry.
- `401` — Authentication token is missing, expired, or invalid. Obtain a valid JWT and retry.
- `500` — An unexpected error prevented the write; the configuration was not saved. The response body is a bare `{"error": "..."}` object, not the structured `ApiError` shape used elsewhere in this API. No automatic retry is performed — retry manually after a short delay and escalate if it persists.
- `502` — The downstream data store (DAL) returned a server error (5xx) while persisting the configuration; the write was not saved. Retry after a short delay and escalate if it persists.
- `503` — Unable to connect to the downstream data store (network/connectivity failure); the write was not saved. Retry after a short delay.

## Changes

- **2026-08-19** `563848e0ecc0` — 1 breaking, 22 warning, 5 info
  - the request's body type/format changed from `object`/`` to ``/``
  - removed the request property `array`
  - removed the request property `bigDecimal`
  - removed the request property `bigInteger`
  - …24 more

[Change history](https://skmtc.dev/certifyos/apis/certify-api-layer/changes/tenant-configurations/by-configuration-type/:configurationTypeId/post.md)

---

[API](https://skmtc.dev/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.dev/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)