# Core concepts

> The vocabulary of Noryo Merchant API on one page: descriptor, enrichment, economic identity, identifiers, statuses, units and environments.

This page defines the terms used throughout the documentation. Field and value names stay exactly as the API returns them.

## The descriptor and the enrichment

| Term | Definition |
|---|---|
| `descriptor` | The raw bank label, as it appears on the statement (`CB MCDONALDS PARIS 4519`). It is the only required field of a request. Noryo does not retain it. |
| Enrichment | The result of a call that was settled: a merchant identity (or the absence of one), a status, and what the call cost. |
| `enrichment_id` | The public identity of a result, shaped `enr_<uuid>`. A refresh produces a new result, hence a new `enrichment_id`; the old one keeps pointing at the old result. |
| `merchant` | The merchant identity: `name`, `category`, `logo_url`, `location`, `confidence`. It is `null` when the status is `not_found`. |

## What identifies a transaction

| Term | Definition |
|---|---|
| Economic identity | The six fields `descriptor`, `amount`, `currency`, `occurred_at`, `country` and `mcc`, compared in a canonical form. Two calls that differ only by amount are two distinct enrichments. |
| `external_transaction_id` | Your identifier for the transaction. It carries economic deduplication: the same transaction sent twice is billed once. It does not expire. |
| `Idempotency-Key` | A request header that protects the transport: a network retry replays the memorised response instead of recomputing. 24-hour window. |

The two identifiers do not replace each other. See [The two identifiers](https://developer.noryo.app/en-GB/merchant/identifiers).

## What the response says

| Term | Definition |
|---|---|
| `enrichment.status` | `resolved`, `partial`, `not_found` or `refresh_recalculated`. Read it first, before `merchant`. See [Statuses](https://developer.noryo.app/en-GB/merchant/enrichments/statuses). |
| `enrichment.reason` | A public reason from a closed list for `partial` and `not_found`, `null` otherwise. |
| `confidence` | A model confidence score between 0 and 1. It is not a calibrated probability. See [Confidence](https://developer.noryo.app/en-GB/merchant/results/confidence). |
| `usage` | What **this call** cost: `billable`, `units`, `deduplicated`, `deduplicated_by`. |
| Unit | The unit in which usage is counted. A `resolved` or `refresh_recalculated` result is 1 unit; `partial` and `not_found` are 0. |

## Who calls, and where

| Term | Definition |
|---|---|
| Organisation and workspace | An organisation groups workspaces; an API key belongs to a workspace. Results, idempotency keys and deduplication are scoped to a workspace and an environment. The Sandbox allowance is counted per organisation. |
| Environment | `sandbox` or `production`. The key prefix carries it and the server confirms it; the response repeats it in `enrichment.environment`. |
| Scopes | `enrich:read` allows reading (`GET`), `enrich:write` allows creating and refreshing. |
| `Noryo-Request-Id` | The identifier of one HTTP attempt, shaped `req_<uuid>`. It is in the header of every response and in the body of every error. |
| `code` | The machine code of a Problem Details error, for example `idempotency_key_reuse`. It is the only part of an error to build logic on. |

## What Noryo does with your input

All six economic fields enter the economic identity, but only `descriptor` currently drives resolution. In particular, `country` does not filter the answer: this is a measured choice, explained in [Reading the response](https://developer.noryo.app/en-GB/merchant/reading-the-response).

To decide whether two requests carry the same transaction, Noryo compares a canonical form rather than the bytes you sent: `descriptor` is normalised (Unicode NFC, lower case, collapsed whitespace), `occurred_at` is reduced to the second in UTC, while `currency`, `country` and `mcc` are compared verbatim. That is why `currency` and `country` must be upper case. See [Formats](https://developer.noryo.app/en-GB/merchant/requests/formats).

---

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