TGG EXPRESS · Developer API Reference

01

Overview

Three endpoints cover the complete order-to-door workflow. All requests and responses are JSON with UTF-8 encoding.

POST /shipments Create a shipment

Submit a new shipping order. Returns a tracking_number and a label download URL. Supports CN / HK → NG TGG Express scenarios.

POST /track Batch tracking

Query up to 100 tracking numbers in a single call. Returns Nigerian local timestamps and standardised event codes.

GET /labels/{trackingNumber} Re-download label

Re-retrieve an already generated shipping label PDF. The original link expires after 7 days — use this endpoint to refresh it.

＋

Create shipment

Book a parcel and receive a label

POST /shipments

⟲

Track parcel

Batch retrieve tracking history

POST /track

▤

Get label

Refresh a label download link

GET /labels/{tn}

!

Authentication & conventions

Every request must include an API key in the request header. The server uses the key to determine environment and access scope.

🔑

X-API-Key header

Include your API key in the header of every HTTP request. Use the sandbox key for integration testing.

X-API-Key: tgg_sandbox_xxxxxxxxxx

Request conventions

Item	Value	Notes
Content-Type	application/json	All request bodies are JSON except label download
Accept	application/json	Responses default to JSON; label endpoint may return `application/pdf`
X-API-Key	string	Required. Used for identity and rate limiting
X-Request-Id	uuid	Optional. Recommended for tracing requests end-to-end
Charset	UTF-8	All fields are UTF-8 encoded
Time format	ISO 8601	UTC timestamps end with `Z`; local times use `YYYY-MM-DD HH:mm:ss`

i

The default request timeout is 15 seconds; the server closes the connection afterwards. When calling /shipments, make sure your client handles idempotency correctly (use reference_no for de-duplication).

03

Create shipment

Submit a shipping order containing sender, recipient, parcel physical properties and itemised contents.

POST /shipments Create shipment

On success, the response contains the tracking number and a label download URL. The label URL remains valid for 7 days; afterwards call /labels/{trackingNumber} to refresh it.

Request body fields

Field	Type	Required	Max length	Description
service_code	string	required	20	Fixed value `1575`, representing the standard TGG Express service.
reference_no	string	required	40	Merchant-side unique business number, used for reconciliation and idempotency.
inco_term_code	string	required	3	Incoterms code, e.g. `DDP` (Delivered Duty Paid).
specialInstruction1	string	optional	255	Special handling instructions, e.g. "Fragile", "Keep upright".
sender — sender (CN / HK)
name	string	required	60	Full name or company name.
phone	string	required	20	Include country code, e.g. `+86 20 9123 4567`.
email	string	optional	80	Email address for pickup notifications.
country	string	required	2	ISO 3166-1 alpha-2, e.g. `CN`.
state	string	required	30	Province / state, e.g. `Guangdong`.
suburb	string	required	40	City or district, e.g. `Guangzhou`.
address_line_1	string	required	200	Street address, building, floor.
address_line_2	string	optional	200	Additional address details (room / unit number).
postcode	string	optional	10	Postal code if any.
recipient — recipient (NG)
name	string	required	60	Full name or company name.
phone	string	required	20	e.g. `+234 803 123 4567`.
email	string	required	80	Used for delivery notifications; mandatory for the NG route.
country	string	required	2	Fixed value `NG`.
state	string	required	30	State, e.g. `Lagos`, `FCT`, `Kano`.
suburb	string	required	40	e.g. `Victoria Island`, `Lekki`.
address_line_1	string	required	200	Street address, building, floor.
address_line_2	string	optional	200	Additional address details.
postcode	string	required	10	Nigerian 6-digit postal code.
parcel — parcel information
weight	number	required	6,3	Total parcel weight in kg, up to 3 decimals.
length	integer	required	4	Length in cm.
width	integer	required	4	Width in cm.
height	integer	required	4	Height in cm.
parcel.items[] — item details (array, at least one item)
sku	string	required	30	Merchant internal SKU.
quantity	number	required	4	Item quantity.
name	string	required	120	Item name / English description.
hs_code	string	required	10	Harmonised System (HS) code.
currency	string	required	3	ISO currency code, e.g. `NGN`, `USD`.
value	number	required	8,2	Declared unit value.
sku_weight	number	required	6,3	Weight of a single SKU.
sku_weight_unit	string	required	5	`kg` or `g`; defaults to `kg`.
image_url	string	required	500	Product image URL (recommended).
product_url	string	required	500	Product page URL (recommended).

Request example

POST /shipments

{
  "service_code": "1575",
  "reference_no": "TGG-2026-00123",
  "inco_term_code": "DDP",
  "specialInstruction1": "Fragile - handle with care",
  "sender": {
    "name": "Li Wei",
    "phone": "+86 20 9123 4567",
    "email": "li.wei@example.cn",
    "country": "CN",
    "state": "Guangdong",
    "suburb": "Guangzhou",
    "address_line_1": "123 Tianhe Road",
    "address_line_2": "Unit 1802",
    "postcode": "510620"
  },
  "recipient": {
    "name": "Chinedu Okafor",
    "phone": "+234 803 123 4567",
    "email": "chinedu@example.ng",
    "country": "NG",
    "state": "Lagos",
    "suburb": "Victoria Island",
    "address_line_1": "15 Adeola Odeku Street",
    "address_line_2": "",
    "postcode": "101241"
  },
  "parcel": {
    "weight": 2.45,
    "length": 35,
    "width": 25,
    "height": 15,
    "items": [
      {
        "sku": "BK-001",
        "quantity": 1,
        "name": "African Short Stories",
        "hs_code": "49019900",
        "currency": "NGN",
        "value": 18500.00,
        "sku_weight": 0.45,
        "sku_weight_unit": "kg",
        "image_url": "https://example.com/images/book1.jpg",
        "product_url": "https://example.com/product/49019900"
      }
    ]
  }
}

Response examples

✓ Success

application/json

{
  "code": "TGG-OK-000",
  "message": "Shipment created",
  "data": {
    "tracking_number": "TGG782345678NG",
    "label_url": "https://api.tggexpress.com/labels/TGG782345678NG.pdf",
    "label_format": "pdf",
    "reference_no": "TGG-2026-00123"
  }
}

✗ Bad Request

application/json

{
  "code": "TGG-PAR-002",
  "message": "Missing required field: items[0].currency",
  "data": null
}

⚠

The label download URL is valid for 7 days. Once expired, call GET /labels/{trackingNumber} to refresh the link — you don't need to re-create the shipment.

04

Track parcel

Query up to 100 tracking numbers per request. Returns a complete event list plus a current status summary.

POST /track Track parcels

The response is split into results (successful lookups) and errors (invalid or not found). Partial success still returns HTTP 200.

Request body fields

Field	Type	Required	Description
tracking_numbers	string[]	required	Array of tracking numbers, up to `100` items, e.g. `["TGG782345678NG"]`.

Response fields

Field	Type	Description
results	object	Map of tracking number → tracking details object.
errors	object	Map of invalid / not found numbers → error reason.
tracking_number	string	The tracking number.
latest_status_code	string	Latest event code, e.g. `del_09`.
latest_status_description	string	Human-readable description of the latest status.
latest_extended_description	string	Extra information about the latest status.
latest_local_time	string	Local Nigerian time (WAT) of the latest event.
latest_location	string	Location of the latest event.
origin	string	Origin city.
destination	string	Destination city.
tracking_details	array	List of events, ordered latest first.
timestamp	string	UTC ISO 8601 timestamp.
local_time	string	Local WAT time `YYYY-MM-DD HH:mm:ss`.
location	string	Facility / city where the event occurred.
status_code	string	Event code (see event codes).
status_description	string	Description of the event.
extended_description	string	Optional additional information about the event.

Request example

POST /track

{
  "tracking_numbers": ["TGG782345678NG", "TGG998877NG"]
}

Success response

200 OK · application/json

{
  "code": "TGG-OK-000",
  "message": "OK",
  "data": {
    "results": {
      "TGG782345678NG": {
        "tracking_number": "TGG782345678NG",
        "latest_status_code": "del_09",
        "latest_status_description": "Delivery Completed",
        "latest_extended_description": "Parcel handed to resident and signed",
        "latest_local_time": "2026-04-02 15:20:00",
        "latest_location": "Lagos",
        "origin": "Hong Kong",
        "destination": "Lagos, LA",
        "tracking_details": [
          {
            "timestamp": "2026-04-02T14:20:00Z",
            "local_time": "2026-04-02 15:20:00",
            "location": "Lagos",
            "status_code": "del_09",
            "status_description": "Delivery Completed",
            "extended_description": "Proof of delivery signed by recipient"
          },
          {
            "timestamp": "2026-04-02T08:15:00Z",
            "local_time": "2026-04-02 09:15:00",
            "location": "Lagos Depot",
            "status_code": "ofd_01",
            "status_description": "Out for Delivery",
            "extended_description": "Driver assigned to route 12B"
          },
          {
            "timestamp": "2026-04-01T22:00:00Z",
            "local_time": "2026-04-01 23:00:00",
            "location": "Lagos Hub",
            "status_code": "dep_01",
            "status_description": "Arrived at destination depot",
            "extended_description": "Parcel sorted for delivery"
          },
          {
            "timestamp": "2026-03-30T10:45:00Z",
            "local_time": "2026-03-30 11:45:00",
            "location": "Lagos Customs",
            "status_code": "ccl_01",
            "status_description": "Released from Customs",
            "extended_description": "Customs clearance completed, duties paid"
          },
          {
            "timestamp": "2026-03-27T10:30:00Z",
            "local_time": "2026-03-27 18:30:00",
            "location": "Hong Kong Hub",
            "status_code": "pro_01",
            "status_description": "Parcel Check In",
            "extended_description": "Parcel accepted at origin facility"
          },
          {
            "timestamp": "2026-03-26T08:00:00Z",
            "local_time": "2026-03-26 16:00:00",
            "location": "Hong Kong",
            "status_code": "cre_01",
            "status_description": "We have been notified of your order.",
            "extended_description": "Shipping label created, awaiting pickup"
          }
        ]
      }
    },
    "errors": {}
  }
}

Partial success response

Partial success

{
  "code": "TGG-OK-000",
  "message": "Partial success",
  "data": {
    "results": {
      "TGG782345678NG": { /* full tracking object */ }
    },
    "errors": {
      "INVALID999": "Tracking number format invalid",
      "TGG000000NG": "Not found"
    }
  }
}

05

Get label

Re-retrieve an already generated label file, either as JSON with a download URL or as a direct PDF stream.

GET /labels/{trackingNumber} Get label

By default returns JSON containing the download link; add ?format=pdf to receive the PDF file stream directly.

Path & query parameters

Parameter	Location	Type	Description
trackingNumber	path	string	Tracking number, e.g. `TGG782345678NG`.
format	query	string	Optional. When set to `pdf`, returns the PDF file directly; otherwise returns JSON.

Response examples

✓ Success (JSON)

application/json

{
  "code": "TGG-OK-000",
  "message": "Success",
  "data": {
    "tracking_number": "TGG782345678NG",
    "label_url": "https://api.tggexpress.com/labels/TGG782345678NG.pdf",
    "label_format": "pdf",
    "created_at": "2026-04-01T10:30:00Z",
    "expires_at": "2026-04-08T10:30:00Z"
  }
}

✗ Not Found

application/json

{
  "code": "TGG-RES-404",
  "message": "Label not found / expired",
  "data": null
}

i

The label file defaults to A6 (100 × 150 mm). To receive an A4 version, append &size=a4 to the query string.

06

Error codes

All error responses follow a unified structure: code is an alphanumeric business code (TGG-XXX-000), message a human-readable description, and data is usually null.

i

Codes use the format TGG-{CATEGORY}-{SEQ}. Category prefixes: OK success, SRV server, PAR parameter, AUTH authentication, RES resource, BIZ business rule, CAR carrier, QTA quota.

Code	Message	Meaning & troubleshooting
TGG-OK-000	Success	Request succeeded with no error.
TGG-SRV-001	Internal server error	Server-side exception. Retry later or contact support.
TGG-SRV-002	Service unavailable	Service under maintenance; usually accompanied by a `Retry-After` header.
TGG-PAR-001	Invalid parameter	Field format error. Check the type and allowed values.
TGG-PAR-002	Missing required field	A required field is missing; the error message points to the exact field path.
TGG-PAR-003	Parameter out of range	A field exceeds its length or numeric range.
TGG-AUTH-001	Authentication failed	`X-API-Key` is missing or invalid.
TGG-AUTH-002	Permission denied	The key is not authorised to access the resource or environment.
TGG-RES-404	Resource not found	Tracking number does not exist, or the label has expired.
TGG-RES-409	Duplicate request	Idempotency conflict; `reference_no` already exists.
TGG-BIZ-001	Business validation failed	Address unreachable, P.O. Box not allowed, or similar business rule failure.
TGG-CAR-001	Carrier rejection	The downstream carrier refused the shipment. Check cargo attributes.
TGG-QTA-001	Quota exceeded	Rate limit reached. Reduce QPS or request a quota increase.

07

Tracking event codes

Every event uses a 3-letter prefix plus a 2-digit sequence. The prefix identifies the stage, making it easy for front-ends to map icons and labels.

i

All local_time values are in West Africa Time (WAT, UTC+1).

Created 2 codes

Code	Description
cre_01	We have been notified of your order.
cre_02	Collection Assigned

Processed 2 codes

Code	Description
pro_01	Parcel Check In
pro_04	Shipment Added in Transit Bag

Arrived 1 code

Code	Description
arr_01	Flight Partial Arrived

Under clearance 4 codes

Code	Description
unc_01	Parcel Collected from Airport
unc_02	Your parcel has been stopped at customs.
unc_03	Your parcel is currently with customs.
unc_04	Customs rejected the shipment.

Cleared 3 codes

Code	Description
ccl_01	Released from Customs
ccl_02	Customs Invoice Paid
cus_03	Released from Security

Sorted to destination 3 codes

Code	Description
sor_01	In Transit
sor_02	Collected
sor_03	Ready For Dispatch

Reached destination depot 2 codes

Code	Description
dep_01	Arrived at destination depot
dep_02	Pickup Point Depot

Out for delivery 1 code

Code	Description
ofd_01	Out for Delivery

Transit exception 4 codes

Code	Description
tex_01	Delayed Parcel
tex_02	Misdirected
tex_03	Damaged
tex_04	Parcel Intercepted

Delivery exception 13 codes

Code	Description
exe_01	Protest Action
exe_02	Premises closed on arrival
exe_03	Traffic Congestion
exe_04	Out of Time
exe_05	Calling Card Left
exe_06	Bad Weather
exe_07	Problem Freight
exe_08	Address Unclear
exe_09	Consignee on Holiday
exe_10	Rejected Delivery
exe_11	Cannot Locate Receiver
exe_12	Change of Address
exe_13	Out of Regional Boundaries

Delivered 10 codes

Code	Description
del_01	Signature Obtained
del_02	Back door Delivery
del_03	Left in Letterbox
del_04	Contactless Signature
del_05	Left in Safe Place
del_06	Manual POD
del_07	Left As Instructed
del_08	Left with Neighbour
del_09	Delivery Completed
del_10	Parcel Collected by Customer

Claim · Cancelled · Returned · Abandoned 6 codes

Code	Description
cla_01	Insurance Claim
cla_02	Hijacking Claim
cla_03	Damaged Claim
can_01	Cancelled Shipment
ret_01	Return to Sender
aba_01	Abandoned Shipment

TGG EXPRESS Parcel API
built for TGG Express & last-mile delivery

Overview

Create shipment

Track parcel

Get label

Error codes

Event codes

Authentication & conventions

X-API-Key header

Request conventions

Create shipment

Request body fields

Request example

Response examples

Track parcel

Request body fields

Response fields

Request example

Success response

Partial success response

Get label

Path & query parameters

Response examples

Error codes

Tracking event codes