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

# Amend event

`PUT /events/{event_id}`

This endpoint is used to amend a single usage event with a given `event_id`. `event_id` refers to the
`idempotency_key` passed in during ingestion. The event will maintain its existing `event_id` after the amendment.

This endpoint will mark the existing event as ignored, and Orb will only use the new event passed in the body of
this request as the source of truth for that `event_id`. Note that a single event can be amended any number of
times, so the same event can be overwritten in subsequent calls to this endpoint. Only a single event with a given
`event_id` will be considered the source of truth at any given time.

This is a powerful and audit-safe mechanism to retroactively update a single event in cases where you need to:
* update an event with new metadata as you iterate on your pricing model
* update an event based on the result of an external API call (e.g. call to a payment gateway succeeded or failed)

This amendment API is always audit-safe. The process will still retain the original 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
* The `timestamp` of the new event must match the `timestamp` of the existing event already ingested. As with
  ingestion, all timestamps must be sent in ISO8601 format with UTC timezone offset.
* The `customer_id` or `external_customer_id` of the new event must match the `customer_id` or
  `external_customer_id` of the existing event already ingested. Exactly one of `customer_id` and
  `external_customer_id` should be specified, and similar to ingestion, the ID must identify a Customer resource
  within Orb. Unlike ingestion, for event amendment, we strictly enforce that the Customer must be in the Orb
  system, even during the initial integration period. We do not allow updating the `Customer` an event is
  associated with.
* 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 amendment 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.
* By default, no more than 100 events can be amended 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

## Request body

- AmendedEvent
  - `customer_id` string, nullable — The Orb Customer identifier
  - `external_customer_id` string, nullable — An alias for the Orb customer, whose mapping is specified when creating the customer
  - `event_name` string, required — A name to meaningfully identify the action or event type.
  - `timestamp` string, date-time, required — An ISO 8601 format date with no timezone offset (i.e. UTC). This should represent the time that usage was recorded, and is particularly important to attribute usage to a given billing period.
  - `properties` object, required — A dictionary of custom properties. Values in this dictionary must be numeric, boolean, or strings. Nested dictionaries are disallowed.

## Response `200`

OK

- AmendEventResult
  - `amended` string, required — event_id of the amended event, if successfully ingested

## 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/orbcorp/apis/api-reference.md) · [All operations](https://skmtc.dev/orbcorp/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/orbcorp/api-reference/revisions/2580a0ee8d4c/schema)