Migration from 2023-10 API to 2024-01

The following guide will help you to migrate the API and webhook from the 2023-10 version to the 2024-01 version.

Breaking changes

API changes

What's the difference?

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

What do I need to do?

1. Update your application's code, replacing the base URL from https://api.aftership.com/tracking/2023-10 to https://api.aftership.com/tracking/2024-01.
2. Parse the header if you want to identify different versions; otherwise, no action is required.

Webhook changes

What's the difference?

Change	Before	After
as-webhook-version request header’s value	2023-10	2024-01

What do I need to do?

1. Parse the header if you want to identify different versions; otherwise, no action is required.
2. Choose the Webhook version when editing existing URLs or adding new ones. Check your webhook settings here.

Business logic changes

Overview

Update	Impact
Below are the new fields for importing and retrieving trackings: shipping_method location_id	API endpoint: - GET /trackings - GET /trackings/:id - POST /trackings - PUT /trackings/:id Tracking Webhook
Below are the new fields for retrieving trackings: carbon_emissions checkpoints[x].events	API endpoint: - GET /trackings - GET /trackings/:id Tracking Webhook
The existing field aftership_estimated_delivery_date.confidence_score will be replaced by the new field aftership_estimated_delivery_date.confidence_code.	API endpoint: - GET /trackings - GET /trackings/:id Tracking Webhook
The newly added field confidence_code will be available in the Response body for you to include when predicting the estimated delivery date.	API endpoint: - POST /estimated-delivery-date/predict-batch
Add validation check for existing fields origin_address.postal_code and destination_address.postal_code	API endpoint: - POST /estimated-delivery-date/predict-batch

New fields added

New field carbon_emissions

The model contains the total amount of carbon emissions generated by the shipment.

What do I need to do?

1. Parse the new field in the API response and the webhook body if you want to fetch the field; otherwise, no action is required.
2. This is a paid service available only for Enterprise plan users. Please contact your customer success manager if you need this.

New field events

The specific event(s) that ocurred to a shipment, such as, “returned_to_sender.” You can find the full list of events and reasons here (Beta Feature)

What do I need to do?

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

New field location_id

The location_id refers to the place where you fulfilled the items. If you provide a location_id, the system will automatically use it as the tracking's origin address.

What do I need to do?

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

New field shipping_method

It refers to the chosen method for delivering the package. Merchants typically offer various shipping methods to consumers during the checkout process, such as, Local Delivery, Free Express Worldwide Shipping, etc.

What do I need to do?

1. Pass the shipping_method while creating or updating the tracking if you have this information.
2. Parse the new field in the API response and the webhook body if you are interested in this information; otherwise, no action is required.

New field confidence_code

It indicates the confidence level and associated reason for an AI EDD prediction request. For the full confidence_code list, refer to this document. Example: 10001

What do I need to do?

1. Parse the new field in the API response if you are interested in this information; otherwise, no action is required.
2. Based on the returned confidence_code, you can decide whether to consider the estimated delivery date result for your actual application scenarios.

Updated API fields

Tracking AI EDD object structural change

We have replaced confidence_score with the new field confidence_code in the object.

What's the difference?

Change	Before	After
The confidence_score is replaced with confidence_code.	There are estimated_delivery_date, confidence_score, estimated_delivery_date_min, and estimated_delivery_date_max under the object.	There are estimated_delivery_date, confidence_code, estimated_delivery_date_min, and estimated_delivery_date_max under the object.

What do I need to do?

1. Parse the new field confidence_code in the API response and the webhook body if you are interested in this information; otherwise, no action is required.
2. Based on the returned confidence_code, you can decide whether to consider the estimated delivery date result for your actual application scenarios.

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 Tracking AI EDD, for invalid input we will return META.CODE 4008 to indicate the errors.

What do I need to do?

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

What if I don’t migrate?

If you choose not to migrate, the 2023-10 API will remain supported for at least 18 months. However, following the deprecation of the versioned API, API traffic will be redirected to the 2024-01 version.