Migration from 2024-04 API to 2024-07

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

API changes

What's the difference?

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

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/2024-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.

API Endpoints Changes

Notification Endpoints Deprecation

What's the difference?

Change	Before	After
Deprecating notifications endpoints	POST /notifications/{tracking_id}/add POST notifications/{tracking_id}/remove POST /notifications/{slug}/{tracking_number}/add POST /notifications/{slug}/{tracking_number}/remove GET /notifications/{tracking_id} GET /notifications/{slug}/{tracking_number}	-

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 emails and SMSes. 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 email and SMS details. Refer to the documentation on get tracking endpoints for more details.

Last checkpoint Endpoints Deprecation

What's the difference?

Change	Before	After
Deprecating last checkpoint endpoints	GET /last_checkpoint/{tracking_id} GET /last_checkpoint/{slug}/{tracking_number}	-

What do I need to do?

Make the following updates to your application's code:

1. Replace the last_checkpoint endpoints with the GET /tracking/{tracking_id} or GET /tracking/{slug}/{tracking_number} endpoint.
2. The GET /tracking/{tracking_id} or GET /tracking/{slug}/{tracking_number} 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.

API Rate limit changes

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.

Endpoint	Rate Limit(req/s)
POST /2024-07/trackings	20
GET /2024-07/trackings	6
GET /2024-07/trackings/:id	5
GET /2024-07/trackings/:slug/:tracking_number	5
PUT /2024-07/trackings/:id	5
PUT /2024-07/trackings/:slug/:tracking_number	5
DELETE /2024-07/trackings/:id	5
DELETE /2024-07/trackings/:slug/:tracking_number	5
POST /2024-07/trackings/:id/retrack	5
POST /2024-07/trackings/:id/mark-as-completed	5
POST /2024-07/trackings/:slug/:tracking_number/retrack	5
POST /2024-07/trackings/:slug/:tracking_number/mark-as-completed	5
POST /2024-07/couriers/detect	3
GET /2024-07/couriers	5
GET /2024-07/couriers/all	5
POST /2024-07/estimated-delivery-date/predict-batch	20

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.

Business logic changes

Overview

Update	Impact
Tracking response new fields: delivery_location_type legacy_id	API endpoint: - GET /trackings - GET /trackings/:id - GET /trackings/:slug/:tracking_number - POST /trackings - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number Tracking Webhook
Estimated delivery date response new fields: id	API endpoint: - POST estimated-delivery-date/predict-batch
Create/update tracking request body new fields: shipment_weight	API endpoint: - POST /trackings - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number Tracking Webhook
Merge shipment_weight and shipment_weight_unit into shipment_weight object.	API endpoint: - GET /trackings - GET /trackings/:id - GET /trackings/:slug/:tracking_number - POST /trackings - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number Tracking Webhook
tracking.checkpoints[x].events.code supports new enum values: carrier_pickup_failed dropped_off_for_carrier_pickup delayed handed_over_to_last_mile_carrier received_by_last_mile_carrier returning_to_sender address_corrected customer_enquiry_raised address_verified	API endpoint: - GET /trackings - GET /trackings/:id - GET /trackings/:slug/:tracking_number - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number Tracking Webhook
tracking.order_promised_delivery_date supports new value formats: - YYYY-MM-DDTHH:mm:ss - YYYY-MM-DDTHH:mm:ssZ	API endpoint: - GET /trackings - GET /trackings/:id - GET /trackings/:slug/:tracking_number - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number Tracking Webhook
Allow to update tracking_ship_date for non-pending tracking	API endpoint: - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number
The length of the tracking ID has changed from 24 characters to 32 characters.	API endpoint: - GET /trackings - GET /trackings/:id - GET /trackings/:slug/:tracking_number - POST /trackings - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number Tracking Webhook
The smses and emails no longer support comma-separated string format for creating and updating tracking endpoints.	API endpoint: - POST /trackings - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number
A slug no longer supports comma-separated string format for detecting courier endpoints.	API endpoint: - POST /couriers/detect
Removed the tracking object wrapper from the request body.	API endpoint: - POST /trackings - POST /couriers/detect - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number
Removed the tracking object wrapper from the response body.	API endpoint: - GET /trackings - GET /trackings/:id - GET /trackings/:slug/:tracking_number - POST /trackings - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number - POST /trackings/:id/retrack - POST /trackings/:slug/:tracking_number/retrack - POST /trackings/:id/mark-as-completed - POST /trackings/:slug/:tracking_number/mark-as-completed

Key Updates - New fields

New field delivery_location_type

The delivery location type represents the secure area where the carrier leaves the package, such as a safe place, locker, mailbox, front porch, etc. This information helps ensure the shipment reaches the intended recipient efficiently, minimizing the risk of theft or damage.

What do I need to do?

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

New field legacy_id

The length of the tracking ID has been increased from 24 characters to 32 characters. We will use the legacy_id field to store the original 24-character tracking ID to maintain compatibility with existing data. Therefore, all tracking endpoints will continue to work with the legacy_id field as before.

What do I need to do?

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

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.

New field shipment_weight

The shipment weight and unit are obtained from the carrier by default. In scenarios where the carrier does not provide the weight, users can input it manually. AfterShip will prioritize returning the weight value provided by the carrier whenever available.

What do I need to do?

Put the new field in the API request body if you want to input the field. Otherwise, no further action is required.

Key Updates - Updated fields

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?

Change	Before	After
The length of the tracking ID has been changed from 24 characters to 32 characters.	my2uktymyz72xld1f7l3h01z	c17ed4faec0a4831b675f445aad72e4e

What do I need to do?

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

tracking.smses and tracking.emails format updated

Currently, smses and emails support 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?

Change	Before	After
smses no longer support comma-separated string format when PUT or POST a tracking.	["+5321288112","+893636771"] or "+5321288112, +893636771"	["+5321288112","+893636771"]
emails no longer support comma-separated string format when PUT or POST a tracking.	["[email protected]","[email protected]"] or "[email protected],[email protected]"	["[email protected]","[email protected]"]

What do I need to do?

If your input for emails and smses is in comma-separated string format, please convert them to an array of strings. Otherwise, no further action is required.

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?

Change	Before	After
slug no longer supports comma-separated string format when detecting couriers.	["ups","fedex"] or "ups, fedex"	["ups","fedex"]

What do I need to do?

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.

order_promised_delivery_date new value format

The order_promised_delivery_date now supports time and timezone information.

What's the difference?

Change	Before	After
Supports new value format.	YYYY-MM-DD	- YYYY-MM-DD - YYYY-MM-DDTHH:mm:ss - YYYY-MM-DDTHH:mm:ssZ

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.

Removed the tracking object wrapper from the request body

What's the difference?

Change	Before	After
Removed the tracking object wrapper from the request body.	{"tracking": {"slug":fedex","tracking_number":"999737828883221"}}	{"slug": fedex","tracking_number": "999737828883221"}

What do I need to do?

Make the following update to your application's code:

1. Remove the tracking object wrapper from the request body when you create/update a tracking or detect couriers.

Removed the tracking object wrapper from the response body

What's the difference?

Change	Before	After
Removed the tracking object wrapper from the response body.	{"meta": {"code": 201},"data": {"tracking": {"id": "nke21z8sryxsqlyh2o45d02f"…}}}	{"meta": {"code": 201},"data": {{"id": "nke21z8sryxsqlyh2o45d02f"…}}

What do I need to do?

Make the following update to your application's code:

1. Remove the tracking object wrapper from the response body when using the tracking endpoints.

Support updating tracking_ship_date for non-pending trackings

What do I need to do?

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

What if I don’t migrate?

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