Migration from legacy API to 2023-10

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

Currently SDKs are not supported for versioned APIs. Please stay tuned for further updates.

Breaking changes in version 2023-10

API Versioning changes

• API

  What's the difference?

  Change	Before	After
  Base URL	https://api.aftership.com/v4	https://api.aftership.com/tracking/2023-10
  New response header	-	New response header key as-api-version Example value 2023-10
  API Key header's key	- as-api-key ✅ - aftership-api-key ✅	- as-api-key ✅ - aftership-api-key ❌
  API Key header's value	The API keys that are marked as Legacy Tracking API access only are supported within the legacy API.	The API keys that are marked as Legacy Tracking API access only are no longer supported in the versioned API.

  What do I need to do?

  1. Update your application's code, replacing the base URL https://api.aftership.com/v4 with https://api.aftership.com/tracking/2023-10.
  2. Parse the header if you want to identify different versions; otherwise, no action is required.
  3. The request header aftership-api-key is no longer supported in the versioned API. Please use as-api-key instead.
  4. 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.

• Webhook

  What's the difference?

  Change	Before	After
  New request header	-	New request header key as-webhook-version Example value 2023-10

  What do I need to do?

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

Business logic changes

• Transit Time Revamp

  What's the difference?

  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.

  Change	Before	After
  Formula updated	Pick up date is considered as 1 transit day - For delivered shipments: Transit time (in days) = Delivered date - Pick-up date + 1 - For undelivered shipments: Transit time (in days) = Current date - Pick-up date + 1	Pick up date is not considered as 1 day in transit - For delivered shipments: Transit time (in days) = Delivered date - Pick-up date - For undelivered shipments: Transit time (in days) = Current date - Pick-up date
  Tracking model's field renamed	delivery_time	transit_time
  GET /trackings endpoint's query parameter renamed	delivery_time	transit_time

  What do I need to do?

  1. Update your application code, replacing delivery_time with transit_time if you parse it from the tracking API's response body or tracking webhook's request body.
  2. Update your application code, replacing delivery_time with transit_time if you use the API endpoint GET /trackings and query with the delivery_time parameter.
  3. 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.

• EDD source rename

  What's the difference?

  Change	Before	After
  The allowed values of first_estimated_delivery.source have been changed	"Carrier EDD", "AI Predictive EDD", "Custom EDD", "Order EDD"	"Carrier EDD", "AfterShip EDD", "Custom EDD", "Order EDD"
  The allowed values of latest_estimated_delivery.source have been changed	"Carrier EDD", "AI Predictive EDD", "Custom EDD", "Order EDD"	"Carrier EDD", "AfterShip EDD", "Custom EDD", "Order EDD"

  What do I need to do?

  1. Update your application code, replacing AI Predictive EDD with AfterShip EDD if you use first_estimated_delivery.source or latest_estimated_delivery.source from the tracking API's response body or tracking webhook's request body.

What if I don’t migrate?

If you choose not to migrate, the legacy API will remain supported for a minimum of 2 years. However, following the deprecation of the legacy API, API endpoints will result in a 404 Not Found error.