---
title: "Update custom event metadata"
method: PUT
path: "/event-metadata"
tags: ["Event Metadata"]
---

# Update custom event metadata

`PUT /event-metadata`

## Request

- Base URL: `https://api.omnisend.com/api`
- URL: `https://api.omnisend.com/api/event-metadata`
- Auth: one of:
  - API key in header `Authorization`
  - OAuth 2
    - Client credentials
    - Token URL: `https://app.omnisend.com/oauth2/token`

Merges changes into an existing brand-custom event, identified by
`name` and `origin`. Only supplied fields are applied: omitted
metadata and omitted properties are preserved, and no property is
deleted. The type of an already explicitly-defined property cannot
change. Optional metadata fields must be omitted rather than sent as
null. The merged event is returned.

**Scopes:**
`events.write`

**Rate Limiting:**
This endpoint is rate limited to 400 requests per minute.

## Headers

- `Omnisend-Version` string, required

## Request body

- WriteEventRequest: Request body for creating (POST) or merging (PUT) a brand-custom event-metadata schema. Optional metadata fields are pointers so PUT can distinguish an omitted field (preserve the stored value) from one explicitly set to an empty string.
  - `displayName` string: Human-readable label. Required on POST; omit on PUT to keep the stored value.
  - `name` string, required: Machine-readable event name
  - `origin` string, required: Single origin the schema belongs to
  - `properties` object: Property tree keyed by property name. Required with at least one key on POST; on PUT only the keys present are merged.

## Response `200`

The merged event metadata

- WriteEventResponse: Response envelope for the POST/PUT write endpoints, echoing the stored event.
  - `event` EventItem: A single logical event with one schema variant. A logical event appears as multiple elements when its origins have different property structures (e.g. schema family omnisend vs shopify).
    - `displayName` string: Human-readable label for the event
    - `explicitlyDefined` boolean: True when the event schema was declared via the write API rather than inferred from the global lexicon or scraped traffic
    - `name` string: Machine-readable event name (e.g. "placed order")
    - `origins` string[]: List of origins that contributed to this event variant
    - `properties` object: Nested tree of properties belonging to this event variant, keyed by property name. Omitted when the request did not set includeProperties=true.

## Other responses

- `400`: Invalid request body or field values
- `401`: Authentication is missing or invalid
- `404`: Event metadata does not exist
- `409`: Event is not API-owned or a property type conflict occurred
- `410`: API version has been retired
- `429`: Rate limit exceeded
- `500`: Unexpected error occurred
- `503`: The event metadata was modified concurrently; retry the request

---

[API](https://skmtc.dev/omnisend/apis/event-metadata-api.md) - [All operations](https://skmtc.dev/omnisend/apis/event-metadata-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisend/apis/event-metadata-api/revisions/9f74e71142e6?raw)