My Availability (Vendor)

Executive summary

My Availability is the Clover-style weekly grid at /dashboard/orders/shifts. Staff pick Preferred or Unavailable windows (or all-day), apply them to all locations or one store, and Notify manager when the template is ready. The legacy POS work-shift history list remains at /dashboard/orders/shifts/v1.

Pass timezone (store dashboard_prefs.timezone) so effective_on and “today” match the store calendar.

Domain model

Table	Purpose
vendor_availability_templates	One repeating week per actor (vendor_id + optional vendor_employee_id) and store. effective_on (date), status (unsubmitted / submitted).
vendor_availability_slots	Windows on a template: weekday (0 = Sunday … 6 = Saturday), kind (preferred / unavailable), all_day, start_time / end_time (HH:mm), apply_to (all / store). Optional shift_template_id links the window to a work-shift template schedule (then template_id is null).
vendor_availability_slot_breaks	Planned paid/unpaid breaks on a slot (kind, start_time, end_time, duration_minutes) — timecard-compatible.

Owners store templates with vendor_employee_id = null. Employees are scoped to vendor.sub. Overlapping windows on the same weekday return 400.

Planned breaks on a slot (vendor_availability_slot_breaks) use the same paid/unpaid HH:mm shape as time-card breaks so schedule windows can convert into attendance / published schedule without inventing times.

Slot and break time fields in vendor-web use the shared DashboardTimeField (HH:mm value, h:mm aa display) — the same control as the HR time card — so availability and timesheet pickers stay one implementation.

API

All routes require a vendor JWT (/api/v1/vendor/availability). store_id is required.

Method	Path	Purpose
GET	/vendor/availability	Current template, slot list, actor name/image, and other templates (template_id, timezone query). Pass shift_template_id instead to list weekday windows for a shift template.
POST	/vendor/availability/templates	New template (effective_on defaults to today in timezone)
POST	/vendor/availability/templates/:id/clear	Delete all slots; status back to unsubmitted
POST	/vendor/availability/templates/:id/notify	Notify manager — set submitted
POST	/vendor/availability/slots/bulk	Bulk upsert by weekdays[]: update existing weekday window, create missing (max 7 unique weekdays). Preferred for the schedule modal.
POST	/vendor/availability/slots	Add a single window (creates a template if none exists). With shift_template_id, upserts that weekday on the shift-template schedule (one slot per weekday).
PATCH	/vendor/availability/slots/:id	Update a window. Shift-template slots keep template_id null (column is nullable).
DELETE	/vendor/availability/slots/:id	Remove a window (store_id query)

UI

The week grid matches the Clover layout (24 hour columns × half-hour cells).

• Empty week: a purple Add Availability bar always spans today’s weekday. Hover (or keyboard-focus) any other empty weekday to reveal the same bar. Plus on a day row still opens the add dialog.
• Filled week: saved windows render as two-line bars (Preferred All Day / Preferred 9:00am - 6:00pm plus All Locations or the store name) with a lavender fill (#f1ecff) for preferred and gray (#ebe9ef) for unavailable. Hover an empty weekday to reveal Add Availability. Empty hour cells on days that already have windows are not clickable; click the bar to edit or plus to add.
• The add dialog is Preferred / Unavailable, All day, start/end time, Apply to weekday pills (same pattern as the timesheet shift modal), optional location (employee availability only), and a Breaks section (paid/unpaid start–end rows, same UX as the time card) persisted with the slot.
• Saving with multiple weekdays calls POST /slots/bulk: one window per selected weekday (update if that day already has a slot, otherwise create), including the shared breaks payload. A shift template keeps at most 7 weekday slots (no duplicates).
• On a shift template detail page (/dashboard/orders/shifts/:id), Effective on PATCHes vendor_shift_templates.effective_on immediately (first store-calendar day the template applies — Timesheet materialize / template chips skip earlier dates). Schedule windows save from the slot modal; Members persist on each checkbox / select-all toggle. Header Save shift / Delete shift (availability notify/clear) stay hidden.