Migration from legacy API & Webhook to 2025-01

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

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/v4 to https://api.aftership.com/tracking/2025-01.
2. The request header aftership-api-key is no longer supported in the versioned API. Please use as-api-key instead.
3. The API keys that are marked as Legacy Tracking API access only are no longer supported in the versioned API. Create a new API key and update your application's code if required. Check your API keys here.
4. Select the Webhook version when editing existing URLs or adding new ones. Please review your webhook settings for verification.
5. 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. If your current request volume falls within the defined rate limits, no additional action is required.

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.

preparing...

preparing...

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.

3. New SDK

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 Coordinates field replaced by Coordinate

The existing array field checkpoints.*.coordinates will be deprecated and replaced with object checkpoints.*.coordinate.

What's the difference?

preparing...

preparing...

What do I need to do?

1. Remove the parsing for the coordinates field.
2. Parse the new field coordinate in the API response and the webhook body if you are interested in this information; otherwise, no action is required.

5.2 Tracking ID format changed

The length of the tracking ID has been increased from 24 characters to 32 characters. The original 24-character ID will continue to be maintained and stored in the new legacy_id field. Both IDs can uniquely identify a tracking. We recommend using the 32-character ID, as the legacy ID will eventually be deprecated in upcoming releases.

What's the difference?

What do I need to do?

1. Extend the length of the tracking ID to 32 characters if you are using this field. Otherwise, no further action is required.

5.3 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.4 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.5 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.6 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.7 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.8 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.9 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.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.

5.11 tracking.transit_time formula updated

We're aligning our transit time calculation with carrier standards for improved accuracy. Our previous method included the pick-up date, resulting in an extra day compared to carriers. Now, transit time starts on the first business day after pick-up, aligning with carriers, where transit time begins on the first business day after pick-up. This change simplifies SLA management and shipping performance monitoring for merchants.

What do I need to do?

1. Be aware of the formula change and adjust your app's code where you use the value to ensure it won't break your system.

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 Endpoints Common Changes

7.1 New fields added in tracking

Please refer to the Tracking Model New Fields Added

7.2 Fields updated in tracking

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

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

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

8. Tracking Endpoints Specific Changes

8.1 GET /trackings endpoint

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

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

8.1.3 Parameters renamed

The following fields have been renamed:

What do I need to do?

1. Put the new field in the API request parameters if you want to use the field. Otherwise, no further action is required.

8.1.4 Parameters added

What do I need to do?

1. Put the new field in the API request parameters if you want to use the field. Otherwise, no further action is required.

8.2 POST /trackings endpoint

Please refer to the Tracking Endpoints Common Changes.

8.3 GET /trackings/:id endpoint

Please refer to the Tracking Endpoints Common Changes.

8.4 PUT /trackings/:id endpoint

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

8.5 DELETE /trackings/:id endpoint

Please refer to the Tracking Endpoints Common Changes.

8.6 POST /trackings/:id/retrack endpoint

Please refer to the Tracking Endpoints Common Changes.

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

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

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

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

10. Courier Endpoints Changes

10.1 GET /couriers

Please refer to the Courier Model Fields Renamed.

10.2 GET /couriers/all

Please refer to the Courier Model Fields Renamed.

10.3 POST /couriers/detect

10.3.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, origin_country_iso3 and destination_country_iso3 fields in the request body.
2. Add the new fields tracking_origin_country_region, tracking_destination_country_region, origin_country_region, and destination_country_region in the API request body if you want to retrieve data from these fields. Otherwise, no further action is required.

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

12. Estimated Delivery Date Endpoints Changes

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

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

12.1.2 New field confidence_code for EDD endpoint

Indicates the confidence level and associated reason for an AI EDD prediction request. For a comprehensive list of confidence codes, refer to this document.

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.

12.1.3 Add validation check for Batch prediction for the Estimated Delivery Date API

We have added validation checks for the origin_address.postal_code and destination_address.postal_code fields in the Tracking AI EDD. In case of invalid input, the API will now return META.CODE 4008 to indicate the errors.

What do I need to do?

Provide valid values for origin_address.postal_code and destination_address.postal_code in your API request otherwise, the API will return an error.

13. Webhook Changes

13.1 New fields added in tracking

Please refer to the Tracking model new fields added

13.2 Fields updated in tracking

Please refer to the Tracking model fields updated

14. What if I don’t migrate?

After Oct 9, 2025, any requests made to the legacy version will result in a 404 Not Found error. and therefore, we encourage you to complete the migration at your earliest convenience.