Skip to main content
A package slate is a proposal: every session of a package, with one supplier, at times the availability engine picked. Clients often like the plan but not one date. “Can we do Thursday instead?” is the step this guide builds. You move one session with POST /v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule. The server checks the new time against the supplier’s real calendar. On success, it returns the whole updated slate, so you can show it and then hold or book it. It builds on two guides. Read them first if you haven’t: For every field and refusal of the reschedule route, see Rescheduling a slot.
The reschedule route takes the x-api-key header alone. There is no client-plane version, so call it from your BFF, even in a flow where the client is signed in. The slate stays tied to the order item it was planned from. So if you planned it from the client’s own credit (orderId and orderItemId), and that order is PAID, the client can still book it on the client plane afterwards.

How it works

  1. Plan a stored slate. POST /availability/package-slate (or package-options) without persist: false. Only a stored slate has slotIds you can move.
  2. Show it, and let the client pick a session to move. Each slot has a slotId.
  3. Move the session. POST /suggestions/slots/{slotId}/reschedule with the new bookingStartUtc.
  4. Re-render from the response. The 200 carries the whole slate. Replace what you show with it.
  5. Hold or book the slate. Use the same slateId as before. The hold or booking picks up the new time.

Move one session

Send the new start as a UTC instant in Z form, such as 2026-07-16T20:00:00.000Z. An offset form such as …-05:00 is a 400 VALIDATION_ERROR. Only the start moves: the session keeps its length, its time zone, its place and its supplier.
Turn the client’s local choice into an instant in the slot’s bookingTz. See Time zones. To offer times that are likely to pass, search that day first with POST /availability/suppliers and use the slate supplier’s entry. See Search suppliers by availability. The reschedule checks the time again either way.

What the server checks

  • The slot still exists, and its slate is within its 24-hour window.
  • The new time is in the future.
  • The supplier works then, and no booking or blocked time is in the way.
  • No live hold covers the new time on the supplier’s calendar.
Three things it doesn’t check, so check them yourself before you send:
  • The other sessions of the slate. The server doesn’t stop two sessions from landing on the same time, or too close to travel between.
  • The package’s expiry. A session moved past the credit’s expiresAt is accepted here, then refused with 409 PACKAGE_EXPIRED when you book or convert it.
  • The plan’s cadence. A moved slate can drift from its own cadenceRrule, which still records how it was first planned.

Re-render from the response

The 200 returns the moved slot’s id and the whole slate:
(slots[] is abridged.) Replace the slate you show with this one. Don’t patch the one slot on your side: the slate’s totals changed too.
  • startTimeConsistencyPercent is worked out again.
  • totalTravelTimeMins doesn’t change: every session keeps its planned travel estimate, including the moved one.
  • cadenceSummary reflects the new times.
  • matchScore, matchComponents, matchNotes and the cadence fields keep the values from planning.
  • slots[] stays in sessionIndex order. A moved session can now fall after a later one, so sort by bookingStartUtc to show the plan in date order.
A reschedule reserves nothing. The new time is free when the call returns, but anyone can take it before you hold it.

When the move is refused

Branch on code, not on the status: nearly every refusal is a 409, and each needs a different answer.

The time isn’t free

The slate is unchanged. Ask the client for another time. SLOT_TIME_UNAVAILABLE is the usual answer. It covers a time the supplier doesn’t work, and a time a booking or blocked time is already in. It names the supplier, the time and the length, but not what’s in the way:
SLOT_HELD means a hold covers the time. SLOT_BOOKED is rare: a booking the first check didn’t see. Both carry conflicts[], naming the hold or booking in the way. See The three supplier-time conflicts.

You lost a race

SLOT_NO_LONGER_FREE means the slot or its slate was removed, or a concurrent write cancelled the move. It carries no freshSuggestions. Retry once. If it fails again, plan a new slate.

The slate went stale

A slot past its 24-hour window is SUGGESTION_EXPIRED. The response carries freshSuggestions: a new plan, worked out from the original request, in the shape of a POST /availability/package-slate response. Show its primarySlate instead of starting a new search:
(freshSuggestions is abridged.) The new slate has new ids, and the client’s earlier moves aren’t in it. Check before you show it:
  • freshSuggestions is null when no new plan could be made: for SLOT_NOT_FOUND, or when the credit it was planned from is used up, expired or cancelled.
  • freshSuggestions.primarySlate can be null too, as with status: "NO_AVAILABILITY".
In either case, plan again yourself. A past or malformed bookingStartUtc is a 400. The slot is checked first, so a past time on a stale slot gets the stale 409. The full list is in When a reschedule is refused.

Hold or book the adjusted slate

The moved slot is stored, so the same slateId now means the new times. Each of these checks the times again. A time that was free when you moved the slot may have been taken since. Moving a slot doesn’t extend the slate’s 24-hour window. resolvableUntil still counts from the original planning call, and holding the slate after then is 409 SUGGESTION_EXPIRED. See Refusals.

Move sessions before you hold, not after

A reschedule changes the slate only. A hold or booking you already made keeps its old time. Two more things follow:
  • Your own hold counts as a conflict. Moving a slot into time you hold yourself is 409 SLOT_HELD, naming your own reservationId.
  • A held slate doesn’t follow the move. Converting the hold books the old times.
So let the client finish adjusting before you hold. If they want a change after you’ve held:
  1. Release the hold: POST /holds/{reservationId}/release.
  2. Move the session.
  3. Hold the slateId again.

Adjust a slate or reschedule a booking?

To move a session that’s already booked, see Reschedule a booking.

Reference

Endpoints used in this guide

Errors and edge cases