# Recurring Events > **ALPHA** #### Description The `recurrence` parameter is used to define how an event recurs. It contains a `rules` Array that describe the frequency and interval. This is an array because some of the underlying calendar models support it, but in practice only one rule is provided and should be used. > **INFO:** Creating recurring events is not supported for Outlook.com calendars authorized before May 2024. Calendars authorized, or reauthorized, since that time are fully supported. #### Example Request ```http POST /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1 Host: {data_center_url} Authorization: Bearer {ACCESS_TOKEN} Content-Type: application/json; charset=utf-8 { "event_id": "recurrence-example", "summary": "Example", "start": "2026-05-06T15:30:00Z", "end": "2026-05-06T17:00:00Z", "tzid": "Europe/Berlin", "recurrence": { "rules": [ { "frequency": "weekly", "interval": 2 } ] } } ``` #### Parameters ##### `data_center_url` *(required)* The URL for the data center you want to communicate with. Possible choices are: - `api-au.cronofy.com` - Australia - `api-ca.cronofy.com` - Canada - `api-de.cronofy.com` - Germany - `api-sg.cronofy.com` - Singapore - `api-uk.cronofy.com` - United Kingdom - `api.cronofy.com` - United States Find out more about [Cronofy's data centers](/developers/data-centers/index.md). ##### `recurrence` *(optional)* Providing the `recurrence` parameter will cause the receiving calendar service to apply a recurrence rule to the event. Not providing the `recurrence` parameter will mean any existing rules are retained. To remove the recurrence rules from an event you must explicitly provide an empty array of recurrence rules. ##### `recurrence.rules.frequency` *(required)* A [`String`](/developers/api/data-types/index.md) value representing the frequency of recurrence. One of: - `daily` - `weekly` - `monthly` - `yearly` ##### `recurrence.rules.by_day` *(optional)* An array of [`String`](/developers/api/data-types/index.md) week days that the recurrence will generate events for. This is **only valid** for use with a **`weekly`** recurrence frequency, and if omitted the recurrence rule generates occurrences on the same day for each week it is active. Valid options are: - `sunday` - `monday` - `tuesday` - `wednesday` - `thursday` - `friday` - `saturday` ##### `recurrence.rules.interval` *(optional)* An [`Integer`](/developers/api/data-types/index.md) greater than zero describing the recurrence interval. Can be thought of "every X" (eg. "every day", "every week", etc). For example, biweekly needs an interval of 2 to make it "every 2 weeks". This can be applied to all frequencies so you can have "every 5 days", "every 4 weeks", "every 3 months", "every 2 years", and so on. ##### `recurrence.rules.count` *(optional)* An [`Integer`](/developers/api/data-types/index.md) greater than zero describing the number of occurrence that should be generated. For example, "five consecutive days" would be a `daily` frequency, with a `count` of `5`. If not specified, the number of occurrences are effectively infinite. ##### `recurrence.rules.until` *(optional)* A [`Date`](/developers/api/data-types/index.md) that occurrences should be generated until. This is *inclusive* and so if an occurrence falls on the specified date, that event will be created. ##### `recurrence.exceptions.add` *(optional)* An array of exceptions that should be excluded from the existing series if present. There can be a maximum of **64** exceptions to a series. ##### `recurrence.exceptions.add.date` *(optional)* The original [`Date`](/developers/api/data-types/index.md) of an occurrence that should be removed from the series of events created by the recurrence rule. This date is always interpreted in the local [time zone](/developers/api/events/upsert-event/index.md) of the event, and so may not match the date portion of the UTC-formatted `start` of the occurrence. For example, this creates a rule generating an event every week, except next week: ```json { "event_id": "recurrence-example", "summary": "Example", "start": "2026-05-06T15:30:00+01:00", "end": "2026-05-06T17:00:00+01:00", "tzid": "Europe/Berlin", "recurrence": { "rules": [ { "frequency": "weekly" } ], "exceptions": { "add": [ { "date": "2026-05-13" }, ] } } } ``` #### Common recurrence examples ##### Daily ```json { "event_id": "recurrence-example", "summary": "Example", "start": "2026-05-06T15:30:00Z", "end": "2026-05-06T17:00:00Z", "tzid": "Europe/Berlin", "recurrence": { "rules": [ { "frequency": "daily" } ] } } ``` ##### Weekly ```json { "event_id": "recurrence-example", "summary": "Example", "start": "2026-05-06T15:30:00Z", "end": "2026-05-06T17:00:00Z", "tzid": "Europe/Berlin", "recurrence": { "rules": [ { "frequency": "weekly" } ] } } ``` ##### Every weekday ```json { "event_id": "recurrence-example", "summary": "Example", "start": "2026-05-06T15:30:00Z", "end": "2026-05-06T17:00:00Z", "tzid": "Europe/Berlin", "recurrence": { "rules": [ { "frequency": "weekly", "by_day": [ {"day": "monday"}, {"day": "tuesday"}, {"day": "wednesday"}, {"day": "thursday"}, {"day": "friday"} ] } ] } } ``` ##### Biweekly ```json { "event_id": "recurrence-example", "summary": "Example", "start": "2026-05-06T15:30:00Z", "end": "2026-05-06T17:00:00Z", "tzid": "Europe/Berlin", "recurrence": { "rules": [ { "frequency": "weekly", "interval": 2 } ] } } ``` ##### Monthly ```json { "event_id": "recurrence-example", "summary": "Example", "start": "2026-05-06T15:30:00Z", "end": "2026-05-06T17:00:00Z", "tzid": "Europe/Berlin", "recurrence": { "rules": [ { "frequency": "monthly" } ] } } ``` ##### Yearly ```json { "event_id": "recurrence-example", "summary": "Example", "start": "2026-05-06T15:30:00Z", "end": "2026-05-06T17:00:00Z", "tzid": "Europe/Berlin", "recurrence": { "rules": [ { "frequency": "yearly" } ] } } ``` #### Caveats Only the first occurrence of the recurrence rule will be created as a managed event. Subsequent occurrences will be external events, so they will be filtered out if you set [only_managed](/developers/api/events/read-events/index.md) to `true` when calling the [Read Events endpoint](/developers/api/events/read-events/index.md). You'd need to omit this parameter or set it to `false` in order for all occurrences of the recurrence rule to be returned when making a Read Events request. You can read more about the differences between Partner Events and External Events in our [Editing Events guide](/developers/calendars-events/editing-events/index.md). Recurring events can be identified by the `recurring` Boolean attribute on events when making a [Read Events](/developers/api/events/read-events/index.md) request. Additionally, instances of a recurring managed event will have an [additional field of `series_master`](/developers/api/events/read-events/index.md) to identify the master event. An example Read Events response of the master event and its first occurrence, with some event fields omitted for brevity: ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "pages": { "current": 1, "total": 1 }, "events": [ { "calendar_id": "cal_n23kjnwrw2_jsdfjksn234", "event_id": "recurrence-example-1", "event_uid": "evt_partner_69457c026b1181330a97a32c", "summary": "Example event", "start": "2026-05-06T12:00:00Z", "end": "2026-05-06T13:00:00Z", "recurring": true, "recurrence": { "rules": [ { "frequency": "daily" } ] }, }, { "calendar_id": "cal_n23kjnwrw2_jsdfjksn234", "event_uid": "evt_external_69457c0910d011004bce1221", "summary": "Example event", "start": "2026-05-07T12:00:00Z", "end": "2026-05-07T13:00:00Z", "recurring": true, "series_identifier": "6fc02c78e9d6c7adb2bd11cf0f489b8b", "series_master": { "event_id": "recurrence-example-1", "event_uid": "evt_partner_69457c026b1181330a97a32c" }, } ] } ``` ##### Editing Recurring Events The occurrences of a recurring event, except the first, are not editable. In order to know if an event can be deleted or updated, the `options` attribute can be inspected when making a [Read Events](/developers/api/events/read-events/index.md) request. ##### Deleting Recurring Events To delete external events, you must request [elevated access to access the user's calendars](/developers/api/authorization/extended-permissions/index.md). Then, the event itself must be have its `options.delete` flag set to `true`. For more information on deleting external events, please see our [Delete External Event](/developers/api/events/delete-external-event/index.md) guide. --- [Read in HTML](/developers/api-alpha/recurring-events/)