# Enrichments

> What an enrichment is, how one transaction accumulates several of them through refreshes, and the three operations that create and read them.

An enrichment is the settled result of a call: a merchant identity (or its absence), a status, and what the call cost. It is identified by an `enrichment_id` shaped `enr_<uuid>`, and its content remains readable for 90 days.

## One transaction, one or more enrichments

A transaction, identified by your `external_transaction_id`, starts with a first enrichment. Each refresh adds a **new** enrichment, with its own `enrichment_id`; it never overwrites the previous one.

```text
tx_8f21c0 (your external_transaction_id)
├── enr_ffe8…  create     resolved              ← current result to begin with
└── enr_dd42…  refresh    refresh_recalculated  ← becomes the current result
```

At any time, the transaction has a **current result**: the first one, replaced only by a refresh that succeeds (`refresh_recalculated`). That is what sending the same transaction again returns through deduplication. Each `enrichment_id`, for its part, keeps designating its own result. See [Lifecycle](https://developer.noryo.app/en-GB/merchant/enrichments/lifecycle).

An enrichment created with an `Idempotency-Key` alone, without an `external_transaction_id`, exists and can be read, but it is attached to no transaction: it is not deduplicated and cannot be refreshed.

## The three operations

| Operation | Scope | Cost | Page |
|---|---|---|---|
| `POST /merchant/v1/enrichments` | `enrich:write` | 1 unit if `resolved` | [Create an enrichment](https://developer.noryo.app/en-GB/merchant/enrichments/create) |
| `GET /merchant/v1/enrichments/{enrichment_id}` | `enrich:read` | never billed | [Read an enrichment](https://developer.noryo.app/en-GB/merchant/enrichments/read) |
| `POST /merchant/v1/enrichments/{enrichment_id}/refresh` | `enrich:write` | 1 unit if `refresh_recalculated` | [Refresh](https://developer.noryo.app/en-GB/merchant/refresh) |

Each one consumes a rate-limit token. The complete schemas are in the [API reference](https://developer.noryo.app/en-GB/merchant/reference).

## Key points

- A `200` is a settled result, not necessarily a merchant found: read `enrichment.status`. See [Statuses](https://developer.noryo.app/en-GB/merchant/enrichments/statuses).
- An enrichment belongs to the workspace and environment that created it; any key of that workspace and environment can read it.
- The content expires after 90 days; the identity, the ledger line and the accounting record survive. See [Retention and 410](https://developer.noryo.app/en-GB/merchant/retention).

## In this section

- [Create an enrichment](https://developer.noryo.app/en-GB/merchant/enrichments/create)
- [Read an enrichment](https://developer.noryo.app/en-GB/merchant/enrichments/read)
- [Refresh](https://developer.noryo.app/en-GB/merchant/refresh)
- [Statuses](https://developer.noryo.app/en-GB/merchant/enrichments/statuses)
- [Lifecycle](https://developer.noryo.app/en-GB/merchant/enrichments/lifecycle)
- [Retention and 410](https://developer.noryo.app/en-GB/merchant/retention)

---

Canonical page: https://developer.noryo.app/en-GB/merchant/enrichments