Migrating from v1 to v3

What changed in v3

• Unified auth model: OAuth2 client credentials for backend integrations and dashboard-issued JWTs/API keys/public client IDs for web flows.
• Expanded linking: Any service can be linked to any location and resource; scope is enforced by IDs instead of global vs location-only services.
• Timezones stored in UTC: Appointments are persisted in UTC to support cross-timezone bookings and multi-day flows.
• Richer availability: GET /v3/availability returns both availableTimes and availableDays, with optional external calendar sync and round robin controls.
• Auditable lifecycle: Holds (IN), reserved holds (RS), booked (BK), rescheduled placeholders (RE), and cancelled (CN) states are explicit.

Endpoint parity and callouts

• The v3 reference highlights any behavioral changes with callouts on each endpoint. If an endpoint is unchanged (for example, GET /v3/appointments), the v3 path retains v1 behavior but uses the v3 authentication headers.
• Validation is stricter in v3. Always fetch availability first, then use those IDs/timestamps when creating or rescheduling appointments.

OnSched.js upgrades

• Swap the script tag to the v3 version and adjust any renamed properties according to the component docs. Core booking flow logic remains the same; availability + appointment endpoints back the widgets.

Migration checklist

1. Inventory credentials: Create v3 client credentials (OAuth2) and API keys/public client IDs in the dashboard. Do not reuse v1 secrets.
2. Update callers: Point hosts to https://v3.onsched.com (or api-stage.onsched.com for staging) and apply the new header model (Authorization + x-api-key + optional x-client-id).
3. Verify availability/booking: Run GET /v3/availability for a known service/location and book it via POST /v3/appointment or POST /v3/appointment/hold followed by PUT /v3/appointment/:id/book.
4. Handle statuses: Expect holds to expire (IN), reserved holds to persist (RS), and reschedules to leave an RE record behind for audit history.
5. Migrate data (optional): If you need existing v1 companies, services, resources, or appointments copied into v3, contact OnSched support with the v1 company IDs to schedule a migration.

With these updates in place, your v1 integration should transition smoothly to the v3 API and widgets.