1. Platform overview
CityHop provides delivery infrastructure that businesses can connect to their own websites, applications, ordering systems and operational software. The integrating business retains its customer relationship and submits delivery information to CityHop.
What the API provides
- Delivery quote calculation.
- Delivery submission using your authenticated business account.
- A unique CityHop tracking identifier.
- Retrieval of delivery details and current recorded status.
- Separate Sandbox and Live environments.
What the API does not provide
- Automatic driver assignment at the moment of API submission.
- Driver GPS coordinates or driver personal contact information.
- A public customer tracking page through the authenticated status endpoint.
- A payment-processing endpoint or a client-controlled delivery price.
2. Quickstart
Use this sequence to build your first integration.
- Create a developer account at Developer Registration.
- Verify your email address using the verification process.
- Sign in to the Developer Dashboard.
- Retrieve your Sandbox API key from the dashboard. Copy and store it securely.
- Use the Sandbox base URL and test the health endpoint.
- Request a quote, submit a test delivery and retrieve its status.
- Complete your integration checks and request Production access.
- After approval and business-account association, use the Live API credential management page to generate a Live key.
- Configure your production application with the Live base URL and Live key.
Sandbox health check
GET https://cityhopdelivery.ca/sandbox/api/v1/health.php
The health endpoint is intended to confirm that the Sandbox API service is responding. It does not create a delivery and does not require an API key.
First authenticated request
curl -X POST "https://cityhopdelivery.ca/sandbox/api/v1/quotes.php" \
-H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"distance_km": 8.5,
"package_count": 1,
"package_size": "Small",
"vehicle_type": "standard",
"service": "standard"
}'
3. Registration and onboarding
Developer registration
Developers can register through the online developer registration page. Registration creates a developer profile, and email verification is required for the account to proceed through the applicable developer access process.
Sandbox access
Sandbox access is designed for self-service testing. After registration and sign-in, the Developer Dashboard provides access to Sandbox credentials and the documentation. Sandbox testing does not require Production approval.
Production access
Production access is a separate approval process. A developer submits a Production access request with information about the integration, intended use and estimated delivery volume. CityHop reviews the request and associates approved access with an eligible business account.
4. API environments
| Environment | Base URL | Purpose |
|---|---|---|
| Sandbox | https://cityhopdelivery.ca/sandbox/api/v1/ |
Integration development and simulated delivery testing. |
| Live | https://cityhopdelivery.ca/api/v1/ |
Approved business delivery operations. |
Keep environments separate
- Use a Sandbox key only with the Sandbox base URL.
- Use a Live key only with the Live base URL.
- Do not use Sandbox delivery records as production order records.
- Keep test and production credentials in separate configuration settings.
- Do not assume Sandbox prices are the prices that will apply to a Live business account.
5. Authentication
Authenticated API requests use a Bearer token in the HTTP
Authorization header.
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Authentication requirements
- Include the Authorization header on every authenticated request.
- Use the key issued for the environment being accessed.
- Do not send the API key as a query-string parameter.
- Do not send the API key in the JSON request body.
- Use HTTPS for all requests.
Live key validation
Live authentication checks that the supplied key exists, is active
and matches its stored credential hash. The key is associated with
a business account. That account must have an eligible
active or approved status and
login_enabled must be enabled.
The business identity is determined by the authenticated credential. Do not submit a different business ID in the request body to select another business.
Credential handling
- Store credentials in server-side environment variables or a secure secrets manager.
- Restrict access to production credentials to authorized personnel.
- Never commit keys to Git or include them in application logs.
- Rotate a credential if it may have been exposed.
- Remember that rotating or revoking a Live key can interrupt every integration using that key.
6. Sandbox API
Sandbox provides simulated delivery operations for integration development. Sandbox requests use a separate developer credential and separate Sandbox records.
| Method | Endpoint | Authentication | Purpose |
|---|---|---|---|
| GET | /health.php |
No | Service health check. |
| POST | /quotes.php |
Yes | Calculate a demonstration quote. |
| POST | /deliveries.php |
Yes | Create a simulated delivery. |
| GET | /delivery-status.php?tracking_id=... |
Yes | Retrieve a simulated delivery record. |
Sandbox quote example
POST /quotes.php
{
"distance_km": 8.5,
"package_count": 1,
"package_size": "Small",
"vehicle_type": "standard",
"service": "standard"
}
Sandbox quote response example
{
"success": true,
"quote": {
"quote_reference": "SBX-EXAMPLE",
"currency": "CAD",
"distance_km": 8.5,
"package_count": 1,
"package_size": "Small",
"vehicle_type": "standard",
"service": "standard",
"breakdown": {
"base_fee": 8.00,
"distance_charge": 10.63,
"package_charge": 2.00,
"minimum_applied": false
},
"total_before_tax": 20.63,
"tax_included": false,
"pricing_type": "sandbox_demonstration"
}
}
Illustrative response. The Sandbox demonstration formula is $8 base + $1.25 per kilometre + $2 per package, subject to a $10 minimum. The example uses 8.5 km and one package. Values are demonstration values, not production pricing.
Sandbox quote input rules
| Field | Requirement |
|---|---|
distance_km | Required number from 0 to 500. |
package_count | Optional; defaults to 1. Whole number from 1 to 20. |
package_size | Optional; Small, Medium or Large. Defaults to Small. |
vehicle_type | Optional; standard, car or van. Defaults to standard. |
service | Optional; standard, express or scheduled. Defaults to standard. |
Sandbox delivery creation example
POST /deliveries.php
{
"external_reference": "ORDER-10025",
"pickup_address": "Pickup business address",
"dropoff_address": "Recipient delivery address",
"customer_name": "Example Customer",
"customer_phone": "555-0100",
"item_description": "One sealed package",
"package_size": "Small",
"package_count": 1,
"vehicle_type": "standard",
"service": "standard",
"distance_km": 8.5,
"delivery_notes": "Leave with reception"
}
Sandbox delivery fields
external_reference: required; your unique order reference, up to 100 characters.pickup_address: required; up to 2,000 characters.dropoff_address: required; up to 2,000 characters.package_count: optional; whole number from 1 to 20.package_size: optional; Small, Medium or Large.vehicle_type: optional; standard, car or van.service: optional; standard, express or scheduled.distance_km: optional; defaults to 0 and must be between 0 and 500.customer_name: optional; maximum 120 characters.customer_phone: optional; maximum 30 characters.item_description: optional; maximum 5,000 characters.delivery_notes: optional; maximum 5,000 characters.scheduled_dateandscheduled_time: optional, but must be supplied together. Use YYYY-MM-DD and HH:MM formats.
Sandbox delivery response example
{
"success": true,
"message": "Sandbox delivery created successfully.",
"delivery": {
"id": 123,
"external_reference": "ORDER-10025",
"tracking_id": "SBX-EXAMPLE",
"status": "Pending",
"package_count": 1,
"package_size": "Small",
"vehicle_type": "standard",
"service": "standard",
"distance_km": 8.5,
"currency": "CAD",
"total_price": "SERVER_CALCULATED",
"tax_included": false,
"simulated_eta": "Simulation only - no driver assigned",
"tracking_url": "Authenticated Sandbox status endpoint"
},
"notice": "This is a simulated sandbox delivery."
}
Example is illustrative. The actual tracking URL returned by the API is an authenticated API endpoint, not a public customer tracking page.
Sandbox duplicate references
The external reference must be unique for the developer's Sandbox deliveries. If a duplicate is submitted, the API can return HTTP 409. Check the existing record before attempting another submission.
Sandbox tracking
GET /delivery-status.php?tracking_id=SBX-EXAMPLE
The authenticated tracking request returns the Sandbox delivery record associated with the developer's account. It includes the simulated status, addresses, schedule, package information, price, simulated ETA and record timestamps. It does not provide live driver location.
7. Live API
The Live API is used for approved business delivery operations. Its base URL is:
https://cityhopdelivery.ca/api/v1/
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /quotes.php |
Calculate a quote using the authenticated business account's pricing. |
| POST | /deliveries.php |
Submit a delivery into the CityHop delivery system. |
| GET | /delivery-status.php?tracking_id=... |
Retrieve a delivery associated with the authenticated business. |
Recommended integration sequence
- Collect the pickup, drop-off, package and distance information.
- Request a quote.
- Display the returned price to the appropriate user or business operator.
- After the order is confirmed, submit the delivery.
- Save the returned CityHop delivery ID and tracking ID against your order.
- Retrieve status using the tracking ID and update your order record.
8. Live delivery quotes
POST/quotes.php
Full URL:
https://cityhopdelivery.ca/api/v1/quotes.php
Request example
{
"service": "standard",
"vehicle_type": "standard",
"package_size": "Small",
"package_count": 1,
"distance_km": 8.5
}
Request fields
| Field | Type | Details |
|---|---|---|
service | String | Optional. Defaults to standard. |
vehicle_type | String | Optional. Defaults to standard. |
package_size | String | Optional. Defaults to Small. |
package_count | Integer | Optional. Defaults to 1; must be at least 1. |
distance_km | Number | Optional. Defaults to 0; must not be negative. |
Successful response structure
{
"success": true,
"quote": {
"...": "The pricing engine's quote details"
}
}
The quote object is generated by the CityHop pricing engine. It reflects the pricing configured for the authenticated business account, including applicable business-specific pricing.
Example cURL request
curl -X POST "https://cityhopdelivery.ca/api/v1/quotes.php" \
-H "Authorization: Bearer YOUR_LIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"service": "standard",
"vehicle_type": "standard",
"package_size": "Small",
"package_count": 1,
"distance_km": 8.5
}'
9. Create a Live delivery
POST/deliveries.php
Full URL:
https://cityhopdelivery.ca/api/v1/deliveries.php
Submit a confirmed delivery using the business's Live API credential. A successful request creates a delivery record in the existing CityHop delivery system.
Request example
{
"business_order_reference": "ORDER-10025",
"pickup_address": "Pickup business address",
"pickup_latitude": 43.4516,
"pickup_longitude": -80.4925,
"dropoff_address": "Recipient delivery address",
"item_description": "One sealed package",
"package_size": "Small",
"package_count": 1,
"distance_km": 8.5,
"customer_name": "Example Customer",
"phone": "555-0100",
"recipient_email": "customer@example.com",
"delivery_notes": "Leave with reception",
"scheduled_date": "2026-11-06",
"scheduled_time": "14:30",
"payment_method": "Business account"
}
Required fields
| Field | Type | Validation / purpose |
|---|---|---|
pickup_address | String | Required pickup address. |
pickup_latitude | Number | Required latitude, from -90 to 90. |
pickup_longitude | Number | Required longitude, from -180 to 180. |
dropoff_address | String | Required recipient destination. |
item_description | String | Required description of the item or items. |
package_size | String | Required: Small, Medium, Large or Bulky. |
package_count | Integer | Required; at least 1. |
Optional fields
| Field | Type | Purpose / validation |
|---|---|---|
business_order_reference | String | Your order identifier; maximum 100 characters. Use a unique value for each business order. |
distance_km | Number | Distance used for quote calculation. Defaults to 0; the delivery request requires a value greater than 0. |
scheduled_date | String | Optional date in YYYY-MM-DD format. |
scheduled_time | String | Optional time in HH:MM format. |
delivery_notes | String | Optional delivery instructions. |
customer_name | String | Optional recipient/customer name. |
phone | String | Optional recipient phone number. |
recipient_email | String | Optional recipient email address; must be valid if supplied. |
payment_method | String | Optional payment-method description. |
The Live endpoint currently uses the standard service and standard vehicle type. The service and vehicle are not selected by adding arbitrary values to the request body.
Successful response
A successfully created Live delivery returns HTTP 201.
{
"success": true,
"dispatch_status": "awaiting_admin_dispatch",
"delivery": {
"id": 12345,
"tracking_id": "CH-EXAMPLE",
"status": "Pending",
"payment_status": "Awaiting Payment",
"business_order_reference": "ORDER-10025",
"service": "standard",
"vehicle_type": "standard",
"package_size": "Small",
"package_count": 1,
"distance_km": 8.5,
"total_price": "SERVER_CALCULATED",
"currency": "CAD"
}
}
Illustrative response only. The actual price and tracking identifier are generated by CityHop. The response does not return the submitted addresses or customer contact information.
Important delivery-creation behaviour
- The authenticated business account is attached to the new delivery.
- The delivery price is calculated server-side.
- The API does not accept a client-supplied delivery price.
- A successful HTTP 201 means the delivery record was created.
- The initial delivery status is Pending.
- The initial payment status is Awaiting Payment.
- The delivery enters the CityHop administrative dispatch workflow.
- A successful response does not mean a driver has accepted the job.
Duplicate order protection
If business_order_reference is supplied, CityHop checks
for an existing delivery with that reference for the authenticated
business. A duplicate reference returns HTTP 409 and identifies the
existing delivery information.
Your integration should save the order reference before submission, handle a timeout as an uncertain result, and check for the existing delivery before retrying. Do not blindly create a new order reference after a timeout.
Example cURL request
curl -X POST "https://cityhopdelivery.ca/api/v1/deliveries.php" \
-H "Authorization: Bearer YOUR_LIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"business_order_reference": "ORDER-10025",
"pickup_address": "Pickup business address",
"pickup_latitude": 43.4516,
"pickup_longitude": -80.4925,
"dropoff_address": "Recipient delivery address",
"item_description": "One sealed package",
"package_size": "Small",
"package_count": 1,
"distance_km": 8.5
}'
10. Delivery tracking and status retrieval
GET/delivery-status.php
Full URL:
https://cityhopdelivery.ca/api/v1/delivery-status.php?tracking_id=YOUR_TRACKING_ID
Required query parameter
| Parameter | Requirement |
|---|---|
tracking_id | Required CityHop tracking identifier returned when the delivery is created. |
Example request
curl -X GET \
"https://cityhopdelivery.ca/api/v1/delivery-status.php?tracking_id=CH-EXAMPLE" \
-H "Authorization: Bearer YOUR_LIVE_API_KEY"
Successful response fields
| Field | Description |
|---|---|
id | CityHop delivery record ID. |
tracking_id | CityHop tracking identifier. |
business_order_reference | Your order reference, if supplied. |
status | Current recorded delivery status. |
payment_status | Current recorded payment status. |
scheduled_date | Scheduled delivery date, if available. |
scheduled_time | Scheduled delivery time, if available. |
pickup_address | Pickup address. |
dropoff_address | Drop-off address. |
item_description | Delivery item description. |
package_size | Recorded package size. |
package_count | Recorded package count. |
service | Recorded service type. |
vehicle_type | Recorded vehicle type. |
total_price | Business delivery charge, formatted to two decimal places. |
currency | CAD. |
eta | ETA value, if available. |
delivery_notes | Delivery notes, if available. |
payment_method | Payment method, if available. |
Tracking integration recommendation
- Save the CityHop tracking ID against your own order record after a successful creation response.
- Retrieve status using the authenticated endpoint.
- Update your own order-management system with the latest returned values.
- Display only the information appropriate for your customer-facing experience.
The endpoint is an authenticated business API. It is not a public customer tracking page and does not return driver GPS coordinates or driver personal contact details.
11. Field formats and integration guidance
JSON and content type
- Send JSON request bodies for POST endpoints.
- Set
Content-Type: application/json. - Use UTF-8 encoded JSON.
- Use a numeric JSON value for coordinates, distance and package count.
- Use strings for addresses, identifiers, dates and times.
Coordinates
Live delivery creation requires pickup coordinates. Latitude must be between -90 and 90, and longitude between -180 and 180. Send numeric coordinates, not formatted coordinate text.
Dates and times
- Date format:
YYYY-MM-DD. - Time format:
HH:MM, using a 24-hour clock. - Do not send locale-formatted dates such as 11/06/2026.
Order references
Use a stable, unique order reference from your own platform. References allow your team to reconcile orders and help prevent accidental duplicate submissions. Do not reuse the same reference for two different orders under the same business account.
Package sizes
The Live delivery endpoint accepts Small, Medium, Large and Bulky. The Sandbox demonstration endpoint accepts Small, Medium and Large. Send the supported value with the exact spelling shown.
12. HTTP responses and errors
Use the HTTP status code and the JSON response to determine whether
a request succeeded. Successful responses include
"success": true. Error responses use
"success": false and provide an
error.message.
Error response structure
{
"success": false,
"error": {
"message": "A description of the error."
}
}
Common HTTP status codes
| HTTP status | Meaning | Recommended action |
|---|---|---|
| 200 | Request succeeded. | Process the returned quote or tracking data. |
| 201 | Delivery created. | Save the delivery ID and tracking ID. |
| 400 | Invalid JSON or malformed request body. | Check JSON syntax and Content-Type. |
| 401 | Authentication failed. | Check the Bearer key, environment and credential status. |
| 403 | Business access is not eligible. | Check business approval and login-enabled status with the account administrator. |
| 404 | Requested tracking record not found for the authenticated account. | Check the tracking ID and account association. |
| 405 | HTTP method not supported for the endpoint. | Use the documented GET or POST method. |
| 409 | Duplicate business order reference. | Retrieve or reconcile the existing delivery; do not blindly resubmit. |
| 413 | Request body too large. Applies to Sandbox body-size limits. | Reduce the request body size. |
| 422 | Validation failed or required information is invalid. | Read the error message and correct the supplied fields. |
| 500 | Unexpected server, database or processing error. | Do not repeatedly submit the same order without checking whether it was created. |
Recommended client-side handling
1. Send the request.
2. Read the HTTP status.
3. Parse the JSON response.
4. If success is true, process the returned data.
5. If success is false, record error.message.
6. For a delivery timeout, check for the original order reference
before attempting another submission.
13. What happens after a Live delivery is submitted?
CityHop uses an administrative dispatch workflow. API delivery creation and driver assignment are separate steps.
- Business submission: your platform submits the delivery through the Live API.
- CityHop record: the API validates the request, calculates the price and creates the delivery record.
- Pending status: the new delivery is recorded as Pending and awaiting administrative dispatch.
- Administrative review: CityHop reviews the delivery and manages dispatch through its operational system.
- Driver earnings: the driver payment amount is managed separately from the business delivery charge.
- Driver acceptance: a driver may accept the dispatched delivery through the driver workflow.
- Status updates: the delivery status is updated through the operational workflow.
- Business tracking: your integration retrieves the recorded status through the tracking endpoint.
Recommended order states in your own system
Keep your own order state separate from the CityHop delivery status. Store the original order reference, CityHop delivery ID, tracking ID, latest status and latest payment status. Update these values from authenticated tracking responses rather than assuming that submission means completion.
14. Pricing, payment status and reconciliation
Business delivery price
The Live quote is calculated using the pricing configuration associated with the authenticated business account. Different businesses may have different pricing arrangements. Therefore, there is no single universal Live price formula that every integration should hardcode.
- Request a Live quote before confirming the delivery where appropriate.
- Use the returned quote information for the customer's or business operator's price display.
- The delivery-creation endpoint calculates the price on the server.
- The created delivery response returns the final business charge in CAD.
- Do not submit a price field to override CityHop's calculation.
Business charge and driver earnings are different
total_price returned by the API is the delivery
charge recorded for the business. It is not the driver's earnings.
CityHop manages driver earnings separately through its operational
process.
For example, a hypothetical business delivery charge of $7.00 does not mean that the driver receives $7.00. The business charge, driver earnings and CityHop's retained amount are separate accounting values.
Payment status
The delivery response initially reports the recorded payment status. The tracking endpoint can be used to retrieve the latest available payment status and payment method. The API endpoints documented here do not process card payments or collect a payment from the recipient.
Billing and reconciliation
Businesses should retain their own order reference, CityHop delivery ID, tracking ID, quoted amount, created delivery amount and returned payment status. Use the commercial billing arrangement agreed with CityHop for invoice and settlement reconciliation. Do not treat a successful API response as proof that an invoice has been paid.
15. Security and data handling
- Use HTTPS for every API request.
- Keep API credentials on your server, not in public browser JavaScript.
- Do not expose keys in mobile application source code or downloadable application bundles.
- Restrict credential access to staff and services that need it.
- Do not log full Authorization headers or API keys.
- Validate user input before submitting delivery information.
- Protect customer contact details and delivery addresses in your own system.
- Use separate credentials and configuration for Sandbox and Live.
- Revoke or rotate exposed credentials promptly.
- Do not use another business's credential or attempt to access its delivery records.
Customer information
Only send information required to fulfil and manage the delivery. Your business remains responsible for handling its customer information appropriately and for providing any notices or permissions required for its own collection and use of that data.
16. Troubleshooting
401 - Unauthorized
- Confirm that the Authorization header is present.
- Confirm that the value begins with
Bearerfollowed by a space. - Confirm that the key belongs to the environment in the URL.
- Check that the key has not been revoked or deactivated.
- Check for leading or trailing spaces in the stored key.
403 - Business access not available
- Confirm that the developer has approved access to the intended business.
- Confirm that the associated business account is active or approved.
- Confirm that business login access is enabled.
- Contact the authorized business administrator if access needs review.
400 - Invalid JSON
- Validate the JSON before sending it.
- Use double quotes around JSON property names and string values.
- Remove trailing commas.
- Set the Content-Type header to application/json.
422 - Validation error
- Check required fields and their exact names.
- Check numeric fields are sent as numbers.
- Check coordinate ranges and date/time formats.
- Check package size and other supported values.
- Read the error message returned by the endpoint.
409 - Duplicate order reference
The business order reference already exists for the authenticated business. Retrieve the existing delivery using its tracking ID or reconcile the existing record before proceeding.
404 - Delivery not found
- Check that the tracking ID was copied correctly.
- Check that the key belongs to the business that created the delivery.
- Check that you are using the correct environment.
Request timed out
A timeout does not prove that the server failed to create the delivery. Check the original business order reference and reconcile the result before retrying. Use a stable reference for each order.
Unexpected 500 response
Record the endpoint, time of request, HTTP status, business order reference and response message. Do not include API keys, passwords or unnecessary customer personal information in a support request.
17. Requesting Production access
Once the Sandbox integration is working, sign in to your Developer Dashboard and submit a Production access request.
Production review information
The request process collects information such as:
- Integration or application name.
- Intended use of the CityHop API.
- Estimated monthly delivery volume.
- Developer and business-account association information.
Approval and Live credentials
- CityHop reviews the Production access request.
- The developer must have an active, verified developer account.
- Approved access must be associated with an eligible business account.
- The business account must be active or approved and have login access enabled.
- After approval and association, the authorized developer can access Live credential management.
- Generate a Live credential and store it securely. The full key is displayed only when generated.
- Configure and test the production application using the Live base URL.
Credential rotation and revocation
Live credential management supports generating and revoking credentials for approved business access. Generating a replacement may deactivate the previous active credential. Revocation can interrupt every application using the affected key. Coordinate credential changes with all systems using that credential.
18. Integration and go-live checklist
Before requesting Production access
- Developer account registered and email verified.
- Sandbox credential securely stored.
- Sandbox health check successful.
- Sandbox quote request successful.
- Sandbox delivery creation successful.
- Sandbox tracking retrieval successful.
- Duplicate-reference handling implemented.
- Validation and authentication errors handled.
- Timeout and retry behaviour reviewed.
Before enabling Live traffic
- Production request approved.
- Developer access associated with the correct business account.
- Business account eligibility confirmed.
- Live credential generated and securely stored.
- Live base URL configured separately from Sandbox.
- Live quote tested using the business's actual pricing configuration.
- Delivery submission tested with an authorized business order.
- Tracking retrieval tested.
- Business order references stored and reconciled correctly.
- Manual dispatch expectations communicated to the operations team.
- Commercial billing and payment terms confirmed.
- Production error logging avoids credentials and unnecessary personal information.
19. Developer support
Review the relevant endpoint, authentication method, request fields and error response before escalating an integration issue. This documentation is intended to answer routine integration questions and provide a self-service path from registration through testing and Production onboarding.
Information to include when reporting a technical issue
- Environment: Sandbox or Live.
- Endpoint and HTTP method.
- Approximate request date and time.
- HTTP response status.
- Response error message.
- Business order reference, if applicable.
- A sanitized request body with credentials and unnecessary customer information removed.
Developer account: Sign in to the Developer Dashboard
New developer: Create a Developer Account