Enrichments

An enrichment is the settled result of a call: a merchant identity (or its absence), a status, and what the call cost. It is identified by an enrichment_id shaped enr_<uuid>, and its content remains readable for 90 days.

One transaction, one or more enrichments

A transaction, identified by your external_transaction_id, starts with a first enrichment. Each refresh adds a new enrichment, with its own enrichment_id; it never overwrites the previous one.

tx_8f21c0 (your external_transaction_id)
├── enr_ffe8…  create     resolved              ← current result to begin with
└── enr_dd42…  refresh    refresh_recalculated  ← becomes the current result

At any time, the transaction has a current result: the first one, replaced only by a refresh that succeeds (refresh_recalculated). That is what sending the same transaction again returns through deduplication. Each enrichment_id, for its part, keeps designating its own result. See Lifecycle.

An enrichment created with an Idempotency-Key alone, without an external_transaction_id, exists and can be read, but it is attached to no transaction: it is not deduplicated and cannot be refreshed.

The three operations

Each one consumes a rate-limit token. The complete schemas are in the API reference.

Key points

• A 200 is a settled result, not necessarily a merchant found: read enrichment.status. See Statuses.
• An enrichment belongs to the workspace and environment that created it; any key of that workspace and environment can read it.
• The content expires after 90 days; the identity, the ledger line and the accounting record survive. See Retention and 410.

In this section

• Create an enrichment
• Read an enrichment
• Refresh
• Statuses
• Lifecycle
• Retention and 410