Migration from 2024-04 API & Webhook to 2025-07

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

The following guide will help you migrate the API and webhook from version 2024-04 to version 2025-07.

1. General API Changes

1.1 Endpoint Change

What's the difference?

What do I need to do?

Make the following updates to your application's code:

1. Replace the base URL from https://api.aftership.com/tracking/2024-04 to https://api.aftership.com/tracking/2025-07.
2. Select the Webhook version when editing existing URLs or adding new ones. Please review your webhook settings for verification.
3. Parse the header to distinguish between different versions. Otherwise, no further action is required.

1.2 Rate Limit Policy

We have updated the rate limit for all endpoints from sharing one rate limit to each endpoint now having its dedicated rate limit to reduce the mutual impact across endpoints. Find the specific rate limit for each endpoint in the table below.

What do I need to do?

Please refer to the updated rate limit table above to manage your requests and prevent encountering frequent 429 errors. If your request volume exceeds the maximum rate limit allocated for a specific endpoint, adjust the frequency of your requests accordingly. No additional action is required if your request volume falls within the defined rate limits.

1.3 Enhanced field type verification

For all POST / PUT / PATCH endpoints (the request with a body), a 400 Bad Request error will be returned if any field in the request body has an incorrect data type.

What do I need to do?

Make the following updates to your application's code:

1. Implement error handling mechanisms in your application to capture and handle the 400 Bad Request error.
2. Ensure that the types of all fields are consistent with the types described in the document.

2. API Endpoints Deprecation

What's the difference?

What do I need to do?

Make the following updates to your application's code:

1. Replace the "Add notifications" and "Remove notifications" endpoints with the "Update tracking" endpoint to update customers. Refer to the documentation on updating tracking endpoints for more information.
2. Replace the "Get tracking notifications" endpoint with the "Get tracking" endpoint to retrieve customer's details. Refer to the documentation on get tracking endpoints for more details.
3. Replace the last_checkpoint endpoints with the GET /tracking/{id} endpoint.
4. The GET /tracking/{id} endpoint will respond to all checkpoints in the tracking information. Retrieve the last item in the checkpoints array returned by these endpoints to obtain the most recent checkpoint.
5. Replace GET /trackings/{slug}/{tracking_number} endpoint with GET /trackings/{id} endpoint. Refer to the documentation on get tracking endpoints for more details.
6. Replace PUT /trackings/{slug}/{tracking_number} endpoint with PUT /trackings/{id} endpoint. Refer to the documentation on update tracking endpoints for more details.
7. Replace DELETE /trackings/{slug}/{tracking_number} endpoint with DELETE /trackings/{id} endpoint. Refer to the documentation on delete tracking endpoints for more details.
8. Replace POST /trackings/{slug}/{tracking_number}/retrack endpoint with POST /trackings/{id}/retrack endpoint. Refer to the documentation on retrack tracking endpoints for more details.
9. Replace POST /trackings/{slug}/{tracking_number}/mark-as-completed endpoint with POST /trackings/{id}/mark-as-completed endpoint. Refer to the documentation on mark tracking as completed endpoints for more details.
10. Replace GET /couriers/all endpoints with GET /couriers endpoint. Refer to the documentation on GET couriers endpoints for more information.

3. New SDK Added

4. Tracking Model New Fields Added

What do I need to do?

For all new fields, simply parse the new field in the API response and the webhook body if you want to fetch the field; otherwise, no action is required.

5. Tracking Model Fields Updated

5.1 Tracking ID format changed

• The length of the tracking ID has been updated from a 24-character string to a string ranging from 0 to 128 characters, following the format [0-9a-zA-Z-_]{1,128}.
• The tracking ID now supports user-provided values. If no value is provided, the system will automatically generate a 32-character UUID.

What's the difference?

What do I need to do?

1. Update the format of the tracking ID to match the new format [0-9a-zA-Z-_]{1,128} if you are using this field. Otherwise, no action is required.

5.2 Slug format change

Currently, the slug in detect couriers supports both an array of strings and comma-separated string formats. Moving forward, we will change it to support only the array of strings format.

What's the difference?

What do I need to do?

1. If your input for slug is in comma-separated string format, please convert it to an array of strings. Otherwise, no further action is required.

5.3 order_promised_delivery_date new value format

The order_promised_delivery_date now supports time and timezone information.

What's the difference?

What do I need to do?

1. Parse the field with time and timezone in the API response and the webhook body if you want to fetch the field. Otherwise, no further action is required.
2. Specify the order_promised_delivery_date with time and timezone in the API request body if you want to input the field. Otherwise, no further action is required.

5.4 expected_delivery renamed and structure changed

The expected_delivery field will be renamed to courier_estimated_delivery_date and will support time range values.

What's the difference?

preparing...

What do I need to do?

1. Remove the parsing for the expected_delivery" field.
2. Parse the new field courier_estimated_delivery_date in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.

5.5 tracking.next_couriers renamed and structure changed

The tracking.next_couriers field will be replaced with tracking.last_mile.

preparing...

preparing...

What do I need to do?

1. Add the new field in the API request body if you want to use the field.
2. Remove the parsing for the tracking.next_couriers field.
3. Parse the new field tracking.last_mile in the API response and the webhook body if you want to retrieve data from this field. Otherwise, no further action is required.

5.6 tracking.customer_name replaced

The tracking.customer_name field will be replaced with tracking.customers.*.name.

preparing...

preparing...

What do I need to do?

1. Put the new field in the API request body if you want to use the field.
2. Remove the parsing for the tracking.customer_name field.
3. Parse the new field tracking.customers.*.name in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.

5.7 tracking.emails replaced

The tracking.emails field will be replaced with tracking.customers.*.email.

preparing...

preparing...

What do I need to do?

1. Put the new field in the API request body if you want to use the field.
2. Remove the parsing for the tracking.emails field.
3. Parse the new field tracking.customers.*.email in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.

5.8 tracking.smses replaced

The tracking.smses field will be replaced with tracking.customers.*.phone_number.

preparing...

preparing...

What do I need to do?

1. Put the new field in the API request body if you want to use the field.
2. Remove the parsing for the tracking.smses field.
3. Parse the new field tracking.customers.*.phone_number in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.

5.9 tracking.shipment_weight structure changed

The tracking.shipment_weight_unit and tracking.shipment_weight fields will be replaced with a nested object tracking.shipment_weight containing unit and value.

preparing...

preparing...

What do I need to do?

1. Put the new field in the API request body if you want to use the field.
2. Remove the parsing for the tracking.shipment_weight_unit and tracking.shipment_weight fields.
3. Parse the new fields tracking.shipment_weight.unit and tracking.shipment_weight.value in the API response and the webhook body if you want to retrieve data from these fields. Otherwise, no further action is required.

5.10 tracking.tracking_ship_date format updated

The tracking.tracking_ship_date field date format has been updated and will support more date-time formats.

preparing...

preparing...

What do I need to do?

1. Ensure that valid values are provided for tracking_ship_date in your API request. Otherwise, the API will return a 400 error.
2. Parse the field tracking.tracking_ship_date in the API response and the webhook body using the new formats if you want to retrieve data. Otherwise, no further action is required.

6. Tracking Model Fields Renamed

The following fields have been renamed:

What do I need to do?

1. Remove the parsing for the old field.
2. 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.

7. Tracking Model Fields Removed

The following fields have been removed and replaced with new ones.

• tracking_origin_country
• tracking_destination_country
• tracking_postal_code
• tracking_state

What do I need to do?

1. Replace the parsing for the tracking_origin_country_region with origin_country_region.
2. Replace the parsing for the tracking_destination_country_region with destination_country_region.
3. Replace the parsing for the tracking_postal_code with destination_postal_code.
4. Replace the parsing for the tracking_state with destination_state.

8. Tracking Endpoints Common Changes

8.1 New fields added in tracking

Please refer to the Tracking Model New Fields Added

8.2 Fields updated in tracking

Please refer to the Tracking Model Fields Updated and Tracking Model Fields Renamed

8.3 Fields removed in tracking

Please refer to the Tracking Model Fields Removed

8.4 Removed the tracking object wrapper from the request body

preparing...

preparing...

What do I need to do?
Remove the tracking object wrapper from the request body when you create/update a tracking or detect couriers.

8.5 Removed the tracking object wrapper from the response body

preparing...

preparing...

What do I need to do?
Remove the tracking object wrapper from the response body when using the tracking endpoints.

9. Tracking Endpoints Specific Changes

9.1 GET /trackings endpoint

9.1.1 Cursor Pagination

Use cursor parameters instead of page parameters to improve search performance. Additionally, we have standardized the response body envelope for consistency.

What's the difference?

What do I need to do?

Make the following updates to your application's code:

1. Do not fetch query parameters from the response.
2. Iterate search results using the cursor instead of relying on page number.

9.1.2 Parameters validation

If a user inputs an invalid query time parameter, we will no longer set it to the default time value. We will return a 400 error code to indicate the invalid query time parameter, preventing any hidden behaviour.

What's the difference?

Common mistake

A common mistake when providing datetime values for the above keys is improper character escaping of the "+" sign. For example, when sending a timestamp via a GET request, such as “2024-12-01T16:42:00+00:00”, the plus sign (“+”) must be correctly escaped as “%2B”. Thus, the correct value should be “2024-12-01T16:42:00%2B00:00”. If this character is not properly escaped, a 400 error will occur in the API response.

What do I need to do?

Make the following updates to your application's code:

1. Implement error-handling mechanisms in your application’s code to capture and handle 400 Bad Request errors.
2. Ensure that the data types of all fields match the types specified in the document.

9.2 POST /trackings endpoint

9.2.1 New fields added in the request body

Create a tracking endpoint now supports custom tracking id.

What's the difference?

preparing...

preparing...

What do I need to do?
Add the new id field to the API request body if you want to retrieve the corresponding data. Otherwise, no action is required.

9.3 GET /trackings/:id endpoint

Please refer to the Tracking Endpoints Common Changes.

9.4 PUT /trackings/:id endpoint

9.4.1 Support updating tracking_ship_date for non-pending trackings

Regardless of the tracking status, you can update the value of the tracking_ship_date field.

What do I need to do?
Include the field in the API request body if you want to update it. Otherwise, no further action is required.

9.5 DELETE /trackings/:id endpoint

Please refer to the Tracking Endpoints Common Changes.

9.6 POST /trackings/:id/retrack endpoint

Please refer to the Tracking Endpoints Common Changes.

9.7 POST /trackings/:id/mark-as-complete endpoint

9.7.1 New fields added in the request body

Tracking mark as completed endpoint supports event_datetime.

What's the difference?

preparing...

preparing...

What do I need to do?

Add the new field event_datetime to the API request body if you want to retrieve corresponding data. Otherwise, no further action is required.

9.7.2 Create a new checkpoint when tracking is marked as completed

A new checkpoint will be created when the user marks the tracking as completed.

preparing...

preparing...

What do I need to do?

Parse the new field tracking.checkpoints in the API response and the webhook body if you want to retrieve data. Otherwise, no further action is required.

10. Courier Model New Fields

What do I need to do?

To fetch any new fields, simply parse them in the API response and the webhook body. Otherwise, no action is required.

11. Courier Model Fields Renamed

The following fields/enum values have been renamed:

What do I need to do?

1. Remove the parsing for the old field.
2. Parse the new field in the API response if you want to retrieve data from the new field. Otherwise, no further action is required.

12. Courier Endpoints Changes

12.1 GET /couriers

12.1.1 Parameters added

What's the difference?

What do I need to do?

Include the new field in the API request parameters if you want to use it. Otherwise, no action is required.

12.2 POST /couriers/detect

12.2.1 Fields updated in the request body

What's the difference?

What do I need to do?

1. Remove the tracking_origin_country,tracking_destination_country, tracking_state and tracking_postal_code fields in the request body.
2. Add the new fields origin_country_region, destination_country_region, destination_state, and destination_postal_code in the API request body if you want to retrieve data from these fields. Otherwise, no further action is required.

13. Estimated Delivery Date Endpoint fields Renamed

The following fields have been renamed:

What do I need to do?

1. Remove the parsing for the old field.
2. Parse the new field in the API response if you want to retrieve data from the new field. Otherwise, no further action is required.

14. Estimated Delivery Date Endpoints Changes

14.1 POST /estimated-delivery-date/predict-batch

14.1.1 New field id for EDD endpoint

The reference ID acts as a unique identifier to associate the estimated delivery date value generated by AfterShip EDD to its corresponding shipment.

What do I need to do?

Parse the new field in the API response if you want to fetch the field. Otherwise, no further action is required.

15. Webhook Changes

15.1 New fields added in tracking

Please refer to the Tracking model new fields added

15.2 Fields updated in tracking

Please refer to the Tracking model fields updated

15.3 Fields removed in tracking

Please refer to the Tracking Model Fields Removed

16. What if I don’t migrate?

After Oct 9, 2025, any requests made to the 2024-04 version will automatically be redirected to version 2024-07. While this redirection is designed to minimize disruptions, it may not fully support all functionalities available in the newer versions, and therefore, we encourage you to complete the migration at your earliest convenience.