Replace sales availability

PUT /api/v1/sales-availability

Replaces the complete sales availability configuration of the organization bound to the API key, in one transaction. Anything you omit is gone: an empty closers array, weekly array or exceptions array deliberately clears what was there.

Authorization

Request headers

Request body

{
  "timeZone": "Europe/Paris",
  "durationMinutes": 45,
  "bufferBeforeMinutes": 15,
  "bufferAfterMinutes": 15,
  "closers": [
    {
      "userId": "11111111-1111-4111-8111-111111111111",
      "position": 1,
      "active": true,
      "dailyCapacity": 4,
      "weekly": [
        { "weekday": 1, "windows": [{ "startMinute": 540, "endMinute": 720 }] }
      ],
      "exceptions": [
        { "localDate": "2026-09-22", "effect": "unavailable", "windows": [] }
      ]
    }
  ]
}

Example

curl -X PUT "$COHORTE_API_BASE_URL/api/v1/sales-availability" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: sales-availability-2026-09-15" \
  -H "Content-Type: application/json" \
  -d '{"timeZone":"Europe/Paris","durationMinutes":45,"bufferBeforeMinutes":15,"bufferAfterMinutes":15,"closers":[{"userId":"11111111-1111-4111-8111-111111111111","position":1,"active":true,"dailyCapacity":4,"weekly":[{"weekday":1,"windows":[{"startMinute":540,"endMinute":720}]}],"exceptions":[]}]}'

Response

• 200 OK — the configuration as stored. replayed: true when the key was already used.
• 400 Bad Request — missing Idempotency-Key, invalid JSON, an unknown time zone, a value outside its allowed set or bounds, a closer listed twice, a weekday or exception date repeated for one closer, ranges that overlap once buffers are applied, an exception whose windows contradict its effect, or a closer without the organization closer responsibility; code is invalid_request.
• 401 Unauthorized — missing, unknown or expired key; code is unauthorized.
• 403 Forbidden — the bearer is not OWNER or ADMIN; code is forbidden. A closer or setter responsibility never grants it: closers read the configuration, only the school edits it.

Response fields

The stored configuration, with the same fields as Read sales availability, plus the envelope:

Example response

{
  "success": true,
  "replayed": false,
  "data": {
    "organizationId": "5e0b7a61-0000-4000-8000-000000000000",
    "timeZone": "Europe/Paris",
    "durationMinutes": 45,
    "bufferBeforeMinutes": 15,
    "bufferAfterMinutes": 15,
    "rotationCursor": 3,
    "version": 8,
    "closers": [
      {
        "id": "c3f1d8a2-0000-4000-8000-000000000000",
        "userId": "11111111-1111-4111-8111-111111111111",
        "name": "Sophie Laurent",
        "email": "sophie@example.com",
        "position": 1,
        "active": true,
        "dailyCapacity": 4,
        "weekly": [
          { "weekday": 1, "windows": [{ "startMinute": 540, "endMinute": 720 }] }
        ],
        "exceptions": []
      }
    ]
  },
  "correlationId": "9d0f2c47-0000-4000-8000-000000000000"
}

Notes

• It is a full replacement. Read the configuration first, change what you need, and send everything back.
• Times are local wall-clock minutes in the persisted time zone; never send a fixed UTC offset.
• organizationId is not a field: the organization comes from the key, and a value sent in the body changes nothing.
• A replay with the same Idempotency-Key returns the original state without a second audit entry or event.
• The replacement writes an audit entry and a sales_availability.replaced domain event. It creates no booking.

Related

• Read sales availability
• Preview sales slots

Scheduling retry contract

Keep one idempotency key for one normalized intention. Current authorization is checked again on retry. A different payload or resource with that key, or an older key whose intention cannot be verified, returns 409 conflict without another mutation. Inspect the original outcome before creating a new command. Identical retries do not resend notifications.

Personal time zones and compatibility

closers[].timeZone is an optional IANA string in the request and a required string in the response. Invalid zones return 400. An explicit value changes that closer’s schedule zone, preserving the submitted wall-clock minutes and exception dates. Confirmed bookings retain their instants.

When omitted, an existing closer keeps their saved zone. A newly configured closer inherits their prepared draft zone, or the school zone if no draft exists. Changing the school timeZone never resets existing personal zones. An idempotent replay returns its historical configuration, including the historical school zone for older records that predate personal zones.

Daily capacity and exceptions use each closer’s local calendar. Available slots are the sorted union of UTC instants from those calendars. Nonexistent spring DST times are skipped; repeated fall times use the later occurrence. Durations and buffers remain elapsed time and must fit within availability.

Public booking horizon

bookingHorizonDays is a nullable integer from 1 to 365. It limits the start of new public bookings (page and widget) to strictly before the current instant plus that many 24-hour days. Booking links inherit this school setting. A null value means no horizon limit. When replacing availability, omitting the field preserves the current limit; sending null clears it. Existing bookings, rescheduling, operator-created bookings and internal previews are unchanged. Historical responses without a configured limit return null.

Closer booking horizon

Each closer availability accepts optional nullable bookingHorizonDays (integer 1–365). Omission preserves the stored value; null inherits the team limit. Personal availability reads also expose teamBookingHorizonDays. The effective public booking limit is the minimum of configured team and closer limits. Candidates are evaluated independently: a restricted closer does not hide slots offered by another closer. Both null means unlimited. Existing appointments, rescheduling and operator bookings are unchanged. Prepared availability keeps this setting when adopted by an administrator. Existing rights and idempotency apply.