Get Shipments v2

Fetch a list of all shipments available for a user.

/shipments

GET https://api.terminal.africa/v2/shipments

This endpoint allows you to get a list of shipments available for a user.

Query Parameters

Name
Type
Description

perPage

string

Specify how many results will be returned in a single request. Defaults to 50.

page

string

Specify what page of records will be sent in response. Defaults to 1.

status

string

Status of shipment. Must be one of cancelled, confirmed, delivered, draft, in-transit, pending

search

String

Search for shipments using text string. The searchable fields includes tracking_number, shipment_id, shipment reference.

Eg: ?search=search_text

orderBy

String

Order a shipments. Default to DESC created_at (-created_at). Ordering fields includes: created_at, updated_at, pickup_date, delivery_date, amount.

EXAMPLES OF DESC ORDERING

1. ?orderBy=-created_at

2. ?orderBy=-amount

3. ?orderBy=-updated_at

EXAMPLES OF ASC ORDERING

1. ?orderBy=created_at

2. ?orderBy=amount

3. ?orderBy=updated_at

pickup_country

String

Filter shipment by pickup country

Eg ?pickup_country=NG

delivery_country

String

Filter shipment by delivery country

Eg ?delivery_country=NG

pickup_state

String

Filter shipment by pickup state

Eg ?pickup_state=Lagos

delivery_state

String

Filter shipment by delivery state

Eg ?delivery_state=Lagos

pickup_city

String

Filter shipment by pickup city

Eg ?pickup_city=Apapa

delivery_city

String

Filter shipment by delivery city

Eg ?delivery_city=Apapa

carrier_slug

String

Filter shipments by carrier_slug

eg?carrier_slug=dhl

carrier_id

String

Filter shipments by carrier_id

eg?carrier_id=CA-81957188177

start_date

String

Filter from shipment creation start date. Format: YYYY-MM-DD

eg ?start_date=2023-05-01

end_date

String

Filter from shipment creation end date. Format: YYYY-MM-DD

eg ?end_date=2023-05-01

Headers

Name
Type
Description

Authorization*

string

Set value to Bearer ACCESS_TOKEN

```json
{
    "status": true,
    "message": "Shipments retrieved successfully",
    "data": {
        "shipments": [
            {
                "_index": "shipments",
                "_id": "SH-WZZM27DZ8DEIP6QB",
                "_score": null,
                "_source": {
                    "address_to": "AD-K6MR9ACBQ0S38T9T",
                    "address_from": "AD-O3E5K3XN1YMSOAHO",
                    "address_return": "AD-O3E5K3XN1YMSOAHO",
                    "parcel": "PC-5X8DU2SSCZ44AZZ8",
                    "parcels": [],
                    "pickup_date": "2023-09-16T12:20:17.053Z",
                    "cancellation_request": false,
                    "cancellation_reason": "",
                    "shipment_cost_currency": "NGN",
                    "shipment_purpose": "personal",
                    "status": "confirmed",
                    "type": "terminal",
                    "source": "web",
                    "created_source": "web",
                    "user": "USER-22070036153",
                    "events": [
                        {
                            "created_at": "2023-09-14T12:20:17.053Z",
                            "description": "Shipment arranged by Tolulope Oguntade",
                            "location": "Ikeja, NG",
                            "status": "confirmed"
                        }
                    ],
                    "shipment_id": "SH-WZZM27DZ8DEIP6QB",
                    "created_at": "2023-09-14T12:14:34.721Z",
                    "updated_at": "2023-09-14T12:20:17.055Z",
                    "carrier": "CA-81957188177",
                    "delivery_arranged": "2023-09-14T12:20:17.053Z",
                    "delivery_date": "2023-09-19T23:59:00.000Z",
                    "rate": "RT-QEWREK6BYRC4F4DO",
                    "shipment_cost": 23577.96,
                    "tracking_number": "3847758972",
                    "international_tracking_number": "",
                    "reference": "CBJ230915031861",
                    "carrier_tracking_url": "https://www.dhl.com/global-en/home/tracking.html?tracking-id=3847758972",
                    "shipping_label_url": "https://api.terminal.africa/v1/shipments/label/SH-WZZM27DZ8DEIP6QB.pdf",
                    "commercial_invoice_url": "https://api.terminal.africa/v1/shipments/commercial-invoice/SH-WZZM27DZ8DEIP6QB.pdf",
                    "tracking_url": "https://app.terminal.africa/shipments/track/SH-WZZM27DZ8DEIP6QB",
                    "user_email": "parcelsnigeria@gmail.com",
                    "user_phone": "",
                    "user_company_name": "Parcels Nigeria",
                    "user_business_category": "consultant",
                    "user_account_type": "3pl",
                    "user_country": "NG",
                    "user_country_state": "",
                    "user_name": "Tolulope Oguntade",
                    "user_storeId": "dmNhphFCXKTYCCTcQJOPbryn6bB2",
                    "user_wallet": "6278e2739619f23000874d56",
                    "user_referredBy": "",
                    "user_referralCode": "REF-84841000717",
                    "pickup_email": "parcelsnigeria@gmail.com",
                    "delivery_email": "parcelsnigeria@gmail.com",
                    "return_email": "parcelsnigeria@gmail.com",
                    "pickup_name": "Lara Evelyn",
                    "delivery_name": "Priscille Manlan",
                    "return_name": "Lara Manlan",
                    "pickup_city": "Ikeja",
                    "delivery_city": "Newark",
                    "return_city": "Ikeja",
                    "pickup_state": "Lagos",
                    "delivery_state": "Delaware",
                    "return_state": "Lagos",
                    "pickup_country": "NG",
                    "delivery_country": "US",
                    "return_country": "NG",
                    "pickup_zip": "105102",
                    "delivery_zip": "19702",
                    "return_zip": "105102",
                    "pickup_line1": "782b Rev. Emmanuel Adubifa Street, Ikeja, Nig",
                    "delivery_line1": "1405 Gregory Drive, Newark, DE, USA",
                    "return_line1": "782b Rev. Emmanuel Adubifa Street, Ikeja, Nig",
                    "carrier_name": "DHL Express",
                    "carrier_logo": "https://ucarecdn.com/dcdd8109-af8c-4057-8104-192be821dd6e/download4.png",
                    "carrier_slug": "dhl-ng",
                    "amount": 23577.96
                },
                "sort": [
                    1694693674721
                ]
            },
            {
                "_index": "shipments",
                "_id": "SH-28GIZ6WNYRMGLII2",
                "_score": null,
                "_source": {
                    "address_to": "AD-3TVI0BWYTVFMNPMW",
                    "address_from": "AD-6QAY79GCAVEVSZI4",
                    "address_return": "AD-6QAY79GCAVEVSZI4",
                    "parcel": "PC-WOTT6EV8Y3UCPB9W",
                    "parcels": [],
                    "pickup_date": "2023-09-16T10:30:36.373Z",
                    "cancellation_request": false,
                    "cancellation_reason": "",
                    "shipment_cost_currency": "NGN",
                    "shipment_purpose": "personal",
                    "status": "confirmed",
                    "type": "terminal",
                    "source": "web",
                    "created_source": "web",
                    "user": "USER-22070036153",
                    "events": [
                        {
                            "created_at": "2023-09-14T10:30:36.373Z",
                            "description": "Shipment arranged by Tolulope Oguntade",
                            "location": "Ikeja, NG",
                            "status": "confirmed"
                        }
                    ],
                    "shipment_id": "SH-28GIZ6WNYRMGLII2",
                    "created_at": "2023-09-14T10:27:25.458Z",
                    "updated_at": "2023-09-14T10:30:36.374Z",
                    "carrier": "CA-81957188177",
                    "delivery_arranged": "2023-09-14T10:30:36.373Z",
                    "delivery_date": "2023-09-15T23:59:00.000Z",
                    "rate": "RT-R9STD54YM120O6EX",
                    "shipment_cost": 4434.6,
                    "tracking_number": "1707192756",
                    "international_tracking_number": "",
                    "reference": "CBJ230915026870",
                    "carrier_tracking_url": "https://www.dhl.com/global-en/home/tracking.html?tracking-id=1707192756",
                    "shipping_label_url": "https://api.terminal.africa/v1/shipments/label/SH-28GIZ6WNYRMGLII2.pdf",
                    "commercial_invoice_url": "https://api.terminal.africa/v1/shipments/commercial-invoice/SH-28GIZ6WNYRMGLII2.pdf",
                    "tracking_url": "https://app.terminal.africa/shipments/track/SH-28GIZ6WNYRMGLII2",
                    "user_email": "parcelsnigeria@gmail.com",
                    "user_phone": "",
                    "user_company_name": "Parcels Nigeria",
                    "user_business_category": "consultant",
                    "user_account_type": "3pl",
                    "user_country": "NG",
                    "user_country_state": "",
                    "user_name": "Tolulope Oguntade",
                    "user_storeId": "dmNhphFCXKTYCCTcQJOPbryn6bB2",
                    "user_wallet": "6278e2739619f23000874d56",
                    "user_referredBy": "",
                    "user_referralCode": "REF-84841000717",
                    "pickup_email": "parcelsnigeria@gmail.com",
                    "delivery_email": "parcelsnigeria@gmail.com",
                    "return_email": "parcelsnigeria@gmail.com",
                    "pickup_name": "Barcutt Logistics",
                    "delivery_name": "Maikyau Princess",
                    "return_name": "Barcutt Princess",
                    "pickup_city": "Ikeja",
                    "delivery_city": "Abuja",
                    "return_city": "Ikeja",
                    "pickup_state": "Lagos",
                    "delivery_state": "Abuja",
                    "return_state": "Lagos",
                    "pickup_country": "NG",
                    "delivery_country": "NG",
                    "return_country": "NG",
                    "pickup_zip": "105102",
                    "delivery_zip": "900108",
                    "return_zip": "105102",
                    "pickup_line1": "782b Rev. Emmanuel Adubifa Street, Ikeja, Nig",
                    "delivery_line1": "House 14, Aclose Eagleville Estate, Mabushi",
                    "return_line1": "782b Rev. Emmanuel Adubifa Street, Ikeja, Nig",
                    "carrier_name": "DHL Express",
                    "carrier_logo": "https://ucarecdn.com/dcdd8109-af8c-4057-8104-192be821dd6e/download4.png",
                    "carrier_slug": "dhl-ng",
                    "amount": 4434.6
                },
                "sort": [
                    1694687245458
                ]
            },
            {
                "_index": "shipments",
                "_id": "SH-MAOPQZBNWOFQQFQC",
                "_score": null,
                "_source": {
                    "address_to": "AD-2912LZK1ZZZ5O0KQ",
                    "address_from": "AD-DE0NV0H03VTTBZZR",
                    "address_return": "AD-DE0NV0H03VTTBZZR",
                    "parcel": "PC-0SSTLONL9NWAW11V",
                    "parcels": [],
                    "pickup_date": "2023-09-13T15:43:27.658Z",
                    "cancellation_request": false,
                    "cancellation_reason": "",
                    "shipment_cost_currency": "NGN",
                    "shipment_purpose": "personal",
                    "status": "delivered",
                    "type": "terminal",
                    "source": "web",
                    "created_source": "web",
                    "user": "USER-22070036153",
                    "events": [
                        {
                            "created_at": "2023-09-13T13:43:27.658Z",
                            "description": "Shipment arranged by Tolulope Oguntade",
                            "location": "Yaba, NG",
                            "status": "confirmed"
                        },
                        {
                            "created_at": "2023-09-13T15:00:00.000Z",
                            "description": "Pickup completed by JOLAOSHO",
                            "location": "Yaba, NG",
                            "status": "in-transit"
                        },
                        {
                            "created_at": "2023-09-13T18:00:00.000Z",
                            "description": "Delivery completed by JOLAOSHO",
                            "location": "Ikeja, NG",
                            "status": "delivered"
                        }
                    ],
                    "shipment_id": "SH-MAOPQZBNWOFQQFQC",
                    "created_at": "2023-09-13T13:40:39.789Z",
                    "updated_at": "2023-09-13T18:15:02.562Z",
                    "carrier": "CA-18228854618",
                    "delivery_arranged": "2023-09-13T13:43:27.658Z",
                    "delivery_date": "2023-09-13T15:43:15.874Z",
                    "rate": "RT-8PR6UNOVOIFDTG1W",
                    "shipment_cost": 2251.88,
                    "transaction_reference": "TR-I43SYVC71VM574FB9A4H5HKRTZ643KJ",
                    "tracking_number": "974858RH319",
                    "international_tracking_number": "",
                    "reference": "974858RH319",
                    "carrier_tracking_url": "https://dashboard.kwik.delivery/tracking/index.html?jobID=2e68771349c057641186cc029f133e91",
                    "shipping_label_url": "",
                    "commercial_invoice_url": "",
                    "tracking_url": "https://app.terminal.africa/shipments/track/SH-MAOPQZBNWOFQQFQC",
                    "user_email": "parcelsnigeria@gmail.com",
                    "user_phone": "",
                    "user_company_name": "Parcels Nigeria",
                    "user_business_category": "consultant",
                    "user_account_type": "3pl",
                    "user_country": "NG",
                    "user_country_state": "",
                    "user_name": "Tolulope Oguntade",
                    "user_storeId": "dmNhphFCXKTYCCTcQJOPbryn6bB2",
                    "user_wallet": "6278e2739619f23000874d56",
                    "user_referredBy": "",
                    "user_referralCode": "REF-84841000717",
                    "pickup_email": "parcelsnigeria@gmail.com",
                    "delivery_email": "parcelsnigeria@gmail.com",
                    "return_email": "parcelsnigeria@gmail.com",
                    "pickup_name": "Lara Evelyn",
                    "delivery_name": "Parcels Nigeria",
                    "return_name": "Lara Nigeria",
                    "pickup_city": "Yaba",
                    "delivery_city": "Ikeja",
                    "return_city": "Yaba",
                    "pickup_state": "Lagos",
                    "delivery_state": "Lagos",
                    "return_state": "Lagos",
                    "pickup_country": "NG",
                    "delivery_country": "NG",
                    "return_country": "NG",
                    "pickup_zip": "101245",
                    "delivery_zip": "105102",
                    "return_zip": "101245",
                    "pickup_line1": "31b Simpson Street, Lagos, Nigeria",
                    "delivery_line1": "782b Rev. Emmanuel Adubifa Street, Ikeja, Nig",
                    "return_line1": "31b Simpson Street, Lagos, Nigeria",
                    "carrier_name": "Kwik Delivery",
                    "carrier_logo": "https://ucarecdn.com/d399a2ad-c831-46de-a8fe-94f8056a3c29/60dc787ac0166774ecb59f04_gy2h4u35onr2nrmuapjt.png",
                    "carrier_slug": "kwik",
                    "amount": 2702.26
                },
                "sort": [
                    1694612439789
                ]
            },
            {
                "_index": "shipments",
                "_id": "SH-B7LD62MNVMI1PHY0",
                "_score": null,
                "_source": {
                    "address_to": "AD-GI5O5EXIX857X7V8",
                    "address_from": "AD-KYQVV7EZF0M7AULH",
                    "address_return": "AD-KYQVV7EZF0M7AULH",
                    "parcel": "PC-VTJR1VHPNGP6USTX",
                    "parcels": [],
                    "pickup_date": "2023-09-15T13:30:59.539Z",
                    "cancellation_request": false,
                    "cancellation_reason": "",
                    "shipment_cost_currency": "NGN",
                    "shipment_purpose": "personal",
                    "status": "in-transit",
                    "type": "terminal",
                    "source": "web",
                    "created_source": "web",
                    "user": "USER-22070036153",
                    "events": [
                        {
                            "created_at": "2023-09-13T13:30:59.539Z",
                            "description": "Shipment arranged by Tolulope Oguntade",
                            "location": "Ikeja, NG",
                            "status": "confirmed"
                        },
                        {
                            "created_at": "2023-09-13T00:00:00.000Z",
                            "description": "Shipment picked up",
                            "location": "Lagos-NG",
                            "status": "PU"
                        },
                        {
                            "created_at": "2023-09-13T20:00:20.280Z",
                            "description": "Processed at LAGOS-NIGERIA",
                            "location": "Lagos-NG",
                            "status": "PL"
                        },
                        {
                            "created_at": "2023-09-13T22:30:15.648Z",
                            "description": "Shipment has departed from a DHL facility LAGOS-NIGERIA",
                            "location": "Lagos-NG",
                            "status": "DF"
                        },
                        {
                            "created_at": "2023-09-13T23:30:17.381Z",
                            "description": "Shipment is in transit to destination",
                            "location": "Lagos-NG",
                            "status": "TR"
                        },
                        {
                            "created_at": "2023-09-14T01:00:17.852Z",
                            "description": "Shipment has departed from a DHL facility LAGOS-NIGERIA",
                            "location": "Lagos-NG",
                            "status": "DF"
                        },
                        {
                            "created_at": "2023-09-14T06:30:15.016Z",
                            "description": "Arrived at DHL Sort Facility  PORT HARCOURT-NIGERIA",
                            "location": "Port Harcourt-NG",
                            "status": "AF"
                        },
                        {
                            "created_at": "2023-09-14T07:30:21.627Z",
                            "description": "Shipment has departed from a DHL facility PORT HARCOURT-NIGERIA",
                            "location": "Port Harcourt-NG",
                            "status": "DF"
                        }
                    ],
                    "shipment_id": "SH-B7LD62MNVMI1PHY0",
                    "created_at": "2023-09-13T13:27:23.871Z",
                    "updated_at": "2023-09-14T07:30:21.627Z",
                    "carrier": "CA-81957188177",
                    "delivery_arranged": "2023-09-13T13:30:59.539Z",
                    "delivery_date": "2023-09-18T13:30:50.075Z",
                    "rate": "RT-3ILA3GUL1YFQNQLO",
                    "shipment_cost": 1935.1,
                    "transaction_reference": "TR-HY45ACJCENP34S9UAC3YQ5C48P7RK7M",
                    "tracking_number": "3361371484",
                    "international_tracking_number": "",
                    "reference": "CBJ230914030325",
                    "carrier_tracking_url": "https://www.dhl.com/global-en/home/tracking.html?tracking-id=3361371484",
                    "shipping_label_url": "https://api.terminal.africa/v1/shipments/label/SH-B7LD62MNVMI1PHY0.pdf",
                    "commercial_invoice_url": "https://api.terminal.africa/v1/shipments/commercial-invoice/SH-B7LD62MNVMI1PHY0.pdf",
                    "tracking_url": "https://app.terminal.africa/shipments/track/SH-B7LD62MNVMI1PHY0",
                    "user_email": "parcelsnigeria@gmail.com",
                    "user_phone": "",
                    "user_company_name": "Parcels Nigeria",
                    "user_business_category": "consultant",
                    "user_account_type": "3pl",
                    "user_country": "NG",
                    "user_country_state": "",
                    "user_name": "Tolulope Oguntade",
                    "user_storeId": "dmNhphFCXKTYCCTcQJOPbryn6bB2",
                    "user_wallet": "6278e2739619f23000874d56",
                    "user_referredBy": "",
                    "user_referralCode": "REF-84841000717",
                    "pickup_email": "parcelsnigeria@gmail.com",
                    "delivery_email": "parcelsnigeria@gmail.com",
                    "return_email": "parcelsnigeria@gmail.com",
                    "pickup_name": "Mummy Swift",
                    "delivery_name": "Azubuike Grace Amarachi",
                    "return_name": "Mummy Grace Amarachi",
                    "pickup_city": "Ikeja",
                    "delivery_city": "Warri",
                    "return_city": "Ikeja",
                    "pickup_state": "Lagos",
                    "delivery_state": "Delta",
                    "return_state": "Lagos",
                    "pickup_country": "NG",
                    "delivery_country": "NG",
                    "return_country": "NG",
                    "pickup_zip": "105102",
                    "delivery_zip": "0000",
                    "return_zip": "105102",
                    "pickup_line1": "782b Rev. Emmanuel Adubifa Street, Ikeja, Nig",
                    "delivery_line1": "Old Julius Berger Yard, Km 4 Warri,",
                    "return_line1": "782b Rev. Emmanuel Adubifa Street, Ikeja, Nig",
                    "carrier_name": "DHL Express",
                    "carrier_logo": "https://ucarecdn.com/dcdd8109-af8c-4057-8104-192be821dd6e/download4.png",
                    "carrier_slug": "dhl-ng",
                    "amount": 2322.12
                },
                "sort": [
                    1694611643871
                ]
            }
        ],
        "pagination": {
            "prevPage": null,
            "nextPage": 2,
            "hasNextPage": true,
            "hasPrevPage": false,
            "total": 11234,
            "perPage": 4,
            "currentPage": 1,
            "pageCounter": 1,
            "pageCount": 2809
        }
    }
}
```

Last updated