Trackings

Create trackings, update trackings, and get tracking results.

Pro Tip!

You can always use/:id to replace /:slug/:tracking_number.
e.g. DELETE /trackings/:id


GET /trackings

Headers

aftership-api-key: YOUR_API_KEY
Content-Type: application/json

Parameters

Optional Parameters
ParameterTypeDescription
pageNumberPage to show. (Default: 1)
limitNumberNumber of trackings each page contain. (Default: 100, Max: 200)
keywordStringSearch the content of the tracking record fields:tracking_number,  title,  order_id,  customer_name,  custom_fields,  order_id,  emails,  smses
slugStringUnique courier code Use comma for multiple values. (Example: dhl,ups,usps)
delivery_timeNumberTotal 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.
originStringOrigin country of trackings. Use ISO Alpha-3 (three letters). Use comma for multiple values. (Example: USA,HKG)
destinationStringDestination country of trackings. Use ISO Alpha-3 (three letters). Use comma for multiple values. (Example: USA,HKG)
tagStringCurrent status of tracking. Values include Pending,  InfoReceived,  InTransit,  OutForDelivery,  AttemptFail,  Delivered,  Exception,  Expired(See tag definition)
created_at_minDateTimeStart date and time of trackings created. AfterShip only stores data of 90 days.
(Defaults: 30 days ago, Example: 2013-03-15T16:41:56+08:00)
created_at_maxDateTimeEnd date and time of trackings created.
(Defaults: now, Example: 2013-04-15T16:41:56+08:00)
fieldsStringList of fields to include in the response. Use comma for multiple values. Fields to include: title,  order_id,  tag,  checkpoints,  checkpoint_time,  message,  country_name
Defaults: none, Example: title,order_id
langStringDefault: '' / Example: 'en'
Support Chinese to English translation for  china-ems  and  china-post  only

Headers

HTTP/1.1 200 OK
Content-Type: application/json
Connection: keep-alive
Date: Mon, 10 Jun 2013 07:38:02 GMT

Attributes

Attributes
AttributeTypeDescription
limitNumberNumber of trackings each page contain. (Default: 100)
countNumberTotal number of matched trackings, max. number is 10,000
pageNumberPage to show. (Default: 1)
trackingsArray of Tracking ObjectArray of Hash describes the tracking information.
Tracking Object
AttributeTypeDescription
created_atDateTimeDate and time of the tracking created.
updated_atDateTimeDate and time of the tracking last updated.
idStringA unique identifier generated by AfterShip for the tracking.
tracking_postal_codeStringThe postal code of receiver's address. Required by some couriers, such asdeutsch-post
tracking_ship_dateStringShipping date inYYYYMMDDformat. Required by some couriers, such asdeutsch-post
tracking_account_numberStringAccount number of the shipper for a specific courier. Required by some couriers, such asdynamic-logistics
tracking_origin_countryStringOrigin Country of the shipment for a specific courier. Required by some couriers, such asdhl
tracking_destination_countryStringDestination Country of the shipment for a specific courier. Required by some couriers, such aspostnl-3s
tracking_stateStringLocated state of the shipment for a specific courier. Required by some couriers, such asstar-track-courier
tracking_keyStringKey of the shipment for a specific courier. Required by some couriers, such assic-teliway
slugStringUnique code of courier. Get courier slug here
activeBooleanWhether or not AfterShip will continue tracking the shipments. Value is false when tag (status) is DeliveredExpired, or further updates for 30 days since last update.
androidArray or StringGoogle cloud message registration IDs to receive the push notifications.
Accept either array or comma separated as input.
custom_fieldsHashCustom fields of the tracking.
customer_nameStringCustomer name of the tracking.
delivery_timeNumberTotal 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_iso3StringDestination 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_iso3StringDestination 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.
emailsArrayEmail address(es) to receive email notifications. Comma separated for multiple values.
expected_deliveryStringExpected delivery date (if any).
Empty String,
YYYY-MM-DD,
YYYY-MM-DDTHH:MM:SS, or
YYYY-MM-DDTHH:MM:SS+TIMEZONE
iosArray or StringApple iOS device IDs to receive the push notifications.
Accept either array or comma separated as input.
order_idStringText field for order ID
order_id_pathStringText field for order path
origin_country_iso3StringOrigin country of the tracking. ISO Alpha-3 (three letters).
unique_tokenStringThe token to generate the direct tracking link: 
https://yourusername.aftership.com/unique_token or 
https://www.aftership.com/unique_token
shipment_package_countNumberNumber of packages under the tracking.
shipment_typeStringShipment type provided by carrier (if any).
shipment_weightNumberShipment weight provied by carrier (if any)
shipment_weight_unitStringWeight unit provied by carrier, either in 
kg or lb (if any)
last_updated_atDateTimeDate and time the tracking was last updated
shipment_pickup_dateDateTimeDate and time the tracking was picked up
shipment_delivery_dateDateTimeDate and time the tracking was delivered
subscribed_smsesArrayPhone number(s) subscribed to receive sms notifications. Comma separated for multiple values
subscribed_emailsArrayEmail address(es) subscribed to receive email notifications. Comma separated for multiple values
signed_byStringSigned by information for delivered shipment (if any).
smsesArrayPhone 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.
sourceStringSource of how this tracking is added.
tagStringCurrent status of tracking. Values include 
  • Pending
  • InfoReceived
  • InTransit
  • OutForDelivery
  • AttemptFail
  • Delivered
  • Exception
  • Expired
(See tag definition)
subtagStringCurrent subtag of tracking. (See subtag definition)
subtag_messageStringNormalized tracking message. (See subtag definition)
titleStringTitle of the tracking.
tracked_countNumberNumber of attempts AfterShip tracks at courier's system.
last_mile_tracking_supportedBoolean or NullIndicates if the shipment is trackable till the final destination.
Three possible values:
  • true
  • false
  • null
languageString or NullStore, customer, or order language of the tracking. ISO 639-1 Language Code .
return_to_senderBooleanWhether or not the shipment is returned to sender. Value istruewhen any of its checkpoints has subtagException_010(returning to sender) orException_011(returned to sender). Otherwise value isfalse
checkpointsArray of Checkpoint ObjectArray of Hash describes the checkpoint information.
Checkpoint Object
AttributeTypeDescription
created_atDateTimeDate and time of the tracking created.
slugStringThe unique code of courier for this checkpoint message. Get courier slug here
checkpoint_timeStringDate and time of the checkpoint, provided by courier. Value may be:
Empty String,
YYYY-MM-DD,
YYYY-MM-DDTHH:MM:SS, or
YYYY-MM-DDTHH:MM:SS+TIMEZONE
locationStringLocation info provided by carrier (if any)
cityStringCity info provided by carrier (if any)
stateStringState info provided by carrier (if any)
coordinatesArrayDeprecated as of March 2013
country_iso3StringCountry ISO Alpha-3 (three letters) of the checkpoint
country_nameStringCountry name of the checkpoint, may also contain other location info.
messageStringCheckpoint message
tagStringCurrent status of checkpoint. Values include 
  • Pending
  • InfoReceived
  • InTransit
  • OutForDelivery
  • AttemptFail
  • Delivered
  • Exception
  • Expired
(See tag definition)
subtagStringCurrent subtag of checkpoint. (See subtag definition)
subtag_messageStringNormalized checkpoint message. (See subtag message definition)
zipStringLocation info (if any)

Body

{
    "meta": {
        "code": 200
    },
    "data": {
        "page": 1,
        "limit": 100,
        "count": 3,
        "keyword": "",
        "slug": "",
        "origin": [],
        "destination": [],
        "tag": "",
        "fields": "",
        "created_at_min": "2018-05-19T06:23:00+00:00",
        "created_at_max": "2018-08-17T06:23:59+00:00",
        "last_updated_at": null,
        "return_to_sender": [],
        "courier_destination_country_iso3": [],
        "trackings": [
            {
                "id": "5b74f4958776db0e00b6f5ed",
                "created_at": "2018-08-16T03:50:45+00:00",
                "updated_at": "2018-08-16T03:50:54+00:00",
                "last_updated_at": "2018-08-16T03:50:53+00:00",
                "tracking_number": "1111111111111",
                "slug": "fedex",
                "active": false,
                "android": [],
                "custom_fields": null,
                "customer_name": null,
                "delivery_time": 2,
                "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": "USA",
                "shipment_package_count": 1,
                "shipment_pickup_date": "2018-07-31T06:00:00",
                "shipment_delivery_date": "2018-08-01T17:19:47",
                "shipment_type": "FedEx Home Delivery",
                "shipment_weight": null,
                "shipment_weight_unit": "kg",
                "signed_by": "Signature not required",
                "smses": [],
                "source": "web",
                "tag": "Delivered",
                "subtag": "Delivered_001",
                "subtag_message": "Delivered",
                "title": "1111111111111",
                "tracked_count": 1,
                "last_mile_tracking_supported": null,
                "language": null,
                "unique_token": "deprecated",
                "checkpoints": [
                    {
                        "slug": "fedex",
                        "city": null,
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": null,
                        "country_name": null,
                        "message": "Shipment information sent to FedEx",
                        "country_iso3": null,
                        "tag": "InfoReceived",
                        "subtag": "InfoReceived_001",
                        "subtag_message": "Info Received",
                        "checkpoint_time": "2018-07-31T10:33:00-04:00",
                        "coordinates": [],
                        "state": null,
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "BROOKLYN",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "BROOKLYN, NY",
                        "country_name": null,
                        "message": "Picked up",
                        "country_iso3": null,
                        "tag": "InTransit",
                        "subtag": "InTransit_002",
                        "subtag_message": "Acceptance scan",
                        "checkpoint_time": "2018-07-31T16:47:00-04:00",
                        "coordinates": [],
                        "state": "NY",
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "BROOKLYN",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "BROOKLYN, NY",
                        "country_name": null,
                        "message": "Arrived at FedEx location",
                        "country_iso3": null,
                        "tag": "InTransit",
                        "subtag": "InTransit_003",
                        "subtag_message": "Arrival scan",
                        "checkpoint_time": "2018-07-31T17:51:00-04:00",
                        "coordinates": [],
                        "state": "NY",
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "BROOKLYN",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "BROOKLYN, NY",
                        "country_name": null,
                        "message": "Left FedEx origin facility",
                        "country_iso3": null,
                        "tag": "InTransit",
                        "subtag": "InTransit_007",
                        "subtag_message": "Departure Scan",
                        "checkpoint_time": "2018-07-31T20:29:29-04:00",
                        "coordinates": [],
                        "state": "NY",
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "KEASBEY",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "KEASBEY, NJ",
                        "country_name": null,
                        "message": "Shipment exception - Barcode label unreadable and replaced",
                        "country_iso3": null,
                        "tag": "Exception",
                        "subtag": "Exception_001",
                        "subtag_message": "Exception",
                        "checkpoint_time": "2018-08-01T00:13:04-04:00",
                        "coordinates": [],
                        "state": "NJ",
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "KEASBEY",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "KEASBEY, NJ",
                        "country_name": null,
                        "message": "Arrived at FedEx location",
                        "country_iso3": null,
                        "tag": "InTransit",
                        "subtag": "InTransit_003",
                        "subtag_message": "Arrival scan",
                        "checkpoint_time": "2018-08-01T00:17:00-04:00",
                        "coordinates": [],
                        "state": "NJ",
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "KEASBEY",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "KEASBEY, NJ",
                        "country_name": null,
                        "message": "Departed FedEx location",
                        "country_iso3": null,
                        "tag": "InTransit",
                        "subtag": "InTransit_007",
                        "subtag_message": "Departure Scan",
                        "checkpoint_time": "2018-08-01T04:30:14-04:00",
                        "coordinates": [],
                        "state": "NJ",
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "DAYTON",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "DAYTON, NJ",
                        "country_name": null,
                        "message": "At local FedEx facility",
                        "country_iso3": null,
                        "tag": "InTransit",
                        "subtag": "InTransit_007",
                        "subtag_message": "Departure Scan",
                        "checkpoint_time": "2018-08-01T06:29:00-04:00",
                        "coordinates": [],
                        "state": "NJ",
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "DAYTON",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "DAYTON, NJ",
                        "country_name": null,
                        "message": "Arrived at FedEx location",
                        "country_iso3": null,
                        "tag": "InTransit",
                        "subtag": "InTransit_003",
                        "subtag_message": "Arrival scan",
                        "checkpoint_time": "2018-08-01T06:31:00-04:00",
                        "coordinates": [],
                        "state": "NJ",
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "DAYTON",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "DAYTON, NJ",
                        "country_name": null,
                        "message": "On FedEx vehicle for delivery",
                        "country_iso3": null,
                        "tag": "OutForDelivery",
                        "subtag": "OutForDelivery_001",
                        "subtag_message": "Out for Delivery",
                        "checkpoint_time": "2018-08-01T06:41:00-04:00",
                        "coordinates": [],
                        "state": "NJ",
                        "zip": null
                    },
                    {
                        "slug": "fedex",
                        "city": "Deal",
                        "created_at": "2018-08-16T03:50:47+00:00",
                        "location": "Deal, NJ",
                        "country_name": null,
                        "message": "Delivered - Left at front door. Signature Service not requested.",
                        "country_iso3": null,
                        "tag": "Delivered",
                        "subtag": "Delivered_001",
                        "subtag_message": "Delivered",
                        "checkpoint_time": "2018-08-01T13:19:47-04:00",
                        "coordinates": [],
                        "state": "NJ",
                        "zip": null
                    }
                ],
                "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
            },
            {
                "id": "5b0516676a810a1400eb5c1c",
                "created_at": "2018-05-23T07:21:11+00:00",
                "updated_at": "2018-06-22T07:21:57+00:00",
                "last_updated_at": "2018-06-22T07:21:57+00:00",
                "tracking_number": "2222222222222",
                "slug": "ups",
                "active": false,
                "android": [],
                "custom_fields": null,
                "customer_name": null,
                "delivery_time": 0,
                "destination_country_iso3": null,
                "courier_destination_country_iso3": null,
                "emails": [
                    "asdfasdf@asdf.com"
                ],
                "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": [
                    "+85261234567",
                    "+85291234567"
                ],
                "source": "web",
                "tag": "Expired",
                "subtag": "Expired_001",
                "subtag_message": "Expired",
                "title": "12ASDF121312",
                "tracked_count": 42,
                "last_mile_tracking_supported": null,
                "language": null,
                "unique_token": "deprecated",
                "checkpoints": [],
                "subscribed_smses": [
                    "+85222222222",
                    "+8533333333"
                ],
                "subscribed_emails": [
                    "yoyo@yoyo.com",
                    "yoyo2@yoyo.com"
                ],
                "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
            },
            {
                "id": "5b04e2cbd560281400b70284",
                "created_at": "2018-05-23T03:40:59+00:00",
                "updated_at": "2018-07-11T08:34:34+00:00",
                "last_updated_at": "2018-07-11T08:34:34+00:00",
                "tracking_number": "1231231231231",
                "slug": "usps",
                "active": false,
                "android": [],
                "custom_fields": null,
                "customer_name": null,
                "delivery_time": 0,
                "destination_country_iso3": null,
                "courier_destination_country_iso3": null,
                "emails": [
                    "asdfsaddf@asdf.com",
                    "asdfasd@asdfasdfasdfasd.com"
                ],
                "expected_delivery": null,
                "ios": [],
                "note": null,
                "order_id": null,
                "order_id_path": null,
                "origin_country_iso3": "USA",
                "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": [
                    "+85291234567",
                    "+85291234566"
                ],
                "source": "web",
                "tag": "Expired",
                "subtag": "Expired_001",
                "subtag_message": "Expired",
                "title": "1231231231231",
                "tracked_count": 1,
                "last_mile_tracking_supported": null,
                "language": null,
                "unique_token": "deprecated",
                "checkpoints": [],
                "subscribed_smses": [
                    "+85290001111"
                ],
                "subscribed_emails": [
                    "asdfasdf@asdf.com"
                ],
                "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
            }
        ]
    }
}