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
Request
GET /api/global/v1/orders
Host: example.shipstream.app
Authorization: Bearer ...
X-ShipStream-API-Version: 2024-10
cURL
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.
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.
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.
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.