# Enrichment

> Every field of the Enrichment object returned by create and refresh, and of the stored result returned by a read: type, presence, possible values.

The `Enrichment` object is the `200` response of `POST /merchant/v1/enrichments` and `POST …/refresh`. The `GET` read returns the same structure, with `usage` replaced by `retrieval` and `original`.

## Top-level fields

| Field | Type | Presence | Description |
|---|---|---|---|
| `enrichment_id` | string | always | Public identity of the result, `enr_<uuid>`. New on each refresh. |
| `merchant` | object or `null` | always | The merchant identity. `null` when the status is `not_found`. See [Merchant](https://developer.noryo.app/en-GB/merchant/models/merchant). |
| `enrichment` | object | always | The verdict: status, reason, environment |
| `usage` | object | create and refresh | What **this call** cost |
| `retrieval` | object | `GET` read only | What **this read** costs |
| `original` | object | `GET` read only | What the enrichment cost when it happened |

## `enrichment`

| Field | Type | Values |
|---|---|---|
| `status` | string | `resolved`, `partial`, `not_found`, `refresh_recalculated`. See [Statuses](https://developer.noryo.app/en-GB/merchant/enrichments/statuses). |
| `reason` | string or `null` | `null` for `resolved` and `refresh_recalculated`; otherwise a value from the closed list (`no_usable_merchant_identity`, `missing_required_fields`, `confidence_below_threshold`, …) |
| `environment` | string | `sandbox` or `production`, the environment of the key that created the result |
| `source` | string | The origin of the result. Currently always `noryo`. |
| `customized` | boolean | Flags a customised result. Currently always `false`. |

## `usage` (create and refresh)

| Field | Type | Description |
|---|---|---|
| `billable` | boolean | The call is billed. Always `false` in Sandbox, and on a replay by `external_transaction_id`. |
| `units` | integer | 1 for `resolved` and `refresh_recalculated`, 0 otherwise; 0 on a replay by `external_transaction_id` |
| `deduplicated` | boolean | `true` if the response comes from economic deduplication |
| `deduplicated_by` | string or `null` | `external_transaction_id` when `deduplicated` is `true`, `null` otherwise |

> **Warning** A replay by `Idempotency-Key` (`Noryo-Idempotency-Replayed: true`) returns the memorised body unchanged, `usage` included. That `usage` describes the original call, not the replay, which is not billed.

## `retrieval` and `original` (read)

| Field | Type | Description |
|---|---|---|
| `retrieval.billable` | boolean | Always `false` |
| `retrieval.units` | integer | Always `0` |
| `original.billable` | boolean | The original call was billed |
| `original.units` | integer | The units of the original call |

## Examples

A `partial` result in Production:

```json
{
  "enrichment_id": "enr_3b9c2a71-8f0e-4d6a-9c5b-1e2f3a4b5c6d",
  "merchant": { "name": "Enseigne", "category": "alimentation.restaurant", "location": null, "confidence": 0.62 },
  "enrichment": { "status": "partial", "reason": "confidence_below_threshold", "environment": "production", "source": "noryo", "customized": false },
  "usage": { "billable": false, "units": 0, "deduplicated": false, "deduplicated_by": null }
}
```

A replay by `external_transaction_id`:

```json
{
  "enrichment_id": "enr_ffe80956-cc3e-4e1f-b4b6-724ad231fbb7",
  "merchant": { "name": "McDonald's", "category": "alimentation.restaurant", "location": { "city": "PARIS", "postal_code": "75018" }, "confidence": 0.96 },
  "enrichment": { "status": "resolved", "reason": null, "environment": "production", "source": "noryo", "customized": false },
  "usage": { "billable": false, "units": 0, "deduplicated": true, "deduplicated_by": "external_transaction_id" }
}
```

These two examples illustrate the shape; their values do not come from real calls.

---

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