> For the complete documentation index, see [llms.txt](https://docs.vomevolunteer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vomevolunteer.com/resources/schedule/shift-series/create-a-shift-series.md).

# Create a shift series

A series is created through the Shifts endpoint, because in Vome a series is a kind of shift. Any row in the `shifts` array that carries a `series` block becomes a series instead of a single shift.

The shift fields describe **one occurrence**. The `series` block says how it repeats.

#### Endpoint

`POST /api/shifts/bulk-create/`

### The series block

These are the same four things the Series tab asks for in Vome.

| Field          | Type   | Description                                                                                                                                                                                                                          |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `repeat_every` | string | **Required.** `day`, `week`, `2_weeks`, or `month`. Matches Week, 2 weeks and Month in the popup.                                                                                                                                    |
| `repeat_on`    | array  | **Required for `week` and `2_weeks`.** Any of `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`.                                                                                                                                       |
| `monthly_on`   | object | Monthly only, optional. `{"week": "second", "day": "mon"}` is the second Monday of each month. `week` takes `first`, `second`, `third`, `fourth`, `last`. Leave it out and a monthly series repeats on the same **date** each month. |
| `start_date`   | date   | Optional. Defaults to the date of `shift_start_at`.                                                                                                                                                                                  |
| `end_date`     | date   | Optional. **Leave it out for an open-ended series**, which is the usual case.                                                                                                                                                        |

Every other field on the row is an ordinary shift field: `opportunity_id`, `shift_start_at`, `shift_end_at`, `spots`, `shift_title`, `shift_description`, `shift_timezone`, `shift_location_id`, `shift_type`, `minimum_time_minutes`.

#### Payload sample

Every Tuesday and Thursday evening, open-ended.

```json
{
  "shifts": [
    {
      "opportunity_id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
      "shift_start_at": "2026-11-10T19:00:00Z",
      "shift_end_at": "2026-11-10T22:00:00Z",
      "spots": 12,
      "shift_title": "Evening meal service",
      "shift_timezone": "ET",
      "series": {
        "repeat_every": "week",
        "repeat_on": ["tue", "thu"]
      }
    }
  ]
}
```

The last Friday of every month, finishing next summer.

```json
{
  "shifts": [
    {
      "opportunity_id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
      "shift_start_at": "2026-11-27T14:00:00Z",
      "shift_end_at": "2026-11-27T17:00:00Z",
      "spots": 6,
      "series": {
        "repeat_every": "month",
        "monthly_on": { "week": "last", "day": "fri" },
        "end_date": "2027-06-30"
      }
    }
  ]
}
```

#### Response sample

```json
{
  "success": true,
  "processed": 1,
  "shifts": [],
  "series": [
    {
      "id": "7c0f3f20-6e39-4b80-bb35-7d743f0193a6",
      "opportunity_role": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
      "status": "active",
      "starts_at": "2026-11-10T19:00:00Z",
      "ends_at": null,
      "repeats": "Every week on Tue, Thu, open-ended"
    }
  ],
  "errors": {}
}
```

`shifts` is empty because no standalone shift was created: the occurrences belong to the series. One request can mix both kinds of row, and each lands in its own list.

### Behavior worth knowing

**`start_date` is an anchor, not a filter.** Ask for "every Monday starting Wednesday" and the first occurrence is the following Monday. This is how Outlook, Google Calendar and iCal behave.

**Open-ended really is open-ended.** Vome generates roughly six months now and extends the series every day after that.

**Duplicates are skipped.** Expansion checks for shifts that already exist at the same start and end on that opportunity, so running an import twice does not double the schedule.

**Large batches finish in the background.** Past roughly 200 shifts, generation is queued and the response carries `"shifts_queued": true`. The series itself exists either way.

**A rule that matches nothing is an error**, not an empty success. A Monday-only rule inside a window containing no Monday is rejected with an explanation.

### Not available here

Pre-assigning volunteers while creating. Create the series, then assign users to it, which notifies people and sets up chat the same way Vome does.
