Skip to main content

Cancel Service

In this guide, we will schedule cancellation of service for a monitorable, choose a cancel date, and remove a scheduled cancellation when needed.

Overview​

Cancellation is always scheduled. Calling cancel sets cancelledAt on the monitorable to the time when cancellation will take effect. When that time arrives, systemStatus becomes CANCELLED. That state is terminal — events can no longer be created, and cancellation cannot be undone after it has executed.

When cancellation executes, any active system status override (for example CUSTOMER_TEST) is expired, and any future system statuses are deleted. See Monitorable Lifecycle.

Getting Started​

You need a partner application with the monitorable:write scope. If you haven't created an application yet, see the Create Application guide.

Once you have your application credentials, use the Set Access Token button in the navbar to configure your access token for making API requests.

The monitorable must already have an active system status (not INACTIVE) and must not already be scheduled for cancellation.

Default: End of Month​

Send a POST request to the /monitorables/:monitorableId/cancel endpoint with an empty body (or omit cancelAt). Hyperion schedules cancellation for the end of the current UTC month (23:59:59.999Z on the last day of the month).

If fewer than 24 hours remain in the current UTC month, the default moves to the end of the next UTC month instead. Cancellation cannot take effect sooner than 24 hours after the request.

Example — enough time left in the month. Request made on 2024-06-10. Default cancelledAt is 2024-06-30T23:59:59.999Z.

Example — fewer than 24 hours left. Request made on 2024-06-30 at 12:00 UTC. Default cancelledAt is 2024-07-31T23:59:59.999Z.

Path parameters

cURL command

cURLPOST
curl -X POST "/v1/monitorables/:monitorableId/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

💡 Set your access token in the navbar to auto-fill the Authorization header

Response​

{
  "id": "7a60216c-5512-467a-8d70-6b5ccc7c9b7d",
  "type": "PREMISES",
  "systemStatus": "ACTIVE",
  "cancelledAt": "2024-06-30T23:59:59.999Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-06-10T14:00:00Z"
}

systemStatus stays at its current value until cancelledAt. At that time it becomes CANCELLED.

Specific Date​

Pass cancelAt as an ISO 8601 datetime to choose when cancellation takes effect:

ConstraintRule
MinimumAt least 24 hours from now — the earliest possible cancellation is 24 hours after the request
MaximumAt most 30 days (1 month) from now
cURLPOST

Values earlier than 24 hours from now return 400 with cancelAt must be at least 24 hours from now. Values more than 30 days out return 400 with cancelAt must be within 1 month from now.

Remove a Scheduled Cancellation​

If cancellation is still more than 24 hours away, you can clear it with DELETE /monitorables/:monitorableId/cancel:

cURLDELETE

On success, cancelledAt is cleared and the monitorable continues with its current systemStatus.

You cannot remove a scheduled cancellation when:

  • Nothing is scheduled (Monitorable is not scheduled for cancellation)
  • cancelledAt is within 24 hours (Scheduled cancellation is within 24 hours and cannot be removed)
  • The monitorable is already CANCELLED (Cannot remove scheduled cancellation for a cancelled monitorable)

Cancellation Timeline​

Errors​

StatusWhen
400Monitorable is INACTIVE — must have an active system status to be cancelled
400Monitorable is already scheduled for cancellation
400cancelAt is less than 24 hours from now
400cancelAt is more than 1 month from now
400Remove requested but nothing is scheduled, cancellation is within 24 hours, or monitorable is already cancelled
404Monitorable not found for the authenticated partner

After cancelledAt, cancellation is irreversible. Plan removals before the final 24-hour window.

Conclusion​

You've scheduled (or removed) cancellation of service for a monitorable. Use the end-of-month default for typical month-bound billing, or pass cancelAt when you need a specific date within the 24-hour to 30-day window.

Learn More​

API Reference​