Getting Started
Follow these steps to get started with GTA API integration:
Request API Access
Sign up for a developer account and request API access. Your request will be reviewed by our team.
Register NowGet Your API Key
Once approved, generate your API key from the portal. Store it securely as it will only be shown once.
Fund Your Wallet
Add credits to your wallet to cover shipment costs. Credits are deducted automatically for each shipment.
Start Integrating
Use the endpoints below to integrate GTA delivery services into your application.
Authentication
All API requests require authentication using a Bearer token in the Authorization header.
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/jsonhttps://toppingcourier.ca/api/gta-api
API Endpoints
/shipments/quote
Get Quote
Get a price quote for a shipment without creating an order. This endpoint does not charge your wallet.
/shipments
Create Shipment
Create a new GTA delivery shipment. Credits will be deducted from your wallet upon successful creation.
/shipments/{tracking_id}
Get Shipment Status
Retrieve the current status and details of a shipment using its tracking ID.
/shipments/{tracking_id}/cancel
Cancel Shipment
Cancel a pending shipment and receive a refund to your wallet. Only available for shipments in pending or assigned status.
Request Examples
Quote Request
curl -X POST https://toppingcourier.ca/api/gta-api/shipments/quote \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"service_level": "express_3h",
"pickup_phone": "416-555-0123",
"pickup_address": "124 Front St W, Toronto, ON M5J 1A5",
"customer_name": "John Doe",
"customer_phone": "647-555-9977",
"customer_address": "55 Bloor St W, Toronto, ON M4W 1A5",
"pickup_date": "2025-01-20",
"pickup_time": "14:30"
}'Create Shipment Request
{
"service_level": "express_3h",
"distance_km": 12.4,
"pickup_name": "Operations Department",
"pickup_phone": "416-555-0123",
"pickup_address": "124 Front St W, Toronto, ON M5J 1A5",
"pickup_postal_code": "M5J 1A5",
"pickup_lat": 43.6445,
"pickup_lng": -79.3889,
"pickup_date": "2025-01-20",
"pickup_time": "14:30",
"customer_name": "John Doe",
"customer_phone": "647-555-9977",
"customer_address": "55 Bloor St W, Toronto, ON M4W 1A5",
"customer_postal_code": "M4W 1A5",
"customer_lat": 43.6702,
"customer_lng": -79.3867,
"note": "Please ring doorbell. Signature required.",
"surcharges": [
{
"code": "after_hours",
"quantity": 1
},
{
"code": "weekend",
"quantity": 1
}
]
}Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
service_level |
string | Yes | Service level: express_3h, express_5h, same_day, next_day |
pickup_phone |
string | Yes | Pickup location phone number |
pickup_address |
string | Yes | Full pickup address |
customer_name |
string | Yes | Recipient name |
customer_phone |
string | Yes | Recipient phone number |
customer_address |
string | Yes | Full delivery address |
pickup_date |
date | Optional | Pickup date (YYYY-MM-DD). Defaults to today. |
pickup_time |
time | Optional | Pickup time (HH:MM). Defaults to current time + 1 hour. |
distance_km |
float | Optional | Distance in kilometers. Will be calculated if not provided. |
surcharges |
array | Optional | Array of surcharge objects with code and quantity |
note |
string | Optional | Special delivery instructions |
Response Examples
Quote Response
{
"quote": {
"subtotal": 15.50,
"tax": 2.01,
"grand_total": 17.51,
"distance_km": 12.4,
"estimated_delivery_time": "2025-01-20 17:30:00"
},
"distance": {
"km": 12.4,
"text": "12.4 km",
"duration_text": "18 minutes"
}
}Create Shipment Response
{
"message": "Shipment created successfully.",
"tracking_id": "GT12345678",
"parcel_id": 9123,
"grand_total": 18.75
}Get Shipment Response
{
"tracking_id": "GT12345678",
"status": "pending",
"customer_name": "John Doe",
"customer_phone": "647-555-9977",
"pickup_date": "2025-01-20",
"pickup_time": "14:30",
"grand_total": 18.75
}Error Handling
The API uses standard HTTP status codes to indicate success or failure. Error responses include a message and optional errors array.
Unauthorized
Missing or invalid API key. Check your Authorization header.
{
"message": "Unauthenticated."
}Payment Required
Insufficient credits in your wallet. Top up your wallet to continue.
{
"message": "Insufficient GTA API credits for this shipment."
}Not Found
The requested shipment or resource was not found.
{
"message": "Shipment not found."
}Conflict
The shipment cannot be cancelled in its current status.
{
"message": "Shipment can no longer be cancelled."
}Unprocessable Entity
Validation error. Check the errors array for details.
{
"message": "The given data was invalid.",
"errors": {
"customer_address": [
"The customer address field is required."
]
}
}Too Many Requests
Rate limit exceeded. Check your daily and monthly quotas.
{
"message": "Rate limit exceeded."
}Rate Limits & Quotas
To ensure fair usage and system stability, the GTA API enforces rate limits:
Daily Limit
500
requests per day
Resets at midnight Toronto time
Monthly Quota
5,000
requests per month
Resets on the 1st of each month
Best Practices
Secure Your API Key
Never commit your API key to version control. Use environment variables or secure key management systems.
Monitor Your Wallet Balance
Keep sufficient credits in your wallet. Set up low balance alerts to avoid service interruptions.
Use Quote Endpoint First
Always call the quote endpoint before creating shipments to show pricing to users and validate addresses.
Handle Errors Gracefully
Implement proper error handling and retry logic. Check status codes and error messages before retrying.
Respect Rate Limits
Implement exponential backoff when hitting rate limits. Monitor your usage to stay within quotas.
Validate Addresses
Provide accurate addresses with postal codes and coordinates when possible to ensure correct pricing and routing.