Appointment Window vs. Planned Window — API Field Reference
Shipwell shipment stops have two distinct sets of date/time fields: the planned window (the scheduled plan) and the appointment window (the confirmed appointment). This article explains both and provides the correct API field paths for integrations.
Planned Window Fields
These represent the planned/expected date and time for a stop — not a confirmed appointment.
Field | API Path | Type |
Planned date |
| date (YYYY-MM-DD) |
Planned window start |
| datetime (ISO 8601) |
Planned window end |
| datetime (ISO 8601) |
Display planned window |
| string (pre-formatted) |
Appointment Window Fields (Confirmed Appointment)
These represent the confirmed appointment slot set by the facility or user. These fields are null until an appointment is confirmed on the stop.
Field | API Path | Type |
Appointment start |
| datetime (ISO 8601, UTC) |
Appointment end |
| datetime (ISO 8601, UTC) |
Appointment type |
| enum: OPEN, BY_APPT, NOTICE_CALL, SPECIAL_INSTRUCTIONS |
Appointment needed flag |
| boolean |
Stop Index Reference
Stop 1 (pickup):
stops[0]Stop 2 (delivery):
stops[1]
Important: Null Handling
The appointment_window.start and appointment_window.end fields will be null if no appointment has been confirmed. Your integration must handle null values gracefully — consider falling back to the planned window when the appointment window is null.
Timezone Handling
Appointment window values are returned in UTC. To convert to local time, use the stop timezone available at: stops[n].location.address.timezone
Building a Combined Display String
The display_planned_window field returns a pre-formatted string. The appointment_window fields return separate start and end datetime values that you must concatenate in your integration layer. Example format: "05/30/2026 14:00 - 16:00" — format each datetime, then join with " - ".