# Timezones & scheduling

Schedule a post at a local wall-clock time with scheduledFor and timezone, and read back the UTC instant Zernio stores.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Schedule posts at a user's local time: send `scheduledFor` without a zone plus the `timezone` field (default `UTC`). A `Z` or an offset makes it an absolute instant.

## Schedule a post at a local time

Send the picked wall-clock time and the IANA timezone (in a browser, `Intl.DateTimeFormat().resolvedOptions().timeZone`).

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: scheduled } = await zernio.posts.createPost({
  body: {
    content: 'Good morning from the Zernio API.',
    platforms: [{ platform: 'instagram', accountId: '66b2e19d8c3f5a7e9d0b1c2d' }],
    scheduledFor: '2027-01-01T09:00:00',
    timezone: 'America/New_York',
  },
});

console.log(scheduled.post.scheduledFor);
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

scheduled = client.posts.create_post(
    content="Good morning from the Zernio API.",
    platforms=[{"platform": "instagram", "accountId": "66b2e19d8c3f5a7e9d0b1c2d"}],
    scheduled_for="2027-01-01T09:00:00",
    timezone="America/New_York",
)

print(scheduled["post"]["scheduledFor"])
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/posts" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Good morning from the Zernio API.",
    "platforms": [{ "platform": "instagram", "accountId": "66b2e19d8c3f5a7e9d0b1c2d" }],
    "scheduledFor": "2027-01-01T09:00:00",
    "timezone": "America/New_York"
  }'
```
</Tab>
</Tabs>

Response (`201`):

```json
{
  "message": "Post scheduled successfully",
  "post": {
    "_id": "65f1c0a9e2b5af0012ab34cd",
    "status": "scheduled",
    "scheduledFor": "2027-01-01T14:00:00Z",
    "timezone": "America/New_York",
    "platforms": [
      { "platform": "instagram", "status": "pending" }
    ]
  }
}
```

[Create post](/posts/create-post) reads `scheduledFor` like this:

| You send | Interpreted as |
|----------|---------------|
| `"2027-01-01T10:00:00Z"` | UTC instant; `timezone` ignored. |
| `"2027-01-01T10:00:00+01:00"` | Instant at that offset; `timezone` ignored. |
| `"2027-01-01T10:00:00"` (no zone) | Wall-clock time in the request's `timezone` (IANA name, default `UTC`). |

These 3 requests schedule the same instant:

```json
{ "scheduledFor": "2027-01-01T09:00:00Z" }
{ "scheduledFor": "2027-01-01T10:00:00+01:00" }
{ "scheduledFor": "2027-01-01T10:00:00", "timezone": "Europe/Madrid" }
```

## Schedule different times per platform

A `scheduledFor` on a `platforms[]` entry overrides the root one, and the root `timezone` applies to it. Below, LinkedIn publishes at 09:00 New York time, Instagram at 18:00.

```json
{
  "content": "Our January release notes are out.",
  "scheduledFor": "2027-01-01T09:00:00",
  "timezone": "America/New_York",
  "platforms": [
    { "platform": "linkedin", "accountId": "66b2e19d8c3f5a7e9d0b1c2d" },
    {
      "platform": "instagram",
      "accountId": "66b2e19d8c3f5a7e9d0b1c2e",
      "scheduledFor": "2027-01-01T18:00:00"
    }
  ]
}
```

An absolute override (`Z` or an offset) ignores `timezone`.

## Schedule into queue slots

A [queue](/guides/queue-scheduling) has its own `timezone`, independent of the post's. Each slot is a weekday plus a wall-clock time.

```json
{
  "profileId": "66a1f0c2a4b9d3e8f1a2b3c4",
  "name": "Evening posts",
  "timezone": "America/New_York",
  "slots": [
    { "dayOfWeek": 1, "time": "18:00" },
    { "dayOfWeek": 3, "time": "18:00" },
    { "dayOfWeek": 5, "time": "18:00" }
  ]
}
```

- **`dayOfWeek`**: `0` (Sunday) through `6` (Saturday).
- **`time`**: `HH:mm` in the queue's timezone.
- **`queuedFromProfile`**: the post takes `scheduledFor` from the next free slot; send no time.

## How it behaves

- **No `timezone` means UTC.** 10:00 picked in Madrid, sent as only `"scheduledFor": "2027-01-01T10:00:00"`, posts at 10:00 UTC (11:00 in Madrid). The usual cause of wrong-hour posts.
- **Past times** publish synchronously in the same request.
- **Responses are UTC.** `scheduledFor` and `publishedAt` return as UTC ISO 8601 with a `Z`. Convert for display.
- **Queue slots follow the wall clock.** An 18:00 New York slot stays 18:00 local all year; its UTC instant shifts an hour across DST.
- **DST days are not errors.** No gap or repeat rule: the offset comes from reading your wall-clock time as UTC, so the result can be an hour off. Send `Z` or an offset on those days.

| DST case (`timezone: "America/New_York"`) | Result |
|---|---|
| `"2027-03-14T02:30:00"` (skipped by spring-forward) | Offset at 02:30 UTC that day is `-05:00`: stores `2027-03-14T07:30:00Z`, 03:30 local. |
| `"2027-11-07T01:30:00"` (repeated by fall-back) | Applies `-04:00`: stores `2027-11-07T05:30:00Z`, the first of the two 01:30s. |

## If it fails

| Error | Cause | Fix |
|---|---|---|
| `400` on `POST /v1/posts`: `{ "error": "Invalid timezone provided" }` | `timezone` is not a known IANA name (`Europe/Madird`). Checked only when `scheduledFor` is set. Predates the error envelope: no `type` or `code`. | Send a canonical IANA name (`Europe/Madrid`, `America/New_York`). |
| `invalid_field_value` on `POST /v1/queue/slots` | Same check, enveloped: `code: "invalid_field_value"`, `param: "timezone"`. | Same fix. |

## Related

- [Queue scheduling](/guides/queue-scheduling): recurring local-time slots per profile.
- [Post lifecycle](/guides/post-lifecycle): what happens between `scheduled` and `published`.
- [Create post](/posts/create-post): every field, including per-platform `scheduledFor`.