# Refresh

> POST /merchant/v1/enrichments/{enrichment_id}/refresh recomputes a known transaction and returns a new enrichment_id. Its conditions, its billing and every possible refusal.

A refresh recomputes the merchant identity of a transaction already enriched and returns a **new `enrichment_id`**, announced in a relative `Location` header. The previous identifier keeps pointing at the previous result: a refresh adds a result, it does not overwrite one. It requires the `enrich:write` scope.

## The three conditions

1. **An `Idempotency-Key` is mandatory.** Refresh is deliberately excluded from economic deduplication: it is the one billable path with no deduplicator, and the key is its only protection against a network retry. Without it: `400 identifier_required`.
2. **The original enrichment must carry an `external_transaction_id`.** A result created with an `Idempotency-Key` alone exists and can be read, but there is nothing to recompute *against*: `409 refresh_not_available`. Read it back with `GET`, or make a new call carrying an `external_transaction_id`.
3. **The body must carry the same economic input as the transaction.** A refresh recomputes the same transaction; it is not a correction: if the input has changed, it is another transaction, and the response is `409 input_mismatch`. Since Noryo does not retain the raw descriptor, you must send it again.

## Example

```bash
curl -sS -i -X POST "https://api.noryo.app/merchant/v1/enrichments/enr_ffe80956-cc3e-4e1f-b4b6-724ad231fbb7/refresh" \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refresh-tx_demo_001-2026-10-08" \
  -d '{"descriptor":"CB MCDONALDS PARIS 4519","amount":12.40,"currency":"EUR","occurred_at":"2026-09-06T11:42:00Z","country":"FR","mcc":"5814"}'
```

```http
HTTP/1.1 200 OK
location: /merchant/v1/enrichments/enr_dd424f15-6371-4565-a4dc-8770815d48c4
noryo-idempotency-replayed: false
```

The body has the same shape as a create response; `enrichment.status` is `refresh_recalculated` when the recomputation succeeds.

## What a refresh body may **not** carry

A refresh targets the enrichment named in the URL. Sending `external_transaction_id` in the body is therefore refused:

```text
400  code: invalid_request   detail: unknown field: external_transaction_id
```

It is not a formality. Accepting both would let one call name two different economic identities, and there would be no honest answer to *which one did you pay for*. The transaction identifier is derived from the target enrichment, on the server.

## The result, and its billing

| Status of the recomputation | Billing (Production) | Becomes the transaction's current result? |
|---|---|---|
| `refresh_recalculated` | 1 unit | yes |
| `partial` | not billed | no |
| `not_found` | not billed | no |

A refresh that does not succeed never destroys the current result: it is recorded as an attempt, with its own `enrichment_id`, and what sending the transaction again returns stays what you last paid for. In Sandbox, `refresh_recalculated` consumes one unit of the allowance.

The URL may name any enrichment of the transaction, the first one or an earlier refresh: it is the transaction that is recomputed.

## What happens if…

| Situation | Response |
|---|---|
| No `Idempotency-Key` | `400 identifier_required`, detail `refresh requires an Idempotency-Key` |
| `external_transaction_id` in the body | `400 invalid_request` |
| Path identifier unknown, malformed, from another workspace or environment | `404 enrichment_not_found` |
| Original enrichment without `external_transaction_id` | `409 refresh_not_available` |
| Economic input different from the transaction's | `409 input_mismatch` |
| Same `Idempotency-Key` and same request, within 24 hours | `200`, replay of the memorised response, `Noryo-Idempotency-Replayed: true` |
| Same `Idempotency-Key` already used for another request (a create call, for example) | `409 idempotency_key_reuse` |
| Engine unavailable | `503 engine_error`, nothing billed or memorised: retry with the same key |
| Sandbox allowance exhausted | `402 sandbox_quota_exhausted` |

## After expiry

When a result's content has passed its 90-day retention, the transaction is still known. A refresh with the same economic input recomputes it and produces a new readable result; it is billed if it succeeds. See [Retention and 410](https://developer.noryo.app/en-GB/merchant/retention).

---

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