Package Tracking

4 API calls in this section.

APIs for tracking packages and listing customer orders

Track Package by Tracking Number

Express Shipping / Order / Package Tracking

GET/express-shipping/order/track/GL1706371234567

API: Track Package by Tracking Number

Endpoint

GET /express-shipping/order/track/{tracking_number}

Purpose

Retrieve detailed package information by tracking number. Returns package status, payment information, and delivery details.

• Bearer token: Authorization: Bearer {{access_token}} (required)

• API Key: X-API-Key: {{api_key}} (alternative authentication method)

Business Logic

1. Validate tenant has active express shipping service

2. Locate package using the provided tracking number

3. Verify access permissions (tenant-scoped)

4. Return comprehensive package information

Package Status Values

• claimed - Package claimed by customer, pending pickup

• received - Package received at facility

• in_transit - Package in transit to destination

• in_transit_international - Package in international transit

• in_warehouse - Package at local warehouse

• out_for_delivery - Package out for delivery

• delivered - Package delivered to customer

• exception - Delivery exception occurred

Payment Status Values

• pending - Payment not yet made

• paid - Payment completed

• failed - Payment failed

• refunded - Payment refunded

Error Responses

400 - Missing Tracking Number

404 - Package Not Found

403 - Access Denied

500 - Internal Server Error

Path parameters

Parameter	Type	Description
tracking_numberRequired	string	(string, required): Package tracking number (format: GL followed by timestamp, e.g., GL1706371234567) (string, required): Package tracking number (format: GL followed by timestamp, e.g., GL1706371234567)

Query parameters

Parameter	Type	Description
languageOptional	string	Preferred language for response messages (en, ar, ku) Preferred language for response messages (en, ar, ku) Example: en

Headers

Parameter	Type	Description
X-EXPRESS-KEYRequired	string	Short-lived JWT from OTP verification (required) Short-lived JWT from OTP verification (required) Example: {{express_access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/express-shipping/order/track/GL1706371234567?language=en" \2  --header "X-EXPRESS-KEY: ${EXPRESS_ACCESS_TOKEN}"

Response examples

200 · Success Response - Package Details404 · Error - Package Not Found400 · Error - Missing Tracking Number404 · 404 - Package Not Found403 · 403 - Access Denied500 · 500 - Internal Server Error

200OK

Response body

json

1{2  "success": true,3  "data": {4    "tracking_number": "GL1706371234567",5    "order_id": "TREND-ORD-98765",6    "status": "in_transit",7    "payment_status": "paid",8    "declared_value": 125.5,9    "currency": "USD",10    "store_name": "Trendyol",11    "quantity": 3,12    "weight": 350,13    "delivery_fee": 15,14    "claimed_at": "2024-01-27T10:00:00Z",15    "created_at": "2024-01-27T10:00:00Z",16    "last_updated": "2024-01-28T14:30:00Z"17  }18}

Track Package by Order ID

Express Shipping / Order / Package Tracking

GET/express-shipping/order/track-by-order/TREND-ORD-98765

API: Track Package by Order ID

Endpoint

GET /express-shipping/order/track-by-order/{order_id}

Purpose

Retrieve minimal package tracking information by order ID. Returns current status, status history, payment status, claimed_at, and store_name.

• Bearer token: Authorization: Bearer {{access_token}} (required)

Error Responses

400 - Missing Order ID

404 - Package Not Found

403 - Express Shipping Not Configured

Path parameters

Parameter	Type	Description
order_idRequired	string	(string, required): Store order identifier (e.g., TREND-ORD-98765) (string, required): Store order identifier (e.g., TREND-ORD-98765)

Query parameters

Parameter	Type	Description
language	string	Preferred language for response messages (en, ar, ku) Preferred language for response messages (en, ar, ku) Example: en

Headers

Parameter	Type	Description
AuthorizationRequired	string	Bearer token authentication (required) Bearer token authentication (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/express-shipping/order/track-by-order/TREND-ORD-98765?language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success - Status by Order ID404 · Error - Package Not Found400 · Error - Missing Order ID403 · 403 - Express Shipping Not Configured

200OK

Response body

json

1{2  "success": true,3  "data": {4    "status": "claimed",5    "status_history": [],6    "payment_status": "pending",7    "claimed_at": "2024-01-15T10:30:00Z",8    "store_name": "Trendyol"9  }10}

List Customer Packages

Express Shipping / Order / Package Tracking

GET/express-shipping/order/customer/GAL1704067200000

API: List Customer Packages

Endpoint

GET /express-shipping/order/customer/{customer_id}

Purpose

Retrieve a list of all packages for a specific customer. Supports pagination and filtering.

• Bearer token: Authorization: Bearer {{access_token}} (required)

• API Key: X-API-Key: {{api_key}} (alternative authentication method)

Business Logic

1. Validate tenant has active express shipping service

2. Verify customer exists and access permissions

3. Apply pagination and filtering

4. Return list of customer packages with summary information

Error Responses

400 - Missing Customer ID

400 - Invalid Pagination

404 - Customer Not Found

500 - Internal Server Error

Path parameters

Parameter	Type	Description
customer_idRequired	string	(string, required): Customer identifier in the URL path (string, required): Customer identifier in the URL path

Query parameters

Parameter	Type	Description
customer_idRequired	string	Customer identifier (required) Customer identifier (required) Example: GAL1704067200000
languageOptional	string	(string, optional): Preferred language for response messages (en, ar, ku) (string, optional): Preferred language for response messages (en, ar, ku) Example: en
limitOptional	string	(integer, optional): Maximum number of packages to return (default: 50, max: 100) (integer, optional): Maximum number of packages to return (default: 50, max: 100) Example: 20
offsetOptional	string	(integer, optional): Number of packages to skip for pagination (default: 0) (integer, optional): Number of packages to skip for pagination (default: 0) Example: 0
statusOptional	string	Filter by package status (optional) (string, optional): Filter by package status (claimed, received, in_transit, delivered, etc.) Filter by package status (optional) (string, optional): Filter by package status (claimed, received, in_transit, delivered, etc.)

Headers

Parameter	Type	Description
AuthorizationRequired	string	Bearer token authentication (required) Bearer token authentication (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/express-shipping/order/customer/GAL1704067200000?language=en&limit=20&offset=0" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success Response - Package List200 · Success Response - Empty List400 · Error - Missing Customer ID400 · 400 - Invalid Pagination404 · 404 - Customer Not Found500 · 500 - Internal Server Error

200OK

Response body

json

1{2  "success": true,3  "data": {4    "packages": [5      {6        "tracking_number": "GL1706371234567",7        "order_id": "TREND-ORD-98765",8        "status": "in_transit",9        "payment_status": "paid",10        "declared_value": 125.5,11        "currency": "USD",12        "store_name": "Trendyol",13        "claimed_at": "2024-01-27T10:00:00Z",14        "created_at": "2024-01-27T10:00:00Z"15      },16      {17        "tracking_number": "GL1706371234568",18        "order_id": "AMZN-ORD-12345",19        "status": "delivered",20        "payment_status": "paid",21        "declared_value": 89.99,22        "currency": "USD",23        "store_name": "Amazon",24        "claimed_at": "2024-01-25T08:30:00Z",25        "created_at": "2024-01-25T08:30:00Z"26      }27    ],28    "total": 2,29    "limit": 20,30    "offset": 0,31    "has_more": false32  }33}

List All Packages with Pagination and Search

Express Shipping / Order / Package Tracking

GET/express-shipping/order/list

API: List All Packages with Pagination and Search

Endpoint

GET /express-shipping/order/list

Purpose

Retrieve all packages for a tenant with comprehensive filtering, search, and pagination capabilities. Ideal for admin dashboards and package management interfaces.

• Bearer token: Authorization: Bearer {{access_token}} (required)

• API Key: X-API-Key: {{api_key}} (alternative authentication method)

Business Logic

1. Validate tenant has active express shipping service

2. Apply all filters and search criteria

3. Execute paginated query with proper sorting (newest first)

4. Include customer information for each package

5. Return comprehensive package list with pagination metadata

Error Responses

400 - Invalid Pagination

403 - Express Shipping Not Configured

404 - Customer Not Found (when filtering by customer_id)

500 - Internal Server Error

Usage Examples

1. List all packages (first page): GET /express-shipping/order/list-all

2. Search by tracking number: GET /express-shipping/order/list-all?search=GL123

3. Filter by customer: GET /express-shipping/order/list-all?customer_id=GAL1704067200000

4. Filter by status: GET /express-shipping/order/list-all?status=claimed

5. Combine filters with pagination: GET /express-shipping/order/list-all?status=claimed&search=TREND&page=2&limit=10

6. Filter by payment status: GET /express-shipping/order/list-all?payment_status=pending&limit=50

Query parameters

Parameter	Type	Description
pageOptional	string	(integer, optional): Page number for pagination (default: 1) (integer, optional): Page number for pagination (default: 1) Example: 1
limitOptional	string	(integer, optional): Maximum number of packages per page (default: 20, max: 100) (integer, optional): Maximum number of packages per page (default: 20, max: 100) Example: 20
searchOptional	string	Search by tracking number or order ID (optional) (string, optional): Search by tracking number or order ID (case-insensitive partial match) Search by tracking number or order ID (optional) (string, optional): Search by tracking number or order ID (case-insensitive partial match) Example: GL123
customer_idOptional	string	Filter by specific customer ID (optional) (string, optional): Filter by specific customer ID Filter by specific customer ID (optional) (string, optional): Filter by specific customer ID Example: GAL1704067200000
statusOptional	string	Filter by package status (optional) (string, optional): Filter by package status (claimed, received, in_transit, delivered, etc.) Filter by package status (optional) (string, optional): Filter by package status (claimed, received, in_transit, delivered, etc.) Example: claimed
payment_statusOptional	string	Filter by payment status (optional) (string, optional): Filter by payment status (pending, paid, failed, refunded) Filter by payment status (optional) (string, optional): Filter by payment status (pending, paid, failed, refunded) Example: pending
languageOptional	string	(string, optional): Preferred language for response messages (en, ar, ku) (string, optional): Preferred language for response messages (en, ar, ku) Example: en

Headers

Parameter	Type	Description
AuthorizationRequired	string	Bearer token authentication (required) Bearer token authentication (required) Example: Bearer {{access_token}}

Staging

Request

curl

1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/express-shipping/order/list?page=1&limit=20&search=GL123&customer_id=GAL1704067200000&status=claimed&payment_status=pending&language=en" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200 · Success Response - All Packages List200 · Success Response - Search Results200 · Success Response - Empty Results400 · Error - Invalid Pagination403 · Error - Express Shipping Not Configured404 · 404 - Customer Not Found (when filtering by customer_id)500 · 500 - Internal Server Error

200OK

Response body

json

1{2  "success": true,3  "data": {4    "packages": [5      {6        "tracking_number": "GL1706371234567",7        "order_id": "TREND-ORD-98765",8        "status": "claimed",9        "payment_status": "pending",10        "declared_value": 125.5,11        "currency": "USD",12        "store_name": "Trendyol",13        "weight": 1500,14        "quantity": 3,15        "claimed_at": "2024-01-27T10:00:00Z",16        "created_at": "2024-01-27T10:00:00Z",17        "updated_at": "2024-01-28T14:30:00Z",18        "customer": {19          "customer_id": "GAL1704067200000",20          "name": "John Doe",21          "email": "john@example.com",22          "phone": "+964751234567"23        }24      },25      {26        "tracking_number": "GL1706371234568",27        "order_id": "AMZN-ORD-12345",28        "status": "delivered",29        "payment_status": "paid",30        "declared_value": 89.99,31        "currency": "USD",32        "store_name": "Amazon",33        "weight": 800,34        "quantity": 1,35        "claimed_at": "2024-01-25T08:30:00Z",36        "created_at": "2024-01-25T08:30:00Z",37        "updated_at": "2024-01-26T12:15:00Z",38        "customer": {39          "customer_id": "GAL1704067200001",40          "name": "Jane Smith",41          "email": "jane@example.com",42          "phone": "+964751234568"43        }44      }45    ],46    "pagination": {47      "page": 1,48      "limit": 20,49      "total": 150,50      "total_pages": 851    }52  }53}