Versioning
Important Update: Changes to Our API Versioning Schedule
Starting from version 2025-07, we’re adjusting our API version release cadence to enhance stability and quality. New major versions of our API will now be released once every six months (twice yearly), replacing our previous quarterly schedule
Versioning helps the API users to smoothen the API upgrade process by providing a predictable new release and version deprecation schedule.
API users can manage their own system upgrade roadmap that fits their needs and no longer need to be bounded by the API version upgrade timeframe.
Making Requests
The API version is specified in the API endpoint URL. For AfterShip Returns API, the URL would be:
The version number follows a date-based format like YYYY-MM. For example, for the return resource in July 2025, the complete URL would be:
Response Header
To discover the exact API version serving your request, check the API response header field named as-api-version.
| HEADER NAME | DESCRIPTION | FORMAT |
|---|---|---|
| as-api-version | The actual API version that serves the request. | YYYY-MM |
Sample Header Value
2025-07 2026-01 and so on.
Release schedule
Expect a new version of the AfterShip Returns API every 6 months, released on the 2nd Thursday of that month. The table below provides the release dates for the next 6 versions:
| Version | Release Date | Supported until |
|---|---|---|
| 2025-07 | 2025-07-10 | 2028-07-08 |
| 2026-01 | 2026-01-08 | 2029-01-11 |
| 2026-07 | 2026-07-09 | 2029-07-12 |
| 2027-01 | 2027-01-07 | 2030-01-10 |
| 2027-07 | 2027-07-08 | 2030-07-11 |
| 2028-01 | 2028-01-06 | 2031-01-09 |
Every API version enjoys support for a minimum of approximately 36 months, ensuring that the first version remains supported until the day before the release of the seventh version. This provides developers with a substantial overlap of at least 30 months between two consecutive stable versions, allowing them ample time to complete their API upgrading process.
Lifecycle and Deprecation Policy
We strongly recommend updating your integration to the latest API version every quarter in order to use our latest features. If a request is made to an unsupported API version, it will automatically redirect to the oldest supported API version.
Version Support Schedule Example
