Migration from 2025-01 API & Webhook to 2025-04

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

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/2025-01 to https://api.aftership.com/tracking/2025-04.
2. When editing existing URLs or adding new ones, select the Webhook version. Please review your webhook settings for verification.
3. Parse the header to distinguish between different versions. Otherwise, no action is required.

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 GET /couriers/all endpoints with GET /couriers endpoint. Refer to the documentation on GET couriers endpoints for more information.

3. New API Endpoints

The following endpoints are added in API 2025-04:

• GET /courier-connections
• POST /courier-connections
• PATCH /courier-connections/:id
• GET /courier-connections/:id
• DELETE /courier-connections/:id

What do I need to do?

Make the following updates to your application's code:

1. Implement the courier connections interface in your code i to use this feature. Otherwise, no further action is required.

4. New SDK Added

5. Tracking Model New Fields Added

What do I need to do?

Simply parse the new field in the API response and the webhook body to fetch the field. Otherwise, no action is required.

6. Tracking Model Fields Updated

6.1 Tracking ID format changed

• The length of the tracking ID has been updated from a 32-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.

7. Tracking Model Fields Removed

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

• tracking_origin_country_region
• tracking_destination_country_region
• 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 section of the guide.

8.2 Fields updated in tracking

Please refer to the Tracking Model Fields Updated section of the guide.

8.3 Fields removed in tracking

Please refer to the Tracking Model Fields Removed section of the guide.

9. Tracking Endpoints Specific Changes

9.1 GET /trackings endpoint

Please refer to the Tracking Endpoints Common Changes section of the guide.

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

Please refer to the Tracking Endpoints Common Changes.

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

Please refer to the Tracking Endpoints Common Changes.

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 action is required.

12. Courier Endpoints Common Changes

12.1 New fields added in courier

Please refer to the Courier Model New Fields section of the guide.

12.2 Fields updated in courier

Please refer to the Courier Model Fields Renamed section of the guide.

13. Courier Endpoints Specific Changes

13.1 GET /couriers

13.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.

13.2 POST /couriers/detect

13.2.1 Fields updated in the request body

What's the difference?

What do I need to do?

1. Remove the tracking_origin_country_region, tracking_destination_country_region, tracking_state, and tracking_postal_code fields in the request body.
2. Include 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 them. Otherwise, no action is required.

14. Webhook Changes

13.1 New fields added in tracking

Please refer to the Tracking model new fields added section of the guide.

13.2 Fields updated in tracking

Please refer to the Tracking model fields updated section of the guide.

13.3 Fields removed in tracking

Please refer to the Tracking Model Fields Removed section of the guide.

15. What if I don’t migrate?

After July 8, 2026, any requests made to the 2025-01 version will be automatically redirected to version 2025-04. 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.