Skip to main content

Dispatch Routing GraphQL

Dispatch routing GraphQL covers route statuses, reusable route templates, daily dispatch routes, route stops, and scheduled template-to-route generation.

Enums​

GraphQL enum values use PascalCase names:

  • DispatchRouteType: Delivery, Pickup
  • StatusStage: Pending, InProgress, Completed
  • DayOfWeek: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday

Queries​

query {
  dispatchRouteStatuses(organizationId: 1, search: "Pending", orderBy: "priority") {
    items { dispatchRouteStatusId statusName statusStage routeType priority color }
  }

  dispatchRouteTemplates(organizationId: 1, search: "Monday", orderBy: "name") {
    items {
      dispatchRouteTemplateId
      name
      routeType
      daysOfWeek
      enabled
      stops { dispatchRouteTemplateStopId sequence stopContactId stopType estimatedServiceMinutes }
    }
  }

  dispatchRoutes(organizationId: 1, search: "Monday", orderBy: "routeDate") {
    items {
      dispatchRouteId
      name
      routeType
      routeDate
      isDraft
      dispatchRouteStatus { statusName statusStage }
      stops { dispatchRouteStopId plannedSequence stopContactId stopType orderIds }
    }
  }
}

Template Mutations​

mutation {
  createDispatchRouteTemplate(input: {
    organizationId: 1
    values: {
      name: "Monday/Wednesday/Friday Route A"
      routeType: Delivery
      daysOfWeek: [Monday, Wednesday, Friday]
      enabled: true
      stops: [
        { stopContactId: 101, estimatedServiceMinutes: 15 }
        { stopContactId: 105, stopType: Pickup }
      ]
    }
  }) {
    dispatchRouteTemplate { dispatchRouteTemplateId stops { sequence stopType } }
  }
}

Stop maintenance uses dedicated mutations: addDispatchRouteTemplateStop, updateDispatchRouteTemplateStop, reorderDispatchRouteTemplateStop, and removeDispatchRouteTemplateStop. Dynamic template updates also accept a full replacement stops array: existing stop IDs are sparse-updated, new entries are inserted, omitted existing entries are soft-deleted, and sequences are reassigned from array order.

Route Mutations​

mutation {
  createDispatchRoute(input: {
    organizationId: 1
    values: {
      name: "Monday Delivery Run"
      routeType: Delivery
      routeDate: "2026-06-16"
      dispatchRouteStatusId: 50
      driverContactId: 1001
      equipmentId: 500
      isDraft: true
      stops: [
        { stopContactId: 101, estimatedServiceMinutes: 15, orderIds: [9001] }
        { stopContactId: 105, stopType: Pickup, estimatedServiceMinutes: 10, orderIds: [9002, 9003] }
      ]
    }
  }) {
    dispatchRoute {
      dispatchRouteId
      name
      isDraft
      stops {
        plannedSequence
        stopType
        stopContactId
        orderIds
        orders { dispatchRouteStopOrderId orderId }
      }
    }
  }
}

mutation {
  activateDispatchRoute(input: { organizationId: 1, dispatchRouteId: 200 }) {
    dispatchRoute { dispatchRouteId isDraft dispatchRouteStatus { statusName } }
  }
}

Stop maintenance uses addDispatchRouteStop, updateDispatchRouteStop, reorderDispatchRouteStop, and removeDispatchRouteStop. addDispatchRouteStop, updateDispatchRouteStop, route creation, and dynamic route updates accept orderIds on stop values. A provided orderIds list is validated against the organization and reconciles the stop's attached orders to exactly those IDs. Dynamic route updates also accept a full replacement stops array: existing stop IDs are sparse-updated, new entries are inserted, omitted existing entries are soft-deleted, and planned sequences are reassigned from array order.

Orders expose route links through relatedDispatchRoutes. Draft orders return an empty list.

query {
  orders(organizationId: 1, filter: "orderId:9001") {
    items {
      orderId
      orderNumber
      relatedDispatchRoutes(orderBy: "routeDate") {
        dispatchRouteId
        name
        routeDate
        stops {
          dispatchRouteStopId
          orderIds
        }
      }
    }
  }
}

Commodities expose route links through getRelatedDispatchRoutes(filter, orderBy). The resolver starts at the selected commodity, walks down its child commodity tree, finds all non-draft orders attached to that commodity or any descendant, and returns dispatch routes attached to those orders.

query {
  commodities(organizationId: 1, filter: "commodityId:5001") {
    items {
      commodityId
      description
      getRelatedDispatchRoutes(orderBy: "routeDate") {
        dispatchRouteId
        name
        routeDate
        stops {
          dispatchRouteStopId
          orderIds
        }
      }
    }
  }
}

Daily Generation​

mutation {
  generateDispatchRoutes(input: {
    organizationId: 1
    values: {
      routeDate: "2026-06-16"
      dispatchRouteStatusId: 10
      dispatchRouteTemplateId: 5
    }
  }) {
    generateDispatchRoutesResult {
      createdCount
      skippedCount
      createdRouteIds
    }
  }
}

Generation is idempotent per template and route date. Omit dispatchRouteTemplateId to generate from all enabled templates matching the date's day of week.