# Scheduled Widget Updates: Send an iPhone Widget's Changes Ahead

> Send a widget's future states in one request, each with the time it applies, and every iPhone and Apple Watch that shows it switches to each one on time by itself.

Source: https://docs.getaivi.app/guides/scheduled-updates/

When you know what a widget should say later, you don’t have to be there to say it. One request can carry the widget’s future states, each with the time it applies, and every device that shows the widget switches to each state on time by itself: no further requests from you, and no push for each change. This guide sends a week of reminders in one request, then covers how the entries combine, the limits, and how to change a schedule later.

Scheduled updates work on the [Status](https://docs.getaivi.app/widget-templates/#status-template), [Gauge](https://docs.getaivi.app/widget-templates/#gauge-template), [Countdown](https://docs.getaivi.app/widget-templates/#countdown-template), [Progress](https://docs.getaivi.app/widget-templates/#progress-template) and [List](https://docs.getaivi.app/widget-templates/#list-template) templates, on the iPhone and on the Apple Watch. Devices need Aivi 2.5 or later to switch on time; older versions show the scheduled state the next time the widget refreshes.

## Send a schedule

A Status widget called Bin day says when the next collection is. Create it in the app’s **Widgets** tab with the **Status** template and the slug `bin-day`. Sent on a Wednesday, this one request carries the whole next week: the reminder the evening before, the morning of the collection, then the next bin.

```bash
curl https://api.getaivi.app/widgets/bin-day \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  --data-binary @- << 'EOF'
{
  "content": {
    "template": "status",
    "value": { "value": "Thursday" },
    "state": { "value": "Paper & cardboard", "text_color": "blue" },
    "icon": { "name": "trash.fill", "primary_color": "blue" }
  },
  "schedule": [
    {
      "at": "2026-11-18T18:00:00+01:00",
      "content": {
        "value": { "value": "Tonight" },
        "state": { "value": "Put the paper bin out", "text_color": "orange" },
        "icon": { "primary_color": "orange" }
      }
    },
    {
      "at": "2026-11-19T06:00:00+01:00",
      "content": {
        "value": { "value": "Today" },
        "state": { "value": "Paper · from 07:00", "text_color": "green" },
        "icon": { "name": "truck.box.fill", "primary_color": "green" }
      }
    },
    {
      "at": "2026-11-19T12:00:00+01:00",
      "content": {
        "value": { "value": "Monday" },
        "state": { "value": "Glass & metal next", "text_color": "teal" },
        "icon": { "name": "trash.fill", "primary_color": "teal" }
      }
    },
    {
      "at": "2026-11-22T18:00:00+01:00",
      "content": {
        "value": { "value": "Tonight" },
        "state": { "value": "Put the glass bin out", "text_color": "orange" },
        "icon": { "primary_color": "orange" }
      }
    },
    {
      "at": "2026-11-23T06:00:00+01:00",
      "content": {
        "value": { "value": "Today" },
        "state": { "value": "Glass · from 07:00", "text_color": "green" },
        "icon": { "name": "truck.box.fill", "primary_color": "green" }
      }
    }
  ]
}
EOF
```

`content` is what the widget shows now. `schedule` is what changes, and when.

## How entries apply

Each entry has a time, `at`, and a `content` that is a [JSON Merge Patch](https://www.rfc-editor.org/rfc/rfc7396): only the fields that change.

- **Entries build on each other in time order.** Each one applies on top of the state before it, starting from `content`. In the example, the Sunday entry changes the icon’s color only, so it keeps the `trash.fill` symbol the Thursday 12:00 entry set.
- **Objects merge key by key.** `"icon": { "primary_color": "orange" }` changes the color and keeps the symbol.
- **`null` removes a field, and arrays replace whole.** A List entry that sends `rows` replaces every row.
- **Every state must be valid content.** Each state the entries produce is checked against the template’s schema and the 4 KiB limit, just like `content`. When an entry creates an object the state doesn’t have yet, give its required fields: for example `name` when `icon` was a plain string.
- **Every key must take effect.** A key the template doesn’t have, or one it would ignore (a segmented bar’s `color`), is refused instead of being dropped quietly.
- **The template stays the same.** An entry can’t change `template`, or a Progress bar’s `style`.

## Times and limits

- `at` is an ISO 8601 time with an offset or `Z`, such as `2026-11-18T18:00:00+01:00`. Unix timestamps and times with no offset are refused. Fractions of a second are dropped.
- Times must be strictly increasing and at least 5 minutes apart, and none more than 366 days ahead.
- Up to 48 entries, and 16 KiB for the whole schedule as compact JSON.
- Times that have already passed are fine. An entry that is due when the request arrives is applied at once and becomes part of the stored content. Every entry is checked either way, so whether a request is accepted never depends on when it arrives.

A schedule that breaks a rule is refused with a `422`, and nothing is stored. The error’s `loc` points into the entry, for example `["body", "schedule", 2, "content", "value"]`. A schedule sent to a template that doesn’t support one is refused with a message naming the template; `null` or `[]` is accepted on every template, so a generic client can always send the field. See [Errors](https://docs.getaivi.app/api-reference/#errors).

## The response

The `200` returns what the widget shows now, with every entry that is already due applied, and the entries still ahead in `schedule`. Times come back in UTC (`2026-11-18T18:00:00+01:00` is returned as `2026-11-18T17:00:00Z`), and each patch comes back as the template stores it, so a Gauge’s `30` reads `30.0`. When nothing is left ahead, the response has no `schedule` key.

## Changing or clearing a schedule

- **Leave `schedule` out to keep it.** An update with only `content` keeps the entries still ahead, and they apply on top of your new content. Entries that were already due are replaced by it. If a kept entry no longer fits the new content, for example because it changes a field you removed, that entry is dropped and the others stay; the response’s `schedule` shows what’s left.
- **A scheduled change wins when it comes due.** It overrides the fields it names until your next update.
- **Send an array to replace the schedule**, or `null` or `[]` to clear it.
- **Changing the widget’s template in the app clears its schedule.**

Every request that sends a schedule, or reaches a widget that has one, is stored and pushed, even when the content is unchanged. To change only the schedule, send the same `content` with the new `schedule`.

## On the device

Each device receives the schedule with the widget and lays out every future state in advance, so it switches on time without a push, without a network connection at that moment, and without the Aivi app being opened. An entry coming due sends no push and needs no reload.

- **Staleness counts from the latest change.** With [`stale_after`](https://docs.getaivi.app/concepts/how-it-works/#marking-content-as-stale) set, the age counts from your last update or the last entry that came due, whichever is later. Set it longer than the longest gap between your entries, or the widget is marked stale in between.
- **Shared widgets switch too.** Devices you’ve shared the widget with receive the schedule and switch on time as well. An invitation preview shows only what the widget says now.
- **Preview what’s coming.** On iPhone and iPad, tap the widget on its detail screen to open it in fullscreen. When a schedule is set, a clock button there lets you scrub through the upcoming states. Only the widget’s owner sees it.
