Refresh

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

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/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:

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

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…

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.