Compatibility
What a client can rely on, what may change without a version change, and the rules for writing an integration that does not break.
This page says what your code can rely on, and what it must not assume.
What to rely on
| Item | Why |
|---|---|
The code field of errors | It is the machine contract of the error body, and the only stability promise Noryo makes about that body. Moving from one domain to another changes no code. |
| The HTTP status | It accompanies every code |
| The key format | nry_mer_sbx_ or nry_mer_live_, a 10-character key_id, a dot, the secret: a frozen public format |
The enr_ and req_ prefixes | They tell enrichment identifiers and request identifiers apart |
| The version carried by the path | /merchant/v1; a future v2 would live beside it |
What may change without a version change
| Item | Consequence for your code |
|---|---|
title and detail of errors | Written for humans, in English; may be reworded at any time. Do not parse them. |
The domain of the base URL and of type links | The host is not part of the contract: keep the base URL in configuration |
| The resolution policy (threshold, required fields) | It decides resolved or partial; its threshold is not a contract value. Decide on enrichment.status, not on a copied confidence threshold. |
| Rate limits | Operational settings; read Noryo-RateLimit-Limit rather than a constant |
| Catalogue coverage | A transaction that is not_found today may be resolved by a refresh tomorrow |
The rules of a client that does not break
- Decide on
code, never on an error's text. - Handle an unknown value with care. An unknown
enrichment.reasonreads asunspecified; an unexpected status is treated as an unusable result; an unknown error code is handled according to its HTTP status. - Read responses tolerantly. Ignore fields you do not know, and accept that an optional field (
category,logo_url) may be absent. - Send strict requests. The request schema is closed: add no field outside the contract, it would be refused. Omit an optional field rather than sending it as
null. - Treat identifiers as opaque. Store
enrichment_idandNoryo-Request-Idas they are, without drawing business meaning from them: anenrichment_idis random and tells neither an order nor a volume. - Resolve
Locationagainst your base URL, since it is relative. - Read header names case-insensitively, as HTTP requires.
Official names
The product is called Noryo Merchant API. Field, status and code names stay in English in every language of the documentation, exactly as the API returns them.
Published on 2026-10-08 21:04 UTC (version 1).
Was this page helpful?