Migration from 2024-01 API to 2024-04

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

Breaking changes

API changes

What's the difference?

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

What do I need to do?

1. Update your application's code, replacing the base URL from https://api.aftership.com/tracking/2024-01 to https://api.aftership.com/tracking/2024-04.
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	2024-01	2024-04

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 retrieving trackings: failed_delivery_attempts signature_requirement	API endpoint: - GET /trackings - GET /trackings/:id - GET /trackings/:slug/:tracking_number - POST /trackings - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number Tracking Webhook
Below is the query parameter added for get trackings: order_id	API endpoint: - GET /trackings
The existing array field checkpoints[x].coordinates will be deprecated and replaced with checkpoints[x].coordinate.	API endpoint: - GET /trackings - GET /trackings/:id - GET /trackings/:slug/:tracking_number - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number Tracking Webhook
New event code and reason code are added: Event code picked_up signed_by_customer Reason code outside_delivery_limits not_what_customer_ordered package_oversized_overweight	API endpoint: - GET /trackings - GET /trackings/:id - GET /trackings/:slug/:tracking_number - PUT /trackings/:id - PUT /trackings/:slug/:tracking_number Tracking Webhook

New fields added

New field failed_delivery_attempts

This field dynamically tracks failed delivery attempts during the delivery of the shipment, allowing you to identify the carriers responsible for the most failures, analyze the root cause, and improve carriers' delivery SOP.

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

New field signature_requirement

Signature requirement is a service offered by shipping carriers that provides an extra level of security and proof of delivery for shipments. When using the service, the recipient's signature is required upon delivery.

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

Updated API fields

Coordinates field replaced by Coordinate

The existing array field checkpoints[x].coordinates will be deprecated and replaced with object checkpoints[x].coordinate.

What's the difference?

Change	Before	After
The existing array field checkpoints[x].coordinates will be deprecated and replaced with checkpoints[x].coordinate.	coordinates Array[number] Example: [51.165691,10.451526]	coordinate Object Example: {"latitude": 51.165691,"longitude": 10.451526 }

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.

What if I don’t migrate?

If you choose not to migrate, the 2024-01 API will remain supported for at least 18 months. However, API traffic will eventually be redirected to the 2024-04 version following the deprecation of the versioned API. Learn more about API versioning.