Migration from 2024-07 API to 2024-10

This migration guide outlines the essential changes required to implement new functionalities when transitioning from the API and webhook version 2024-07 to 2024-10.

API changes

What's the difference?

Change	Before	After
Base URL	https://api.aftership.com/tracking/2024-07	https://api.aftership.com/tracking/2024-10
as-api-version header’s value	2024-07	2024-10
as-webhook-version header’s value	2024-07	2024-10

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-07 to https://api.aftership.com/tracking/2024-10.
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.

API Endpoints Changes

Legacy Tracking Endpoints Deprecation

What's the difference?

Change	Before	After
Deprecating legacy tracking endpoints	- GET /trackings/{slug}/{tracking_number} - PUT /trackings/{slug}/{tracking_number} - DELETE /trackings/{slug}/{tracking_number} - POST /trackings/{slug}/{tracking_number}/retrack - POST /trackings/{slug}/{tracking_number}/mark-as-completed	-

What do I need to do?

Make the following updates to your application's code:

1. Replace GET /trackings/{slug}/{tracking_number} endpoint with GET /trackings/{id} endpoint. Refer to the documentation on get tracking endpoints for more details.
2. Replace PUT /trackings/{slug}/{tracking_number} endpoint with PUT /trackings/{id} endpoint. Refer to the documentation on update tracking endpoints for more details.
3. Replace DELETE /trackings/{slug}/{tracking_number} endpoint with DELETE /trackings/{id} endpoint. Refer to the documentation on delete tracking endpoints for more details.
4. 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.
5. 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.

Searching for Trackings Using Cursor

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?

Change	Before	After
Query parameters updates	Using page parameters to traverse search results.	Use the cursor to get data for the next page.
Response body updates	Returns all query parameters.	- Removed query parameters. - Added pagination object with cursor.

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.

Enhanced field type verification

Receive a 400 Bad Request error response when any field in the request body has an incorrect type.

What's the difference?

Change	Before	After
Enhanced field type verification	The field will be ignored.	A bad request error will be returned.

Affected Endpoints

Affected Endpoints
POST /trackings
PUT /trackings/{id}
POST /couriers/detect
POST /estimated-delivery-date/predict-batch

What do I need to do?

Make the following updates to your application's code:

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

Business logic changes

Overview

Update	Affected Endpoints
Tracking modal new fields: aftership_tracking_url aftership_tracking_order_url next_couriers[x].courier_tracking_link next_couriers[x].courier_redirect_link	API endpoint: - GET /trackings - GET /trackings/:id - DELETE /trackings/:id - POST /trackings - PUT /trackings/:id - POST /trackings/:id/mark-as-completed - POST /trackings/:id/retrack Tracking Webhook
The existing field expected_delivery will be deprecated and replaced with courier_estimated_delivery_date	API endpoint: - GET /trackings - GET /trackings/:id - DELETE /trackings/:id - POST /trackings - PUT /trackings/:id - POST /trackings/:id/mark-as-completed - POST /trackings/:id/retrack Tracking Webhook

Key Updates - New fields

New field aftership_tracking_url

The field contains the tracking page URL of the individual shipment. It will display the default tracking page or a variation based on any applicable segmentation rules.

What do I need to do?

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

New field aftership_tracking_order_url

The field contains the order URL that displays the tracking page for the entire order, including all shipments. It will show the default tracking page or a variation based on any applicable segmentation rules.

What do I need to do?

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

New field next_couriers[x].courier_tracking_link

The field contains the official tracking URL of the next courier, if available. The language parameter of this link is determined by the destination country/region and the language associated with the shipment. If the data associated with the destination country/region and language of the shipment is not available, AfterShip will default the language parameter of the link to "US".

What do I need to do?

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

New field next_couriers[x].courier_redirect_link

The field provides the link for modifying delivery instructions (such as delivery date and shipping address) if supported by the next carrier. The language parameter of this link is determined by the destination country/region and the language associated with the shipment. If the data associated with the destination country/region and language of the shipment is not available, AfterShip will default the language parameter of the link to "US".

What do I need to do?

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

Key Updates - Updated fields

expected_delivery rename

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

What's the difference?

Change	Before	After
expected_delivery will be deprecated and replaced with courier_estimated_delivery_date	expected_delivery Example: 2024-10-03T10:00:00	courier_estimated_delivery_date Example: {"estimated_delivery_date": "2022-01-04", "estimated_delivery_date_min": "2022-01-02","estimated_delivery_date_max": "2022-01-04"}

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.

What if I don’t migrate?

If you choose not to migrate, the 2024-07 API will continue to be supported for at least 18 months. However, API traffic will eventually be redirected to the 2024-10 version following the deprecation of the versioned API. For further details on API versioning, please refer to our documentation.