Creating Courier Events

Throughout the course of the delivery fulfillment lifecycle, there are a variety of events that can happen to a delivery to help us understand where it is at in the fulfillment process. Capturing these events is important to the ezCater fulfillment process as they can be tied to other side-effects, like communicating to our customers that their food is on the way or has arrived.

If you already had a courier assigned to a delivery and are now assigning a new courier, we automatically take care of un-assigning the previous courier

Mutation

Mutation

mutation CourierEventCreate($input: CourierEventCreateInput!) {
  courierEventCreate(input: $input) {
    clientMutationId
    delivery {
      id
    }
    userErrors {
      ... on DeliveryValidationError {
        message
        path
      }
    }
  }
}

Variables

Variables

{
  "input": {
    "clientMutationId": "your-mutation-id",
    "coordinates": {
      "latitude": 42.360081,
      "longitude": -71.058884
    },
    "courier": {
      "id": "your-courier-id",
      "firstName": "Test",
      "lastName": "Courier",
      "phone": "+15555555555",
      "vehicle": {
        "make": "Your Vehicle Make",
        "model": "Your Vehicle Model",
        "color": "Your Vehicle Color"
      }
    },
    "deliveryId": "ezcater-delivery-id",
    "eventType": "EN_ROUTE_TO_PICKUP",
    "occurredAt": "2024-02-05T17:27:55+0000"
  }
}

Arguments

Argument Name	Description
`input`: CourierEventCreateInput!	The Input object for creating a new menu.

Return Type

Returns a CourierEventCreatePayload.

Success Responses

When the courierEventCreate mutation succeeds you can expect the response payload to look like:

Response

{
  "data": {
    "courierEventCreate": {
      "clientMutationId": "your-mutation-id",
      "delivery": {
        "id": "ezcater-delivery-id"
      },
      "userErrors": []
    }
  }
}

Failure Responses

User Errors

When the courierEventCreate mutation fails because it is too early to add courier events you can expect the response payload to look like:

Response - Too Early

{
  "data": {
    "courierEventCreate": {
      "clientMutationId": "your-mutation-id",
      "delivery": null,
      "userErrors": [
        {
          "message": "It's too early to add the event for courier en route to pickup",
          "path": [
            "input",
            "occurredAt"
          ]
        }
      ]
    }
  }
}

Response - Too Late

{
  "data": {
    "courierEventCreate": {
      "clientMutationId": "your-mutation-id",
      "delivery": null,
      "userErrors": [
        {
          "message": "Delivery cannot receive updates 2 hours past its event time",
          "path": [
            "input",
            "deliveryId"
          ]
        }
      ]
    }
  }
}

400 Bad Request

When the courierEventCreate mutation fails due to bad user input, such as a invalid eventType enum or invalid field, you can expect a HTTP 400 Bad Request and the response payload to look like:

Response - Invalid Enum

{
  "errors": [
    {
      "message": "Variable \"$input\" got invalid value \"PICKEDUP\" at \"input.eventType\"; Value \"PICKEDUP\" does not exist in \"CourierEventCreateInputEventType\" enum.",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

Response - Invalid Field

{
  "errors": [
    {
      "message": "Variable \"$input\" got invalid value { clientMutationId: \"your-mutation-id\", coordinates: { latitude: 42.360081, longitude: -71.058884 }, courier: { id: \"your-courier-id\", firstName: \"Test\", lastName: \"Courier\", phone: \"+15555555555\", vehicle: [Object] }, deliveryId: \"your-ezcater-delivery-id\", eventType: \"PICKED_UP\", occurredAt: \"2025-05-07T19:52:32.841Z\" }; Field \"eventType\" is not defined by type \"CourierTrackingEventCreateInput\".",
      "extensions": {
        "code": "BAD_USER_INPUT"
      }
    }
  ]
}

Courier Event Create