Handle timezones and UTC correctly
Store unambiguous instants while presenting schedules in the brand's expected local time.
Send publish_at as an ISO-8601 timestamp with an offset or Z suffix, store it as UTC, and display it in the brand timezone. Preserve the timezone name for calendar interpretation and daylight-saving changes rather than storing only a numeric offset.
What this means in practice
Send publish_at as an ISO-8601 timestamp with an offset or Z suffix, store it as UTC, and display it in the brand timezone. Preserve the timezone name for calendar interpretation and daylight-saving changes rather than storing only a numeric offset.
Use the documented brand and account boundaries consistently across the scheduler, REST API, SDK, MCP tools, SSE consumers, and webhooks. That makes the same social operation explainable to an operator and reproducible by an integration.
Implementation checklist
Set an IANA timezone such as America/New_York on the brand.
Convert a user's local date and time into an offset-aware ISO instant.
Display the resolved local time, UTC time, and timezone near final confirmation.
Recompute future recurring plans in the owning CRM; App9 Post V1 schedules one-time instants.
Test daylight-saving boundaries and ambiguous or nonexistent local times.
Operational details
A UTC instant does not preserve the user's original calendar intent by itself, so the brand timezone remains useful context.
Drag-to-reschedule operates in the displayed brand timezone before saving a new UTC instant.
Provider dashboards can display a different timezone without changing the scheduled instant.
Common mistakes to avoid
- Do not submit a local timestamp without an offset.
- Do not treat a fixed -05:00 offset as equivalent to America/New_York all year.
- Do not compare formatted local strings when determining whether a target is due.