---
title: "Deprecate event"
method: PUT
path: "/events/{event_id}/deprecate"
tags: ["Event"]
---

# Deprecate event

`PUT /events/{event_id}/deprecate`

This endpoint is used to deprecate a single usage event with a given `event_id`. `event_id` refers to the
`idempotency_key` passed in during ingestion.

This endpoint will mark the existing event as ignored. Note that if you attempt to re-ingest an event with the same
`event_id` as a deprecated event, Orb will return an error.

This is a powerful and audit-safe mechanism to retroactively deprecate a single event in cases where you need to:
* no longer bill for an event that was improperly reported
* no longer bill for an event based on the result of an external API call (e.g. call to a payment gateway failed and
  the user should not be billed)

If you want to only change specific properties of an event, but keep the event as part of the billing calculation,
use the [Amend event](amend-event) endpoint instead.

This API is always audit-safe. The process will still retain the deprecated event, though it will be ignored for
billing calculations. For auditing and data fidelity purposes, Orb never overwrites or permanently deletes ingested
usage data.

## Request validation
* Orb does not accept an `idempotency_key` with the event in this endpoint, since this request is by design
  idempotent. On retryable errors, you should retry the request and assume the deprecation operation has not
  succeeded until receipt of a 2xx.
* The event's `timestamp` must fall within the customer's current subscription's billing period, or within the
  grace period of the customer's current subscription's previous billing period. Orb does not allow deprecating
  events for billing periods that have already invoiced customers.
* The `customer_id` or the `external_customer_id` of the original event ingestion request must identify a Customer
  resource within Orb, even if this event was ingested during the initial integration period. We do not allow
  deprecating events for customers not in the Orb system.
* By default, no more than 100 events can be deprecated for a single customer in a 100 day period. For higher volume
  updates, consider using the [event backfill](create-backfill) endpoint.

## Path parameters

- `event_id` string, required

## Response `200`

OK

- DeprecatedEventResult
  - `deprecated` string, required — event_id of the deprecated event, if successfully updated

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/withorb/apis/api-reference.md) · [All operations](https://skmtc.dev/withorb/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withorb/api-reference/revisions/816dfe734e2e/schema)