Skip to main content
POST
/
experiences
/
{experience_id}
/
recurrences
curl -X POST \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "prov_xyz",
    "timezone": "America/New_York",
    "start_date": "2026-09-01",
    "cadence": { "frequency": "weekly", "interval": 1, "days_of_week": [1, 3] },
    "end_condition": { "type": "never" },
    "session_templates": [
      { "start_time_of_day": "09:00", "capacity": 12, "provider_id": "prov_xyz" },
      { "start_time_of_day": "17:00", "capacity": 12, "provider_id": "prov_xyz" }
    ]
  }' \
  "https://www.gomry.com/api/v1/experiences/AbCdEfGhIjKlMnOpQrSt/recurrences"

{
  "data": {
    "id": "rec_AbCdEfGh",
    "service_id": "AbCdEfGhIjKlMnOpQrSt",
    "provider_id": "prov_xyz",
    "timezone": "America/New_York",
    "start_date": "2026-09-01",
    "cadence": { "frequency": "weekly", "interval": 1, "days_of_week": [1, 3] },
    "end_condition": { "type": "never" },
    "session_templates": [
      { "start_time_of_day": "09:00", "capacity": 12, "provider_id": "prov_xyz", "days_of_week": null },
      { "start_time_of_day": "17:00", "capacity": 12, "provider_id": "prov_xyz", "days_of_week": null }
    ],
    "status": "active",
    "created_at": "2026-05-25T10:00:00.000Z",
    "updated_at": "2026-05-25T10:00:00.000Z"
  }
}

​
Create Recurrence

Attaches a schedule to an existing experience. The experience template itself must already exist (create it first via Create Experience). The recurrence defines a cadence (how often), an end condition (when to stop), and one or more session templates (what time each day, with what capacity and provider). Once an active recurrence exists, the public booking page expands its rules on-the-fly into the date/time grid — no separate “publish slots” step is required. Requires the experiences:write scope.

​
Idempotency

Pass an Idempotency-Key header (max 255 chars) to make POST retries safe. The first request executes the create; subsequent requests with the same key within 24 hours replay the original response verbatim — including the original status code — and add an Idempotent-Replay: true response header. Keys are scoped per API key, so two integrations can use the same key value without collision. Two concurrent requests with the same key return 409 idempotent_request_in_progress to the second caller.

​
Path Parameters

​
experience_id
string
required
Parent experience ID. Must belong to the API key’s organization.

​
Request Body

​
provider_id
string
required
Default provider (SpaceMember) for this recurrence. Used by session templates that don’t specify their own provider_id.
​
timezone
string
required
IANA timezone the schedule is anchored to (e.g. America/New_York). Session start times are interpreted in this zone.
​
start_date
string
required
First date the recurrence is active. Accepts an ISO-8601 datetime or a YYYY-MM-DD date string.
​
cadence
object
required
​
end_condition
object
required
Discriminated union, one of:
​
session_templates
array<object>
required
At least one template, up to 336. Each template materializes into one session per occurrence date.Two templates can share a start_time_of_day only if their days_of_week are disjoint.
​
status
enum
active or paused. Defaults to active.

​
Response

Returns the created recurrence with 201 Created.
​
data
object
Same schema as Get Recurrence.
curl -X POST \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id": "prov_xyz",
    "timezone": "America/New_York",
    "start_date": "2026-09-01",
    "cadence": { "frequency": "weekly", "interval": 1, "days_of_week": [1, 3] },
    "end_condition": { "type": "never" },
    "session_templates": [
      { "start_time_of_day": "09:00", "capacity": 12, "provider_id": "prov_xyz" },
      { "start_time_of_day": "17:00", "capacity": 12, "provider_id": "prov_xyz" }
    ]
  }' \
  "https://www.gomry.com/api/v1/experiences/AbCdEfGhIjKlMnOpQrSt/recurrences"

{
  "data": {
    "id": "rec_AbCdEfGh",
    "service_id": "AbCdEfGhIjKlMnOpQrSt",
    "provider_id": "prov_xyz",
    "timezone": "America/New_York",
    "start_date": "2026-09-01",
    "cadence": { "frequency": "weekly", "interval": 1, "days_of_week": [1, 3] },
    "end_condition": { "type": "never" },
    "session_templates": [
      { "start_time_of_day": "09:00", "capacity": 12, "provider_id": "prov_xyz", "days_of_week": null },
      { "start_time_of_day": "17:00", "capacity": 12, "provider_id": "prov_xyz", "days_of_week": null }
    ],
    "status": "active",
    "created_at": "2026-05-25T10:00:00.000Z",
    "updated_at": "2026-05-25T10:00:00.000Z"
  }
}