AfterShip Tracking API library for Java

This library allows you to quickly and easily use the AfterShip Tracking API via Java.

For updates to this library, see our GitHub release page.

If you need support using AfterShip products, please contact support@aftership.com.

Table of Contents

• AfterShip Tracking API library for Java
  • Table of Contents
  • Before you begin
    • API and SDK Version
  • Quick Start
    • Installation
  • Constructor
    • Example
  • Rate Limiter
  • Error Handling
    • Error List
  • Endpoints
    • /couriers
    • /courier-connections
    • /estimated-delivery-date
    • /trackings
  • Help
  • License

Before you begin

Before you begin to integrate:

• Create an AfterShip account.
• Create an API key.
• Install Java version Java 1.8 or later.

API and SDK Version

• SDK Version: 12.0.1
• API Version: 2026-07

Quick Start

Installation

<dependency><groupId>com.aftership</groupId><artifactId>tracking-sdk</artifactId><version>12.0.1</version></dependency>

Constructor

Create AfterShip instance with options

Name	Type	Required	Description
api_key	string	✔	Your AfterShip API key
auth_type	enum		Default value: AuthType.API_KEY AES authentication: AuthType.AES RSA authentication: AuthType.RSA
api_secret	string		Required if the authentication type is AuthType.AES or AuthType.RSA
domain	string		AfterShip API domain. Default value: https://api.aftership.com
user_agent	string		User-defined user-agent string, please follow RFC9110 format standard.
proxy	string		HTTP proxy URL to use for requests. Default value: null Example: http://192.168.0.100:8888
max_retry	number		Number of retries for each request. Default value: 2. Min is 0, Max is 10.
timeout	number		Timeout for each request in milliseconds.

Example

importcom.aftership.tracking.TrackingSdk;
importcom.aftership.tracking.model.GetTrackingByIdResponse;
importcom.aftership.tracking.tracking.TrackingResource;
publicclassApp {
publicstaticvoidmain(String[] args) {
try {
TrackingSdk.init(
"YOUR_API_KEY"
);
GetTrackingByIdResponseresponse = TrackingResource.getTrackingById()
.setId("valid_value")
.fetch();
System.out.println(response.getData());
} catch (Exceptione) {
e.printStackTrace();
}
}
}

Rate Limiter

See the Rate Limit to understand the AfterShip rate limit policy.

The API returns its current rate limit status in the headers of every response, and the SDK exposes these headers on both successful responses and rate-limited errors, so you can monitor your consumption proactively instead of waiting for 429 errors.

Header	Description
X-RateLimit-Limit	The rate limit ceiling for the current endpoint per second
X-RateLimit-Remaining	The number of requests left for the 1-second window
X-RateLimit-Reset	The Unix timestamp when the rate limit will be reset

Every successful response exposes getResponseHeader() (a Map<String, List<String>>) alongside getData(). Header names are case-insensitive per the HTTP spec, so normalize when looking up. Taking the Quick Start example above:

Map<String, List<String>> headers = response.getResponseHeader();
intremaining = headers.entrySet().stream()
.filter(e -> e.getKey().equalsIgnoreCase("x-ratelimit-remaining"))
.map(e -> Integer.parseInt(e.getValue().get(0)))
.findFirst()
.orElse(-1);
if (remaining >= 0 && remaining <= 1) {
// Throttle or defer lower-priority requests
}

When the rate limit is exceeded, the request fails with a 429 error that carries the same headers — see Error Handling.

Error Handling

The SDK will return an error object when there is any error during the request, with the following specification:

Name	Type	Description
message	string	Detail message of the error
code	enum	Error code enum for API Error.
meta_code	number	API response meta code.
status_code	number	HTTP status code.
response_body	string	API response body.
response_header	object	API response header.

Error List

code	meta_code	status_code	message
INVALID_REQUEST	400	400	The request was invalid or cannot be otherwise served.
INVALID_JSON	4001	400	Invalid JSON data.
TRACKING_ALREADY_EXIST	4003	400	Tracking already exists.
TRACKING_DOES_NOT_EXIST	4004	404	Tracking does not exist.
TRACKING_NUMBER_INVALID	4005	400	The value of tracking_number is invalid.
TRACKING_REQUIRED	4006	400	tracking object is required.
TRACKING_NUMBER_REQUIRED	4007	400	tracking_number is required.
VALUE_INVALID	4008	400	The value of [field_name] is invalid.
VALUE_REQUIRED	4009	400	[field_name] is required.
SLUG_INVALID	4010	400	The value of slug is invalid.
MISSING_OR_INVALID_REQUIRED_FIELD	4011	400	Missing or invalid value of the required fields for this courier. Besides tracking_number, also required: [field_name]
BAD_COURIER	4012	400	The error message will be one of the following:1. Unable to import shipment as the carrier is not on your approved list for carrier auto-detection. Add the carrier here: https://admin.aftership.com/settings/couriers2. Unable to import shipment as we don't recognize the carrier from this tracking number.3. Unable to import shipment as the tracking number has an invalid format.4. Unable to import shipment as this carrier is no longer supported.5. Unable to import shipment as the tracking number does not belong to a carrier in that group.
INACTIVE_RETRACK_NOT_ALLOWED	4013	400	Retrack is not allowed. You can only retrack an inactive tracking.
NOTIFICATION_REQUIRED	4014	400	notification object is required.
ID_INVALID	4015	400	The value of id is invalid.
RETRACK_ONCE_ALLOWED	4016	400	Retrack is not allowed. You can only retrack each shipment once.
TRACKING_NUMBER_FORMAT_INVALID	4017	400	The format of tracking_number is invalid.
API_KEY_INVALID	401	401	The API Key is invalid.
REQUEST_NOT_ALLOWED	403	403	The request is understood, but it has been refused or access is not allowed.
NOT_FOUND	404	404	The URI requested is invalid or the resource requested does not exist.
TOO_MANY_REQUEST	429	429	You have exceeded the API call rate limit. The default limit is 10 requests per second.
INTERNAL_ERROR	500	500	Something went wrong on AfterShip's end.
INTERNAL_ERROR	502	502	Something went wrong on AfterShip's end.
INTERNAL_ERROR	503	503	Something went wrong on AfterShip's end.
INTERNAL_ERROR	504	504	Something went wrong on AfterShip's end.

 |

Endpoints

The AfterShip SDK has the following resource which are exactly the same as the API endpoints:

• CourierResource
  • Get couriers
  • Detect courier
• CourierConnectionResource
  • Get courier connections
  • Create courier connections
  • Get courier connection by id
  • Update courier connection by id
  • Delete courier connection by id
• EstimatedDeliveryDateResource
  • Prediction for the Estimated Delivery Date
  • Batch prediction for the Estimated Delivery Date
• TrackingResource
  • Get trackings
  • Create a tracking
  • Get a tracking by ID
  • Update a tracking by ID
  • Delete a tracking by ID
  • Retrack an expired tracking by ID
  • Mark tracking as completed by ID

/couriers

GET /couriers

GetCouriersResponseresponse = CourierResource.getCouriers()
.fetch();
System.out.println(response.getData());

POST /couriers/detect

DetectCourierRequestrequest = newDetectCourierRequest();
request.setTrackingNumber("valid_value");
DetectCourierResponseresponse = CourierResource.detectCourier()
.setDetectCourierRequest(request)
.create();
System.out.println(response.getData());

/courier-connections

GET /courier-connections

GetCourierConnectionsResponseresponse = CourierConnectionResource.getCourierConnections()
.fetch();
System.out.println(response.getData());

POST /courier-connections

PostCourierConnectionsRequestrequest = newPostCourierConnectionsRequest();
request.setCourierSlug("valid_value");
request.setCredentials();
PostCourierConnectionsResponseresponse = CourierConnectionResource.postCourierConnections()
.setPostCourierConnectionsRequest(request)
.create();
System.out.println(response.getData());

GET /courier-connections/{id}

GetCourierConnectionsByIdResponseresponse = CourierConnectionResource.getCourierConnectionsById()
.setId("valid_value")
.fetch();
System.out.println(response.getData());

PATCH /courier-connections/{id}

PutCourierConnectionsByIdRequestrequest = newPutCourierConnectionsByIdRequest();
request.setCredentials();
PutCourierConnectionsByIdResponseresponse = CourierConnectionResource.putCourierConnectionsById()
.setId("valid_value")
.setPutCourierConnectionsByIdRequest(request)
.update();
System.out.println(response.getData());

DELETE /courier-connections/{id}

DeleteCourierConnectionsByIdResponseresponse = CourierConnectionResource.deleteCourierConnectionsById()
.setId("valid_value")
.delete();
System.out.println(response.getData());

/estimated-delivery-date

POST /estimated-delivery-date/predict

EstimatedDeliveryDateRequestrequest = newEstimatedDeliveryDateRequest();
request.setSlug("valid_value");
EstimatedDeliveryDateRequestOriginAddressoriginAddress = newEstimatedDeliveryDateRequestOriginAddress();
request.setOriginAddress(originAddress);
EstimatedDeliveryDateRequestDestinationAddressdestinationAddress = newEstimatedDeliveryDateRequestDestinationAddress();
request.setDestinationAddress(destinationAddress);
PredictResponseresponse = EstimatedDeliveryDateResource.predict()
.setPredictRequest(request)
.create();
System.out.println(response.getData());

POST /estimated-delivery-date/predict-batch

PredictBatchRequestrequest = newPredictBatchRequest();
PredictBatchResponseresponse = EstimatedDeliveryDateResource.predictBatch()
.setPredictBatchRequest(request)
.create();
System.out.println(response.getData());

/trackings

GET /trackings

GetTrackingsResponseresponse = TrackingResource.getTrackings()
.fetch();
System.out.println(response.getData());

POST /trackings

CreateTrackingRequestrequest = newCreateTrackingRequest();
request.setTrackingNumber("valid_value");
CreateTrackingResponseresponse = TrackingResource.createTracking()
.setCreateTrackingRequest(request)
.create();
System.out.println(response.getData());

GET /trackings/{id}

GetTrackingByIdResponseresponse = TrackingResource.getTrackingById()
.setId("valid_value")
.fetch();
System.out.println(response.getData());

PUT /trackings/{id}

UpdateTrackingByIdRequestrequest = newUpdateTrackingByIdRequest();
UpdateTrackingByIdResponseresponse = TrackingResource.updateTrackingById()
.setId("valid_value")
.setUpdateTrackingByIdRequest(request)
.update();
System.out.println(response.getData());

DELETE /trackings/{id}

DeleteTrackingByIdResponseresponse = TrackingResource.deleteTrackingById()
.setId("valid_value")
.delete();
System.out.println(response.getData());

POST /trackings/{id}/retrack

RetrackTrackingByIdResponseresponse = TrackingResource.retrackTrackingById()
.setId("valid_value")
.create();
System.out.println(response.getData());

POST /trackings/{id}/mark-as-completed

MarkTrackingCompletedByIdRequestrequest = newMarkTrackingCompletedByIdRequest();
MarkTrackingCompletedByIdResponseresponse = TrackingResource.markTrackingCompletedById()
.setId("valid_value")
.setMarkTrackingCompletedByIdRequest(request)
.create();
System.out.println(response.getData());

Help

If you get stuck, we're here to help:

• Issue Tracker for questions, feature requests, bug reports and general discussion related to this package. Try searching before you create a new issue.
• Contact AfterShip official support via support@aftership.com

License

Copyright (c) 2025 AfterShip

Licensed under the MIT license.