Trackings API - AfterShip Docs

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%2Fto represent/in your:tracking_number
e.g. GET /trackings/usps/ABCD%2F1234to 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

Headers

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

Parameters

Required 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: `A - Z` `0 - 9` `- (Hyphen)` `. (Period)` `_ (Underscore)` `/ (Slash)`

Optional Parameters

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 as`deutsch-post`
`tracking_ship_date`	String	Shipping date in`YYYYMMDD`format. Required by some couriers, such as`deutsch-post`
`tracking_account_number`	String	Account number of the shipper for a specific courier. Required by some couriers, such as`dynamic-logistics`
`tracking_key`	String	Key of the shipment for a specific courier. Required by some couriers, such as`sic-teliway`
`tracking_origin_country`	String	Origin Country of the shipment for a specific courier. Required by some couriers, such as`dhl`
`tracking_destination_country`	String	Destination Country of the shipment for a specific courier. Required by some couriers, such as`postnl-3s`
`tracking_state`	String	Located state of the shipment for a specific courier. Required by some couriers, such as`star-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`+` and`area code` before phone number. Accept either array or comma separated as input.
`title`	String	Title of the tracking. Default value as`tracking_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 in`YYYY-MM-DD`format.
`delivery_type`	String	Shipment delivery type `pickup_at_store` `pickup_at_courier` `door_to_door`
`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.

Tracking Object

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 as`deutsch-post`
`tracking_ship_date`	String	Shipping date in`YYYYMMDD`format. Required by some couriers, such as`deutsch-post`
`tracking_account_number`	String	Account number of the shipper for a specific courier. Required by some couriers, such as`dynamic-logistics`
`tracking_origin_country`	String	Origin Country of the shipment for a specific courier. Required by some couriers, such as`dhl`
`tracking_destination_country`	String	Destination Country of the shipment for a specific courier. Required by some couriers, such as`postnl-3s`
`tracking_state`	String	Located state of the shipment for a specific courier. Required by some couriers, such as`star-track-courier`
`tracking_key`	String	Key of the shipment for a specific courier. Required by some couriers, such as`sic-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 further updates for 30 days since last update.
`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
`order_date`	DateTime	Date and time of the order created
`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 `Pending` `InfoReceived` `InTransit` `OutForDelivery` `AttemptFail` `Delivered` `AvailableForPickup` `Exception` `Expired` (See tag definition)
`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: `true` `false` `null`
`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 is`true`when any of its checkpoints has subtag`Exception_010`(returning to sender) or`Exception_011`(returned to sender). Otherwise value is`false`
`order_promised_delivery_date`	String	Promised delivery date of an order in`YYYY-MM-DD`format.
`delivery_type`	String	Shipment delivery type `pickup_at_store` `pickup_at_courier` `door_to_door`
`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.

Checkpoint Object

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 `Pending` `InfoReceived` `InTransit` `OutForDelivery` `AttemptFail` `Delivered` `AvailableForPickup` `Exception` `Expired` (See tag definition)
`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,
            "order_date": 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
        }
    }
}