# Versioning and governance

> What is authoritative (the OpenAPI contract), how the API is versioned by path family, what the contract version and the publication date mean, and why the host is not part of it.

## What is authoritative

The **machine contract** of Noryo Merchant API is an OpenAPI 3.1 document. The [API reference](https://developer.noryo.app/en-GB/merchant/reference) is generated from it, and the document is not translated: it is one source for everyone, from which a client can generate its code. Guide pages, like this one, explain it and describe the behaviour a schema does not state (idempotency, deduplication, retention).

## The version belongs to the family

The version is carried by the path: `/merchant/v1`. It belongs to the API **family**, so that a future `merchant/v2` can live beside `merchant/v1` rather than replace it. The three current routes are all under `/merchant/v1`.

```http
POST /merchant/v1/enrichments
GET  /merchant/v1/enrichments/{enrichment_id}
POST /merchant/v1/enrichments/{enrichment_id}/refresh
```

## Three numbers, three meanings

| What you see | What it designates | Current value |
|---|---|---|
| The `v1` segment of the path | The version of the API family, the one your code calls | `v1` |
| The OpenAPI contract version | The revision of the machine document | `1.0.0` |
| The documentation publication date | The documentation publication that contains this contract version | 2026-10-01 |

The reference shows the publication date; that is what to quote to say "the documentation as I read it". See [Changelog](https://developer.noryo.app/en-GB/merchant/governance/changelog).

## The host is not part of the contract

Noryo may serve the API from more than one domain. No hostname enters any identity, hash or signature:

- the `Location` header of a refresh is a **relative** path;
- a transaction's economic identity does not depend on the host called;
- the `type` of an error is a link to the documentation, not part of the error code.

The contract currently declares `https://api.noryo.app`. Put the base URL in your configuration, and do not hardcode it anywhere else.

## What is stable, and what is not

The [Compatibility](https://developer.noryo.app/en-GB/merchant/governance/compatibility) page details what your code can rely on (error codes, the format of keys and identifiers) and what may change without a version (the text of error messages, the resolution policy).

## In this section

- [Compatibility](https://developer.noryo.app/en-GB/merchant/governance/compatibility): writing a client that does not break.
- [Changelog](https://developer.noryo.app/en-GB/merchant/governance/changelog): the dated publications.

---

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