Migration from 2026-01 API & Webhook to 2026-07
The following guide will help you migrate the API and webhook from version 2026-01 to version 2026-07.
1. General API Changes
1.1 Endpoint Change
What's the difference?
| Change | Before | After |
|---|---|---|
| Base URL | https://api.aftership.com/tracking/2026-01 | https://api.aftership.com/tracking/2026-07 |
as-api-version response header value | 2026-01 | 2026-07 |
as-webhook-version request header value | 2026-01 | 2026-07 |
What do I need to do?
Make the following updates to your application's code:
- Replace the base URL from https://api.aftership.com/tracking/2026-01 to https://api.aftership.com/tracking/2026-07.
- When editing existing URLs or adding new ones, select the correct Webhook version. Please review your webhook settings for verification.
- Parse the header to distinguish between different versions. Otherwise, no action is required.
2. New SDK Added
3. New Delivery Sub-statuses
10 new delivery sub-statuses have been added. For a comprehensive list, refer to this document.
| Sub-status code | Sub-status message | Description |
|---|---|---|
| Delivered_005 | Delivered to neighbor | The shipment was delivered to a neighbor. |
| Exception_016 | Delayed (Processing issue) | The shipment has experienced a delay due to a processing issue within the carrier network. This could be a vehicle issue, sorting error, misroute, etc. |
| Exception_017 | Delayed (Extreme weather) | The shipment has experienced a delay due to extreme weather conditions such as storms, floods, or heavy snow. |
| Exception_018 | Incorrect missing documents | The shipment has been placed on hold due to inaccurate or missing documents required by regulatory agencies. It may be delayed or returned to sender if not resolved. |
| Exception_019 | Delayed (Late flight) | The shipment has experienced a delay due to a delayed or rescheduled flight. |
| Exception_020 | Shipment cancelled | The shipment was voided or canceled by the sender or carrier. |
| Exception_021 | Shipment disposed | The shipment was destroyed or discarded, usually due to it being prohibited, damaged, or unable to be delivered or returned. |
| InTransit_011 | Import customs clearance completed | The shipment has successfully cleared import customs. |
| InTransit_012 | Import customs clearance started | The shipment is now undergoing import customs clearance. |
| InTransit_013 | Drop off for carrier pickup | The shipment has been dropped off at a designated location (such as a drop box, service point, or post office) and is awaiting carrier pickup. |
What do I need to do?
- Parse the new sub-status codes in the API response and the webhook body if you want to retrieve data from the new sub-statuses. Otherwise, no further action is required.
4. Tracking Model Fields Added
4.1 Shipment dimensions field added
The new shipment_dimensions field returns the physical dimensions of the package, including length, width, and height.
What do I need to do?
- Parse the
shipment_dimensionsfield in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.
4.2 Checkpoint hash field added
The new checkpoints[].hash field returns a unique hash identifier for each checkpoint event, which can be used for deduplication.
What do I need to do?
- Parse the
checkpoints[].hashfield in the API response and the webhook body if you want to retrieve data from the new field. Otherwise, no further action is required.
4.3 Customer id field added
The new customers[].id field stores the customer's identifier on the merchant or platform (for example, Shopify) side. This field is both readable and writable.
What do I need to do?
- Provide
customers[].idin the API request if you want to associate a customer with their platform ID. - Parse the field in the API response and the webhook body if you want to retrieve the data. Otherwise, no further action is required.
4.4 Proof of delivery field added
The new proof_of_delivery field returns an array of proof of delivery (POD) records, such as a signature or photo captured upon successful delivery. This field returns a value only after the feature is enabled. Please contact your customer success manager if you'd like to know more.
| Field | R/W | Description |
|---|---|---|
proof_of_delivery[].type | Read-only | The file type of the proof of delivery record. Currently, only images are supported. |
proof_of_delivery[].url | Read-only | The URL of the proof of delivery record. |
What do I need to do?
- Parse the
proof_of_deliveryfield in the API response and the webhook body if you want to retrieve data. Otherwise, no further action is required.
4.5 Multi-piece shipment fields added
Multi-piece shipment (MPS) refers to a scenario where a single shipment order is fulfilled by multiple physical packages. Each piece has its own carrier-assigned tracking number, but all pieces belong to the same shipment. The following new fields expose MPS metadata. These fields return a value only after the feature is enabled. To enable, go to AfterShip Tracking Admin > Settings > Shipment tracking > Multi-piece shipments.
| Field | R/W | Description |
|---|---|---|
multi_piece_info | Read-only | Multi-piece shipment metadata describing a group of packages that belong to the same shipment. This commonly occurs when an order is too large to fit in one box, or when items are packed separately for handling reasons. This field returns a value only when your subscription plan includes the multi-piece feature. |
multi_piece_info.type | Read-only | Indicates the role of the current tracking object within the multi-piece shipment: master (the main tracking number representing the entire shipment; it may not always exist) or child (a sub-tracking number belonging to one of the pieces in the shipment) |
multi_piece_info.pieces[] | Read-only | List of all pieces in the MPS, including the master and all child pieces |
multi_piece_info.pieces[].tracking_id | Read-only | AfterShip system-assigned unique identifier for the piece |
multi_piece_info.pieces[].tracking_number | Read-only | Carrier-assigned tracking number for the piece |
multi_piece_info.pieces[].type | Read-only | Type of the piece within the MPS: master or child |
multi_piece_info.pieces[].trackable | Read-only | Indicates whether the tracking number can be used to retrieve tracking updates on the carrier's side. If not, it means the carrier can only return a child tracking number, but cannot independently provide tracking updates for the sub-shipment. In this case, it is not recommended for you to import this tracking number into AfterShip for tracking. Possible values: true or false |
What do I need to do?
- Parse the new fields in the API response and the webhook body if you want to retrieve data. Otherwise, no further action is required.
4.6 Shipment direction and linked shipment fields added
The following new fields indicate the business direction of a shipment and link forward and return shipments together. The return_shipment and forward_shipment fields return a value only after the feature is enabled. To enable, go to AfterShip Tracking Admin > Settings > Shipment tracking > Return shipments.
| Field | R/W | Description |
|---|---|---|
shipment_direction | Read/Write | Indicates the business direction of the shipment in the e-commerce fulfillment lifecycle: forward (a forward, outbound-to-customer shipment created for order fulfillment) or return (a return, customer-to-merchant shipment created for after-sales return or exchange). This field is populated in either of the following cases: 1. You explicitly provided it when creating the tracking. 2. AfterShip automatically detected a linked forward or return shipment. It also determines which related shipment object (forward_shipment or return_shipment) may appear in the response. |
return_shipment | Read-only | The associated return shipment linked to the current outbound shipment. This field is only present when shipment_direction = "forward" and AfterShip has detected a linked return shipment. |
return_shipment.id | Read-only | AfterShip system-assigned unique identifier of the linked return shipment. This field is only returned when both of the following conditions are met: 1. AfterShip has detected a linked return shipment. 2. The Auto-import for return shipments feature is enabled in your AfterShip account. When auto-import is disabled, id will not be returned, but tracking_number and slug may still be present. To enable this feature, go to AfterShip Tracking Admin > Settings > Shipment Tracking > Return Shipments. |
return_shipment.tracking_number | Read-only | Carrier-assigned tracking number of the linked return shipment. Can be used together with return_shipment.slug to create a new tracking subscription and retrieve the return shipment's checkpoints. |
return_shipment.slug | Read-only | Carrier slug (identifier) of the linked return shipment. Can be used together with return_shipment.tracking_number to subscribe to tracking updates for the return shipment. |
forward_shipment | Read-only | The original outbound shipment linked to this return. Use this to trace a return back to its source delivery. This field is only present when shipment_direction = "return" and AfterShip has detected a linked forward shipment. |
forward_shipment.id | Read-only | AfterShip system-assigned unique identifier of the linked outbound shipment |
What do I need to do?
- Provide
shipment_directionin the API request if you want to label a shipment as forward or return. - Parse the new fields in the API response and the webhook body if you want to retrieve data. Otherwise, no further action is required.
5. Tracking Endpoints Common Changes
5.1 New sub-statuses
Please refer to the New Delivery Sub-statuses section of the guide.
5.2 Fields added in tracking
Please refer to the Tracking Model Fields Added section of the guide.
6. What if I don't migrate?
After January 7, 2029, requests made to the 2026-01 version will be automatically redirected to the oldest supported API version. While this redirection aims to minimize disruptions, it may not fully support all functionalities available in the newer versions. We recommend migrating at your earliest convenience.