Report the shift result

Introduction

You know what happened to a shift. HyperTrack sees only location. When a shift ends or changes, call complete or cancel on the order, and send what happened. If you learn more later, send it with PATCH or cancel.

HyperTrack uses this result to measure worker reliability and to train the no-show model for your account (see ML based NCNS Score).

The status is the result

The order status tells HyperTrack if the shift occurred.

Complete carries the timesheets and the metadata. Cancel carries a cancellation_reason, and timesheets when the worker came to the site.

If a call gets a 5xx response, send it again. If the repeated call gets 409 because the order already has the new status, the first call was successful.

Cancellation reasons

cancellation_reason tells why the shift did not occur as planned. You can send it on cancel, and on PATCH of a cancelled order.

The client is the business that books the worker. More values can be added later.

Fields

Timesheets

timesheets is the same list of timesheet entries that POST /orders/track accepts. Each entry has a type:

• system: the times from your system, for example the clock-in and clock-out of the worker
• worker: the times that the worker reported
• client: the times that the client reported or approved
• reconciled: the final times that HyperTrack AI creates from all inputs

For all fields of an entry, see the request body of complete.

Rules:

• A write replaces your full list. To add or correct one entry, send the full list again.
• The HyperTrack location entry ("source": "hypertrack-location") stays. You cannot change it.
• When your list changes, HyperTrack sends the Timesheet Updated webhook.

Metadata

On complete and cancel, metadata is a shallow merge. The keys that you send overwrite the stored keys. The keys that you do not send stay.

On PATCH, metadata replaces the full stored object. To keep a key, send it again.

Examples

The examples show the request body. Send each request to https://v3.api.hypertrack.com with your usual authentication.

The worker came and worked

Complete the order with the times from your system and your own metadata.

{
  "timesheets": [
    {
      "type": "system",
      "start_time": "2026-10-14T14:58:00Z",
      "end_time": "2026-10-14T23:02:00Z",
      "breaks": [
        { "start_time": "2026-10-14T18:00:00Z", "end_time": "2026-10-14T18:30:00Z", "type": "meal" }
      ]
    }
  ],
  "metadata": { "supervisor": "D. Chen", "pay_hours": 8.0, "pay_rate": 22.5, "shift_id": "S-55120" }
}

No-show, and the shift was reassigned

When you give the shift to a new worker, create a new order and cancel the old one with no_show. Put the handle of the new order in the metadata of the old order, for example replacement_order_handle. This key ties the replacement order back to the order that it replaces. HyperTrack does not read or validate this key. It is your own metadata key.

{
  "cancellation_reason": "no_show",
  "metadata": { "replacement_order_handle": "ORD-88213", "note": "no contact after 2 calls" }
}

The worker called off on the morning of the shift

Use metadata to send more detail about what happened, for example your own reason code.

{
  "cancellation_reason": "worker_cancelled",
  "metadata": { "reason_code": "sick" }
}

The worker came and was sent home

Cancel with client_cancelled, and send the time that the worker was on site.

{
  "cancellation_reason": "client_cancelled",
  "timesheets": [
    { "type": "system", "start_time": "2026-10-14T14:57:00Z", "end_time": "2026-10-14T15:20:00Z" }
  ]
}

The reason is known only the next day

The order is already cancelled. Add the reason with PATCH.

{ "cancellation_reason": "no_show" }

The client approved a corrected timesheet the next day

The list replaces the stored list, so send the system entry again.

{
  "timesheets": [
    { "type": "system", "start_time": "2026-10-14T14:58:00Z", "end_time": "2026-10-14T23:02:00Z" },
    {
      "type": "client",
      "start_time": "2026-10-14T15:00:00Z",
      "end_time": "2026-10-14T22:45:00Z",
      "approved_at": "2026-10-15T09:12:00Z"
    }
  ]
}

A completed order did not occur

The order was completed in error. The next day you learn that the worker did not come. Call cancel on the completed order with a reason. The status changes to cancelled (see Cancel a completed order).

{
  "cancellation_reason": "no_show",
  "metadata": { "note": "worker did not show, completed in error" }
}

Cancel a completed order

When you learn later that a completed shift did not occur, make a second call: call cancel on the completed order.

• Send a cancellation_reason. Without it, the response is 409.
• Send the cancel not more than 7 days after the order was completed. After 7 days, the response is 409.
• The status changes from completed to cancelled.
• You received the Order Completed webhook when the order was completed. Now you also get the Order Cancelled webhook for the same order. Your webhook handler must accept a change from completed to cancelled.
• In the dashboard, the order moves from the completed count to the cancelled count.

Webhooks

Related

• ML based NCNS Score
• No Show Detection
• Pre-shift and On-shift tracking