---
title: "Versioning"
description: "What may change within v1, and what never does."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

Every path starts with `/v1`. Within `/v1`, the API only grows: code written against it today keeps working.

## What may change within v1

- New operations, and new events for [webhooks](/merchant-api/webhooks).
- New optional arguments on an operation.
- New fields in an answer, at any depth, and in a webhook's `data`.
- New values of an enum: in an argument, and in an answer.
- New filters, sorts, search fields and facets on a list.
- Wording: a problem's `title` and `detail`, an operation's summary.

So read answers tolerantly: ignore fields you don't know, treat an enum value you don't know as "other" rather than an error, and branch on a problem's `type` or `code`, never its sentences. The OpenAPI document marks enums that may grow in answers with `x-extensible-enum`.

## What never changes within v1

- An operation's path, method or scope.
- An argument's name or type, or its limits narrowed; an optional argument turned required; an argument value refused that was taken.
- A field removed from an answer, renamed, given another type, or made optional or nullable.
- A list's sort removed or renamed, or where its rows with no value fall.
- A write that takes an `Idempotency-Key` stopping to take one.

A change of that kind ships as a new operation beside the old one, which keeps working. Every change to the API is checked against this list before it ships.

## Following changes

The [reference](/merchant-api/reference) and the OpenAPI document at `https://api.sherpo.io/merchant/openapi.json` are rebuilt from the API itself on every release, so they always describe what runs.

Source: https://docs.sherpo.io/merchant-api/versioning/index.mdx
