# Models

> The objects the API receives and returns, how they fit together, and how the identifiers relate to each other: transaction, enrichment, idempotency key, attempt.

Noryo Merchant API exchanges few objects, all described in the OpenAPI contract and in the [API reference](https://developer.noryo.app/en-GB/merchant/reference). This section presents them from the integrator's point of view: what each field guarantees, when it is present, and when it is `null`.

## The map of objects

| Object | Where | Content |
|---|---|---|
| `CreateRequest` | Body of `POST /merchant/v1/enrichments` | `descriptor` and the optional economic fields, plus `external_transaction_id`. See [Formats](https://developer.noryo.app/en-GB/merchant/requests/formats). |
| `RefreshRequest` | Body of `POST …/refresh` | The six economic fields, without `external_transaction_id` |
| `Enrichment` | `200` response of both `POST` routes | `enrichment_id`, `merchant`, `enrichment`, `usage`. See [Enrichment](https://developer.noryo.app/en-GB/merchant/models/enrichment). |
| Stored result | `200` response of `GET` | `enrichment_id`, `merchant`, `enrichment`, `retrieval`, `original` |
| `Merchant` | The `merchant` field | `name`, `category`, `logo_url`, `location`, `confidence`. See [Merchant](https://developer.noryo.app/en-GB/merchant/models/merchant). |
| Location | The `merchant.location` field | `city`, `postal_code`, or `null`. See [Location](https://developer.noryo.app/en-GB/merchant/models/location). |
| `Problem` | Every error response | `type`, `title`, `status`, `code`, `detail`, `request_id`. See [Errors](https://developer.noryo.app/en-GB/merchant/error-handling). |

```text
Enrichment
├── enrichment_id
├── merchant ─────── Merchant | null
│                    ├── name, category, logo_url, confidence
│                    └── location ── { city, postal_code } | null
├── enrichment ───── status, reason, environment, source, customized
└── usage ────────── billable, units, deduplicated, deduplicated_by
```

## How the identifiers relate

Four identifiers circulate, each at its own scale:

| Identifier | Designates | Chosen by | Lifetime |
|---|---|---|---|
| `external_transaction_id` | An economic transaction | You | No expiry |
| `enrichment_id` | A frozen result | Noryo | Content readable for 90 days, identity kept |
| `Idempotency-Key` | A request and its response | You | 24 hours |
| `Noryo-Request-Id` | An HTTP attempt | Noryo | That of your logs |

How they relate:

- **A transaction has one or more enrichments**: the first one, then one per refresh. One of them is its current result. See [Lifecycle](https://developer.noryo.app/en-GB/merchant/enrichments/lifecycle).
- **An `Idempotency-Key` designates a single request** for 24 hours, hence at most one enrichment.
- **A request can give several attempts**: each retry has its own `Noryo-Request-Id`, even when it returns the memorised response.
- **An enrichment without `external_transaction_id`** belongs to no transaction: it is not deduplicated and cannot be refreshed.

## Presence rules

- `merchant` is always present: an object, or `null` when the status is `not_found`.
- `merchant.location` is always present when `merchant` is an object: an object, or `null`.
- `merchant.category` and `merchant.logo_url` are omitted when unknown.
- `enrichment.reason` is always present: a reason, or `null`.
- `usage.deduplicated_by` is always present: `external_transaction_id`, or `null`.

Write a client that ignores response fields it does not know, and that accepts an optional field being absent.

---

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