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

# Versions

We strive to make maintaining an API integration with ShipStream as easy as possible while not limiting our ability to
make improvements. There are two "versions" in the Global API: the "major" version number is indicated in the url
(such as `/api/global/v1/...` for version 1) and the "minor" version is specified by the client in either a header
or query parameter.

**Example**

```http Request theme={null}
GET /api/global/v1/orders
Host: example.shipstream.app
Authorization: Bearer ...
X-ShipStream-API-Version: 2024-10
```

```bash cURL theme={null}
curl --header "Authorization: Bearer ..." \
     --header "X-ShipStream-API-Version: 2024-10" \
     --url https://example.shipstream.app/api/global/v1/orders
```

In this example the major version is `v1` and the minor version is `2024-10`.

# Major Version

The endpoints of a major version indicated in the url path (e.g. `v1`) will always remain backward-compatible, if
possible, and breaking changes should only be introduced by adding a new version so that the old version is left unchanged.
New endpoints will often be added to the **current** version **without** incrementing the version number, so new major versions should
be infrequent. Each version is like a namespace and multiple versions may be available in which case you should always
use the newest that provides the functionality you need.

## Beta Version

The `/api/global/beta` namespace may used to provide new functionality that is still simmering, with the expectation that it
will be added to the latest version in the future. This will hopefully require you to just change `beta` to `v1`, for example, when the
functionality is declared to be finalized.

# Minor Version

The minor version should be specified in every request with a `X-ShipStream-API-Version` header or a `version=` query parameter.
This should be chosen as the year and month of the latest version at the time the integration is developed.

<Warning>
  If a version header or query parameter is not provided, the latest version will be assumed! To ensure the best stability,
  you should **always** specify a minor version.
</Warning>

The latest recognized version will only be updated whenever a breaking change is made, such as if a field's type must
be modified or a field was renamed or removed. This version number will be used to maintain backwards compatibility for
a limited time so that minor changes can be introduced without duplicating the API with a new major version each time, or
otherwise hampering the ability to make changes.

**For example**, if the field `foo` needs to be changed from an integer to a string, the API docs will be updated to reflect
that a string is returned, and the latest recognized version will be updated to the current year and month. Any API
requests for an older version will return the integer, and any API requests for a newer version will return a string.

The API response will include a header named `X-ShipStream-API-Version` which contains the effective version for the given request.

## Validation

If an invalid version number is specified in the request, a `400` error will be thrown and the error message will indicate
the latest tagged version. Specifying a future date is not allowed, since you can't predict what changes will potentially
be made in the future.

## Deprecation

If the requested version is deprecated or no longer supported, a `X-ShipStream-API-Version-Error` header will be added to the response.

<Warning>
  We strongly recommend that your integrations check for this error header and log an internal error so that you are notified automatically
  if your API is running a deprecated or unsupported version.
</Warning>