Re Revenue lesson details ask; Delivery exposes GET /api/v1/delivery/v1/lessons as the operational read surface

Why

Delivery accepts the ask. Lesson schedule and outcome facts are Delivery-owned, and Revenue's reservation drawer should hydrate those facts through a Delivery read rather than promoting Revenue's imported lesson rows to canonical delivery state.

This should live as a Delivery-owned operational read surface for now, not as a lesson-lifecycle contract bump. The endpoint answers a workbench display question over Delivery tables. If another domain begins depending on the same read as a behavioral contract, Delivery can promote the shape into a minor lesson-lifecycle contract addition.

What

Delivery added:

GET /api/v1/delivery/v1/lessons?organization_id={org}&lesson_ids={les_1,les_2}
GET /api/v1/delivery/v1/lessons/{lesson_id}?organization_id={org}

The batch route also accepts repeated lesson_ids or lesson_ids[] query params, with a cap of 100 ids per request. Both routes are read-only and require organization_id. The response shape is:

export type DeliveryLessonDetailsResponse = {
  organization_id: string;
  as_of: string;
  lessons: Array<{
    lesson_id: string;
    organization_id: string;
    starts_at: string;
    ends_at: string | null;
    timezone: string | null;
    status: string;
    outcome: "completed" | "canceled" | "no_show" | "unresolved";
    credits_cost: number | null;
    completed_at: string | null;
    canceled_at: string | null;
    updated_at: string;
    as_of: string;
  }>;
  missing_lesson_ids: string[];
};

timezone is null until Delivery stores a separate lesson timezone. Today the timestamps are the canonical instant values. status is Delivery's source status. outcome is the drawer-friendly label Revenue asked for: Completed maps to completed, Canceled and Cancelled map to canceled, No-Show maps to no_show, and every non-terminal state maps to unresolved. credits_cost is Delivery's source-backed expected_lesson_credit_cost, the lesson credit cost used by Delivery's lesson debit path.

The implementation is intentionally schedule and outcome only. It does not include coach assignment, participant details, notes, attendance roster rows, or Revenue-owned lock and funding state.

References

• Revenue ask: 2026-05-19-revenue-delivery-lesson-details-api
• Delivery route: delivery/app/api/v1/delivery/v1/lessons/route.ts
• Delivery single-id route: delivery/app/api/v1/delivery/v1/lessons/[lessonId]/route.ts
• Delivery repo helper: delivery/modules/lesson/repo.ts