Documentation

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


POST /trackings

Headers

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

Parameters

Required Parameters
ParameterTypeDescription
tracking_numberStringTracking number of a shipment. Duplicate tracking numbers, or tracking number with invalid tracking number format will not be accepted.
Optional Parameters
ParameterTypeDescription
slugString or ArrayUnique 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_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_keyStringKey of the shipment for a specific courier. Required by some couriers, such assic-teliway
tracking_destination_countryStringDestination Country of the shipment for a specific courier. Required by some couriers, such aspostnl-3s
androidArray or StringGoogle cloud message registration IDs to receive the push notifications.
Accept either array or Comma comma separated as input.
iosArray or StringApple iOS device IDs to receive the push notifications.
Accept either array or Comma comma separated as input.
emailsArray or StringEmail address(es) to receive email notifications.
Accept either array or Comma comma separated as input.
smsesArray or StringPhone number(s) to receive sms notifications. Enter+ andarea code before phone number.
Accept either array or Comma comma separated as input.
titleStringTitle of the tracking. Default value astracking_number
customer_nameStringCustomer name of the tracking.
destination_country_iso3StringEnterISO Alpha-3(three letters)to specify the destination of the shipment. If you use postal service to send international shipments, AfterShip will automatically get tracking results at destination courier as well (e.g. USPS for USA).
order_idStringText field for order ID
order_id_pathStringText field for order path
custom_fieldsStringCustom fields that accept any text string
noteStringText field for the note

Body

{
    "tracking": {
        "slug": "dhl",
        "tracking_number": "123456789",
        "title": "Title Name",
        "smses": [
            "+18555072509",
            "+18555072501"
        ],
        "emails": [
            "email@yourdomain.com",
            "another_email@yourdomain.com"
        ],
        "order_id": "ID 1234",
        "order_id_path": "http://www.aftership.com/order_id=1234",
        "custom_fields": {
            "product_name": "iPhone Case",
            "product_price": "USD19.99"
        }
    }
}

Headers

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

Attributes

Attributes
AttributeTypeDescription
trackingHash of Tracking ObjectHash 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_keyStringKey of the shipment for a specific courier. Required by some couriers, such assic-teliway
tracking_destination_countryStringDestination Country of the shipment for a specific courier. Required by some couriers, such aspostnl-3s
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 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.
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 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)
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 status definition)
titleStringTitle of the tracking.
tracked_countNumberNumber of attempts AfterShip tracks at courier's system.
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
cityStringLocation info (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
stateStringLocation info (if any)
tagStringCurrent status of checkpoint. Values include 
  • Pending
  • InfoReceived
  • InTransit
  • OutForDelivery
  • AttemptFail
  • Delivered
  • Exception
  • Expired
(See status definition)
zipStringLocation info (if any)

Body

{
    "meta": {
        "code": 201
    },
    "data": {
        "tracking": {
            "id": "53aa7b5c415a670000000021",
            "created_at": "2014-06-25T07:33:48+00:00",
            "updated_at": "2014-06-25T07:33:48+00:00",
            "tracking_number": "123456789",
            "tracking_account_number": null,
            "tracking_postal_code": null,
            "tracking_ship_date": null,
            "slug": "dhl",
            "active": true,
            "custom_fields": {
                "product_price": "USD19.99",
                "product_name": "iPhone Case"
            },
            "customer_name": null,
            "destination_country_iso3": null,
            "emails": [
                "email@yourdomain.com",
                "another_email@yourdomain.com"
            ],
            "expected_delivery": null,
            "note": null,
            "order_id": "ID 1234",
            "order_id_path": "http://www.aftership.com/order_id=1234",
            "origin_country_iso3": null,
            "shipment_package_count": 0,
            "shipment_type": null,
            "signed_by": null,
            "smses": [],
            "source": "api",
            "tag": "Pending",
            "title": "Title Name",
            "tracked_count": 0,
            "unique_token": "xy_fej9Llg",
            "checkpoints": []
        }
    }
}