Trackings
Create trackings, update trackings, and get tracking results.
Resource | Description |
---|---|
POST /trackings | Create a tracking. |
DELETE /trackings/:slug/:tracking_number | Delete a tracking. |
GET /trackings | Get tracking results of multiple trackings. |
GET /trackings/:slug/:tracking_number | Get tracking results of a single tracking. |
PUT /trackings/:slug/:tracking_number | Update a tracking. |
POST /trackings/:slug/:tracking_number/retrack | Retrack an expired tracking. Max 3 times per tracking. |
POST /trackings/:slug/:tracking_number/mark-as-completed | Mark a tracking as completed. The tracking won't auto update until retrack it. |
Pro Tip!
You can always use/:id
to replace /:slug/:tracking_number
.
e.g. DELETE /trackings/:id
You can also use%2F
to represent/
in your:tracking_number
e.g. GET /trackings/usps/ABCD%2F1234
to represent the tracking numberABCD/1234
You must pass other required parameterstracking_*
if a courier requires such information when the tracking is created.
e.g. GET /trackings/:slug/:tracking_number?tracking_ship_date=20200406
POST /trackings
Headers
aftership-api-key: YOUR_API_KEY
Content-Type: application/json
Parameters
Parameter | Type | Description |
---|---|---|
tracking_number | String | Tracking number of a shipment. Duplicated tracking numbers, tracking numbers with invalid tracking number format will not be accepted. We only accept tracking numbers with length from 4 to 100 We currently support the following characters in a tracking number:
|
Parameter | Type | Description |
---|---|---|
slug | String or Array | Unique code of each courier. Provide a single courier or array for a list of couriers. If you do not specify a slug, Aftership will automatically detect the courier based on the tracking number format and your selected couriers. Get a list of courier slug using GET /couriers |
tracking_postal_code | String | The postal code of receiver's address. Required by some couriers, such asdeutsch-post |
tracking_ship_date | String | Shipping date inYYYYMMDD format. Required by some couriers, such asdeutsch-post |
tracking_account_number | String | Account number of the shipper for a specific courier. Required by some couriers, such asdynamic-logistics |
tracking_key | String | Key of the shipment for a specific courier. Required by some couriers, such assic-teliway |
tracking_origin_country | String | Origin Country of the shipment for a specific courier. Required by some couriers, such asdhl |
tracking_destination_country | String | Destination Country of the shipment for a specific courier. Required by some couriers, such aspostnl-3s |
tracking_state | String | Located state of the shipment for a specific courier. Required by some couriers, such asstar-track-courier |
android | Array or String | Google cloud message registration IDs to receive the push notifications. Accept either array or comma separated as input. |
ios | Array or String | Apple iOS device IDs to receive the push notifications. Accept either array or comma separated as input. |
emails | Array or String | Email address(es) to receive email notifications. Accept either array or comma separated as input. |
smses | Array or String | Phone number(s) to receive sms notifications. Enter+ andarea code before phone number.Accept either array or comma separated as input. |
title | String | Title of the tracking. Default value astracking_number |
customer_name | String | Customer name of the tracking. |
origin_country_iso3 | String | Enter ISO Alpha-3 (three letters) to specify the origin of the shipment (e.g. USA for United States). |
destination_country_iso3 | String | Enter
ISO Alpha-3
(three letters) to specify the destination of the shipment (e.g. USA for United States). If you use postal service to send international shipments, AfterShip will automatically get tracking results at destination courier as well. |
order_id | String | Text field for order ID |
order_id_path | String | Text field for order path |
custom_fields | Hash | Custom fields that accept a hash with string, boolean or number fields |
note | String | Text field for the note |
language | String | Enter ISO 639-1 Language Code to specify the store, customer or order language. |
order_promised_delivery_date | String | Promised delivery date of an order inYYYY-MM-DD format. |
delivery_type | String | Shipment delivery type
|
pickup_location | String | Shipment pickup location for receiver |
pickup_note | String | Shipment pickup note for receiver |
Body
{
"tracking": {
"slug": "dhl",
"tracking_number": "123456789",
"title": "Title Name",
"smses": [
"+18555072509",
"+18555072501"
],
"emails": [
"[email protected]",
"[email protected]"
],
"order_id": "ID 1234",
"order_id_path": "http://www.aftership.com/order_id=1234",
"custom_fields": {
"product_name": "iPhone Case",
"product_price": "USD19.99"
},
"language": "en",
"order_promised_delivery_date": "2019-05-20",
"delivery_type": "pickup_at_store",
"pickup_location": "Flagship Store",
"pickup_note": "Reach out to our staffs when you arrive our stores for shipment pickup"
}
}
Headers
HTTP/1.1 201 Created Content-Type: application/json Connection: keep-alive Date: Mon, 10 Jun 2013 07:38:02 GMT
Attributes
Attribute | Type | Description |
---|---|---|
tracking | Hash of Tracking Object | Hash describes the tracking information. |
Attribute | Type | Description |
---|---|---|
created_at | DateTime | Date and time of the tracking created. |
updated_at | DateTime | Date and time of the tracking last updated. |
id | String | A unique identifier generated by AfterShip for the tracking. |
tracking_postal_code | String | The postal code of receiver's address. Required by some couriers, such asdeutsch-post |
tracking_ship_date | String | Shipping date inYYYYMMDD format. Required by some couriers, such asdeutsch-post |
tracking_account_number | String | Account number of the shipper for a specific courier. Required by some couriers, such asdynamic-logistics |
tracking_origin_country | String | Origin Country of the shipment for a specific courier. Required by some couriers, such asdhl |
tracking_destination_country | String | Destination Country of the shipment for a specific courier. Required by some couriers, such aspostnl-3s |
tracking_state | String | Located state of the shipment for a specific courier. Required by some couriers, such asstar-track-courier |
tracking_key | String | Key of the shipment for a specific courier. Required by some couriers, such assic-teliway |
slug | String | Unique code of courier. Get courier slug here |
active | Boolean | Whether or not AfterShip will continue tracking the shipments. Value is false when tag (status) is Delivered , Expired , or |
android | Array or String | Google cloud message registration IDs to receive the push notifications. Accept either array or comma separated as input. |
custom_fields | Hash | Custom fields of the tracking. |
customer_name | String | Customer name of the tracking. |
delivery_time | Number | Total delivery time in days. - Difference of 1st checkpoint time and delivered time for delivered shipments - Difference of 1st checkpoint time and current time for non-delivered shipments Value as 0 for pending shipments or delivered shipment with only one checkpoint. |
destination_country_iso3 | String | Destination country of the tracking. ISO Alpha-3 (three letters). If you use postal service to send international shipments, AfterShip will automatically get tracking results from destination postal service based on destination country. |
courier_destination_country_iso3 | String | Destination country of the tracking detected from the courier. ISO Alpha-3 (three letters). Value will be null if the courier doesn't provide the destination country. |
emails | Array | Email address(es) to receive email notifications. Comma separated for multiple values. |
expected_delivery | String | Expected delivery date (nullable). Available format: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DDTHH:MM:SS+TIMEZONE |
ios | Array or String | Apple iOS device IDs to receive the push notifications. Accept either array or comma separated as input. |
order_id | String | Text field for order ID |
order_id_path | String | Text field for order path |
origin_country_iso3 | String | Origin country of the tracking. ISO Alpha-3 (three letters). |
unique_token | String | The token to generate the direct tracking link: https://yourusername.aftership.com/unique_token or https://www.aftership.com/unique_token |
shipment_package_count | Number | Number of packages under the tracking (if any). |
shipment_type | String | Shipment type provided by carrier (if any). |
shipment_weight | Number | Shipment weight provied by carrier (if any) |
shipment_weight_unit | String | Weight unit provied by carrier, either in kg or lb (if any) |
last_updated_at | DateTime | Date and time the tracking was last updated |
shipment_pickup_date | DateTime | Date and time the tracking was picked up |
shipment_delivery_date | DateTime | Date and time the tracking was delivered |
subscribed_smses | Array | Phone number(s) subscribed to receive sms notifications. Comma separated for multiple values |
subscribed_emails | Array | Email address(es) subscribed to receive email notifications. Comma separated for multiple values |
signed_by | String | Signed by information for delivered shipment (if any). |
smses | Array | Phone number(s) to receive sms notifications. The phone number(s) to receive sms notifications. Phone number should begin with `+` and `Area Code` before phone number. Comma separated for multiple values. |
source | String | Source of how this tracking is added. |
tag | String | Current status of tracking. Values include
|
subtag | String | Current subtag of tracking. (See subtag definition) |
subtag_message | String | Normalized tracking message. (See subtag definition) |
title | String | Title of the tracking. |
tracked_count | Number | Number of attempts AfterShip tracks at courier's system. |
last_mile_tracking_supported | Boolean or Null | Indicates if the shipment is trackable till the final destination. Three possible values:
|
language | String or Null | Store, customer, or order language of the tracking. ISO 639-1 Language Code . |
return_to_sender | Boolean | Whether or not the shipment is returned to sender. Value istrue when any of its checkpoints has subtagException_010 (returning to sender) orException_011 (returned to sender). Otherwise value isfalse |
order_promised_delivery_date | String | Promised delivery date of an order inYYYY-MM-DD format. |
delivery_type | String | Shipment delivery type
|
pickup_location | String | Shipment pickup location for receiver |
pickup_note | String | Shipment pickup note for receiver |
courier_tracking_link | String | Official tracking URL of the courier (if any) |
courier_redirect_link | String | Delivery instructions (delivery date or address) can be modified by visiting the link if supported by a carrier. |
first_attempted_at | String or Null | date and time of the first attempt by the carrier to deliver the package to the addressee Available format: YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DDTHH:MM:SS+TIMEZONE |
checkpoints | Array of Checkpoint Object | Array of Hash describes the checkpoint information. |
Attribute | Type | Description |
---|---|---|
created_at | DateTime | Date and time of the tracking created. |
slug | String | The unique code of courier for this checkpoint message. Get courier slug here |
checkpoint_time | String | Date and time of the checkpoint, provided by courier. Value may be: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, or YYYY-MM-DDTHH:MM:SS+TIMEZONE |
location | String | Location info provided by carrier (if any) |
city | String | City info provided by carrier (if any) |
state | String | State info provided by carrier (if any) |
coordinates | Array | Deprecated as of March 2013 |
country_iso3 | String | Country ISO Alpha-3 (three letters) of the checkpoint |
country_name | String | Country name of the checkpoint, may also contain other location info. |
message | String | Checkpoint message |
tag | String | Current status of checkpoint. Values include
|
subtag | String | Current subtag of checkpoint. (See subtag definition) |
subtag_message | String | Normalized checkpoint message. (See subtag message definition) |
zip | String | Location info (if any) |
raw_tag | String | Checkpoint status provided by courier (if any) |
Body
{
"meta": {
"code": 201
},
"data": {
"tracking": {
"id": "5b766a5cc7c33c0e007de3c9",
"created_at": "2018-08-17T06:25:32+00:00",
"updated_at": "2018-08-17T06:25:32+00:00",
"last_updated_at": "2018-08-17T06:25:32+00:00",
"tracking_number": "1111111111111",
"slug": "fedex",
"active": true,
"android": [],
"custom_fields": null,
"customer_name": null,
"delivery_time": 0,
"destination_country_iso3": null,
"courier_destination_country_iso3": null,
"emails": [],
"expected_delivery": null,
"ios": [],
"note": null,
"order_id": null,
"order_id_path": null,
"origin_country_iso3": null,
"shipment_package_count": 0,
"shipment_pickup_date": null,
"shipment_delivery_date": null,
"shipment_type": null,
"shipment_weight": null,
"shipment_weight_unit": null,
"signed_by": null,
"smses": [],
"source": "api",
"tag": "Pending",
"subtag": "Pending_001",
"subtag_message": "Pending",
"title": "1111111111111",
"tracked_count": 0,
"last_mile_tracking_supported": null,
"language": null,
"unique_token": "deprecated",
"checkpoints": [],
"subscribed_smses": [],
"subscribed_emails": [],
"return_to_sender": false,
"tracking_account_number": null,
"tracking_origin_country": null,
"tracking_destination_country": null,
"tracking_key": null,
"tracking_postal_code": null,
"tracking_ship_date": null,
"tracking_state": null,
"order_promised_delivery_date": "2019-05-20",
"delivery_type": "pickup_at_store",
"pickup_location": "Flagship Store",
"pickup_note": "Contact shop keepers when you arrive our stores for shipment pickup",
"courier_tracking_link": "https://www.fedex.com/fedextrack/?tracknumbers=1111111111111&cntry_code=us",
"courier_redirect_link": "https://www.fedex.com/track?loc=en_US&tracknum=111111111111&requester=WT/trackdetails",
"first_attempted_at": null
}
}
}