Migration from 2025-07 API & Webhook to 2026-01
The following guide will help you migrate the API and webhook from version 2025-07 to version 2026-01.
1. General API Changes
1.1 Endpoint Change
What's the difference?
| Change | Before | After |
|---|---|---|
| Base URL | https://api.aftership.com/tracking/2025-07 | https://api.aftership.com/tracking/2026-01 |
as-api-version response header value | 2025-07 | 2026-01 |
as-webhook-version request header value | 2025-07 | 2026-01 |
What do I need to do?
Make the following updates to your application's code:
- Replace the base URL from https://api.aftership.com/tracking/2025-07 to https://api.aftership.com/tracking/2026-01.
- When editing existing URLs or adding new ones, select the correct Webhook version. Please review your webhook settings for verification.
- Parse the header to distinguish between different versions. Otherwise, no action is required.
2. New SDK Added
3. Tracking Model Fields Updated
3.1 Order promised delivery date structure changed
The order_promised_delivery_date field will support time range values.
What's the difference?
| Change | Before | After |
|---|---|---|
order_promised_delivery_date | string or null Example: 2024-10-03T10:00:00 | Object or null Example: { "promised_delivery_date": null, "promised_delivery_date_min": "2022-01-02T10:00:00", "promised_delivery_date_max": "2022-01-04T10:00:00" } or { "promised_delivery_date": "2022-01-03T10:00:00", "promised_delivery_date_min": null, "promised_delivery_date_max": null } |
What do I need to do?
- Ensure that the valid values are provided for the
order_promised_delivery_datein your API request. Otherwise, the API will return a 400 error. - Parse the field
order_promised_delivery_datein the API response and the webhook body using the new format if you want to retrieve data. Otherwise, no further action is required.
3.2 Checkpoint zip renamed
The checkpoint.zip field has been renamed to checkpoint.postal_code.
What do I need to do?
- Remove the parsing of the old field.
- Parse the new field in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.
3.3 New confidence codes added
We have introduced 2 new confidence codes to the aftership_estimated_delivery_date.confidence_code field.
For a comprehensive list of confidence codes, refer to this document.
| Confidence code | Description |
|---|---|
| 10000 | Highest confidence. Single EDD accuracy is statistically equivalent to Range EDD. |
| 30004 | Medium confidence. Origin or destination address lacks precision. |
What do I need to do?
- Parse the new codes in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.
4. Tracking Model Fields Removed
The following fields have been removed from the tracking module.
last_mile_tracking_supported
What do I need to do?
- Remove the parsing of the
last_mile_tracking_supportedfield. - If you want to determine if a tracking is a multi-leg tracking, please update the logic to check whether
last_mileis null or not.
5. Tracking Endpoints Common Changes
5.1 Fields updated in tracking
Please refer to the Tracking Model Fields Updated section of the guide.
5.2 Fields removed in tracking
Please refer to the Tracking Model Fields Removed section of the guide.
6. Tracking Endpoints Specific Changes
6.1 GET /trackings endpoint
Please refer to the Tracking Endpoints Common Changes section of the guide.
6.2 POST /trackings endpoint
Please refer to the Tracking Endpoints Common Changes section of the guide.
6.3 GET /trackings/:id endpoint
Please refer to the Tracking Endpoints Common Changes section of the guide.
6.4 PUT /trackings/:id endpoint
Please refer to the Tracking Endpoints Common Changes section of the guide.
6.5 DELETE /trackings/:id endpoint
Please refer to the Tracking Endpoints Common Changes section of the guide.
6.6 POST /trackings/:id/retrack endpoint
Please refer to the Tracking Endpoints Common Changes section of the guide.
6.7 POST /trackings/:id/mark-as-complete endpoint
Please refer to the Tracking Endpoints Common Changes section of the guide.
7. Estimated Delivery Date Endpoints Changes
7.1 POST /estimated-delivery-date/predict
7.1.1 New confidence codes added
We have added two new confidence codes for AI-EDD predictions. For the complete list of confidence codes, refer to this document.
| Confidence code | Description |
|---|---|
| 10000 | Highest confidence. Single EDD accuracy is statistically equivalent to Range EDD. |
| 30004 | Medium confidence. Origin or destination address lacks precision. |
What do I need to do?
- Parse the new codes in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.
7.2 POST /estimated-delivery-date/predict-batch
7.2.1 New confidence codes added
We have added two new confidence codes for AI-EDD predictions. For the complete list of confidence codes, refer to this document.
| Confidence code | Description |
|---|---|
| 10000 | Highest confidence. Single EDD accuracy is statistically equivalent to Range EDD. |
| 30004 | Medium confidence. Origin or destination address lacks precision. |
What do I need to do?
- Parse the new codes in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.
8. Webhook Changes
8.1 Fields updated in tracking
Please refer to the Tracking Model Fields Updated section of the guide.
8.2 Fields removed in tracking
Please refer to the Tracking Model Fields Removed section of the guide.
9. What if I don't migrate?
After July 6, 2028, any requests made to the 2025-07 version will be automatically redirected to the oldest supported API version. While this redirection aims to minimize disruptions, it may not fully support all functionalities available in the newer versions. We encourage you to complete the migration at your earliest convenience.