# 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-10-25T15:30:00Z",
  "end": "2026-10-25T17: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](https://docs.cronofy.com/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`](https://docs.cronofy.com/api-reference/fundamentals/data-types/index.md) value representing the
frequency of recurrence. One of:

- `daily`

- `weekly`

- `monthly`

- `yearly`

##### `recurrence.rules.by_day` *(optional)*

An array of objects describing which week days the recurrence will generate
events for. Each entry must specify a `day` and, when the recurrence
frequency is `monthly`, an `nth_of_period`.

This is valid for use with `weekly` and `monthly` recurrence frequencies. If
omitted from a `weekly` rule, occurrences are generated on the same day for
each week it is active.

When the recurrence frequency is `monthly`, `by_day` cannot contain multiple
entries.

##### `recurrence.rules.by_day.day` *(required)*

A [`String`](https://docs.cronofy.com/api-reference/fundamentals/data-types/index.md) week day. Valid options
are:

- `sunday`

- `monday`

- `tuesday`

- `wednesday`

- `thursday`

- `friday`

- `saturday`

##### `recurrence.rules.by_day.nth_of_period` *(optional)*

An [`Integer`](https://docs.cronofy.com/api-reference/fundamentals/data-types/index.md) describing which
occurrence of the specified `day` within the period the recurrence applies
to. Valid values are `1`, `2`, `3`, `4`, and `-1` (where `-1` means the
last occurrence of that day in the period).

Required when the recurrence frequency is `monthly`. Not permitted when the
recurrence frequency is `weekly`.

When creating an event with a "first Monday of each month" type rule, it is
strongly recommended to ensure the first event itself matches this rule (i.e.
that it is on the first Monday of its month) to avoid unexpected behavior.
Different providers have been seen to have varying support for an exceptional
date on the first event.

##### `recurrence.rules.interval` *(optional)*

An [`Integer`](https://docs.cronofy.com/api-reference/fundamentals/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`](https://docs.cronofy.com/api-reference/fundamentals/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`](https://docs.cronofy.com/api-reference/fundamentals/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`](https://docs.cronofy.com/api-reference/fundamentals/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](https://docs.cronofy.com/api-reference/calendar-control/calendar-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-10-25T15:30:00+01:00",
  "end": "2026-10-25T17:00:00+01:00",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "weekly" }
    ],
    "exceptions": {
      "add": [
        { "date": "2026-11-01" },
      ]
    }
  }
}
```

### Common recurrence examples
#### Daily
```json
{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2026-10-25T15:30:00Z",
  "end": "2026-10-25T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "daily" }
    ]
  }
}
```

#### Weekly
```json
{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2026-10-25T15:30:00Z",
  "end": "2026-10-25T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "weekly" }
    ]
  }
}
```

#### Every weekday
```json
{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2026-10-25T15:30:00Z",
  "end": "2026-10-25T17: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-10-25T15:30:00Z",
  "end": "2026-10-25T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "weekly", "interval": 2 }
    ]
  }
}
```

#### Monthly
```json
{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2026-10-25T15:30:00Z",
  "end": "2026-10-25T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      { "frequency": "monthly" }
    ]
  }
}
```

#### Monthly on the first Monday
```json
{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2026-10-25T15:30:00Z",
  "end": "2026-10-25T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      {
        "frequency": "monthly",
        "by_day": [
          { "day": "monday", "nth_of_period": 1 }
        ]
      }
    ]
  }
}
```

#### Monthly on the last Friday
```json
{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2026-10-25T15:30:00Z",
  "end": "2026-10-25T17:00:00Z",
  "tzid": "Europe/Berlin",
  "recurrence": {
    "rules": [
      {
        "frequency": "monthly",
        "by_day": [
          { "day": "friday", "nth_of_period": -1 }
        ]
      }
    ]
  }
}
```

#### Yearly
```json
{
  "event_id": "recurrence-example",
  "summary": "Example",
  "start": "2026-10-25T15:30:00Z",
  "end": "2026-10-25T17: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](https://docs.cronofy.com/api-reference/calendar-control/calendar-events/read-events/index.md) to `true` when calling the [Read Events endpoint](https://docs.cronofy.com/api-reference/calendar-control/calendar-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](https://docs.cronofy.com/developers/calendars-events/editing-events/index.md).

Recurring events can be identified by the `recurring` Boolean attribute on events when making a [Read Events](https://docs.cronofy.com/api-reference/calendar-control/calendar-events/read-events/index.md) request. Additionally, instances of a recurring managed event will have an [additional field of `series_master`](https://docs.cronofy.com/api-reference/calendar-control/calendar-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-10-25T12:00:00Z",
      "end": "2026-10-25T13:00:00Z",
      "recurring": true,
      "recurrence": {
        "rules": [
          {
            "frequency": "daily"
          }
        ]
      },
    },
    {
      "calendar_id": "cal_n23kjnwrw2_jsdfjksn234",
      "event_uid": "evt_external_69457c0910d011004bce1221",
      "summary": "Example event",
      "start": "2026-10-26T12:00:00Z",
      "end": "2026-10-26T13: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](https://docs.cronofy.com/api-reference/calendar-control/calendar-events/read-events/index.md) request.

#### Deleting Recurring Events
To delete external events, you must request [elevated access to access the user's calendars](https://docs.cronofy.com/api-reference/authorization/individual-connect/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](https://docs.cronofy.com/api-reference/calendar-control/calendar-events/delete-external-event/index.md) guide.



---
[Read in HTML](https://docs.cronofy.com/api-reference/calendar-control/recurring-events/)