Migrating from v1 to v3

Choose your path

Not every team rewrites to native /v3/* routes on day one.

Existing integrations still calling v1-style paths (/consumer/v1/..., /setup/v1/...): Start with the v1 alias endpoints on v3 guide—swap the API host, keep your v1 bearer token and payloads, then move endpoint-by-endpoint to /v3/* when you are ready.
New integrations or a deliberate full rewrite: Use native /v3/* endpoints, OAuth2 client credentials (and x-api-key where required), following the checklist below.

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.

Availability mode mapping

V1 services: type=1 means the service uses weekly availability, while type=2 means it uses allocations.
V1 resources: recurringAvailability=true means the resource uses weekly availability, while false means it uses allocations.
Allocation migration: When a service or resource is in allocation mode, migrate both recurring allocation patterns and one-off allocation dates instead of copying weeklyAvailability.

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 (native `/v3/*` and dashboard)

Inventory credentials: Create v3 client credentials (OAuth2) and API keys/public client IDs in the dashboard. Do not reuse v1 secrets.
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).
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.
Handle statuses: Expect holds to expire (IN), reserved holds to persist (RS), and reschedules to leave an RE record behind for audit history.
Migrate data (optional): If you need existing v1 companies, locations, services, resources, customers, and appointments copied into v3 in bulk, sign in to the dashboard and use the migration API with your user session JWT: GET /v3/migration/companies (list v1 companies available to your account) and POST /v3/migration/sync (run the sync). That flow is for authenticated users matching v1 businesses by email; it is not a substitute for client-credentials API calls. Sync depends on the platform being able to reach legacy identity/company credentials—if that fails (for example IP allowlisting to Azure identity endpoints), entity import may be skipped until access is fixed; contact OnSched support in that case. For large or custom migration projects, you can still contact support with v1 company IDs.

If you are staying on the v1 compatibility layer first, use the testing and rollout guidance there, then return to this checklist when you cut specific flows over to native /v3/*.

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