Welcome to the EziShipping API Developer Portal.
The EziShipping REST API allows you to integrate directly with our shipping platform to calculate shipping rates, create consignments, generate labels, track shipments, and retrieve Proof of Delivery (POD) information.
Getting Started
Follow these steps to begin integrating with EziShipping API.
Obtain your credentials
Obtain your Customer ID, API Username, and API Password from EziShipping.
Choose an API service
Select the required API endpoint from the API Collections menu.
Configure the endpoint
Replace all required placeholder variables in the endpoint URL with your account-specific values.
Authenticate your requests
All API requests require HTTP Basic Authentication using your assigned API credentials.
Test in Sandbox
Complete your integration testing using the Sandbox environment before moving to Production.
Move to Production
Production access is enabled after successful integration testing and validation.
Authentication
All API requests require HTTP Basic Authentication.
Setting
Value
Authentication Type
Basic Authentication
Username
Your assigned API Username
Password
Your assigned API Password
Environment URLs
Sandbox Environment
Use the Sandbox environment for development and integration testing.
https://betaapi.sampsonexpress.com.au/v3.6
Production Environment
Use the Production environment for live shipping transactions.
https://api.sampsonexpress.com.au/v3.6
Variable System
API endpoints use placeholder variables which must be replaced
before sending requests.
Variable
Description
{{host}}
API Base URL for the selected environment
{{customerId}}
Your assigned customer account number
Example Endpoint
{{host}}/customers/{{customerId}}/consignment/
Available API Services
The EziShipping API provides the following services:
Consignments
Create and manage shipping consignments.
Book A Pickup
Schedule and manage pickup requests.
Address Lookup
Validate and retrieve address information.
Shipping Calculator
Calculate available shipping options and rates.
Order
Create and manage shipping orders.
For detailed request parameters, response structures, and examples, select a service from the API Collections menu.
Important Notes
Before moving your integration to Production:
Sandbox data may not synchronise with Production in real time.
Sandbox environments may be refreshed periodically.
Test consignments should be thoroughly validated before Production use.
Production access is enabled after successful integration testing.
Always verify that your application is using the correct environment URL.
Do not use Production credentials in your Sandbox integration, or vice versa.
📞 Support
For API access issues, authentication problems, or integration assistance, contact our support team:
Please include your Customer ID, environment,
endpoint name and error details when contacting support.
Webhook
Overview
Webhooks enable EziShipping to deliver event notifications directly to your application. Rather than continuously polling the API for updates, your system can subscribe to specific events and receive notifications automatically whenever those events occur.
This event-driven approach reduces unnecessary API requests, improves efficiency, and ensures your application receives updates as soon as they are available.
How Webhooks Work
To receive webhook notifications, follow these steps:
Provide a Secure Endpoint
Configure an HTTPS endpoint within your application that can receive webhook requests from EziShipping.
Subscribe to Relevant Events
Select the event types that are relevant to your integration, such as:
Order Status Updates
Tracking Events
Connote Carrier Reference Changes
Provide a custom header Key and Value
The provided header key and value will be included in the POST request header that's sent to the provided end point.
You should use this header to validate and make sure the request is coming from MRL.
Receive Event Notifications
When a subscribed event occurs, EziShipping sends an HTTP POST request to your configured endpoint containing the event payload.
Acknowledge Receipt
After successfully processing the notification, your endpoint must return an HTTP 200 OK response. This confirms that the webhook has been received and processed successfully.
Benefits of Using Webhooks
Webhooks provide a more efficient alternative to API polling.
Traditional Polling
Without webhooks, your application must repeatedly query the API to determine whether shipment information has changed. This approach:
Generates unnecessary API traffic
Increases processing overhead
Introduces delays between an event occurring and your application becoming aware of it
Event-Driven Notifications
With webhooks enabled, EziShipping automatically pushes notifications to your application when an event occurs. This approach:
Delivers updates to your application when happened
Reduces API usage and network overhead
Simplifies integration architecture
Improves application responsiveness and data accuracy
Request Flow
Event Occurs in EziShipping
⬇
EziShipping Generates Webhook Event
⬇
HTTP POST Sent to Your Endpoint
⬇
Your Application Validates Request
⬇
Your Application Processes Event
⬇
HTTP 200 OK Response Returned
This workflow ensures that your application remains synchronized with shipment activity while minimizing API calls and processing overhead.
Sample Webhook Request
Example 1 — Tracking Update
{
"datetime": "2026-07-06 10:36:03",
"event": "CONNOTE_TRACKING",
"refNo": "CAFH662058",
"type": "CONNOTE",
"comment": "COD tracking event added to the connote"
}
Description: Triggered when new tracking information is added to a connote. This allows your system to receive the latest shipment updates and keep customers informed.
Example 2 — Order Status Update
{
"datetime": "2026-07-20 13:50:56",
"event": "ORDER_UPDATE",
"refNo": "WHO99703",
"type": "ORDER",
"comment": "Order status updated to Order Processed"
}
Description: Triggered when an order status changes, such as when an order is processed, finalised, or cancelled. This allows your system to keep order status up to date.
Description: Triggered when a carrier reference number is added or updated for a connote. This allows your system to keep the carrier reference up to date.
Frequently Asked Questions
This FAQ provides practical guidance for integrating with EziShipping
using the REST API and Webhooks. It covers authentication, security,
testing, troubleshooting, production readiness, and API changes.
TABLE OF CONTENTS
Select a topic below to jump directly to the relevant questions.
01
GETTING STARTED
The REST API uses a request-and-response model. Your application
sends a request to EziShipping to perform an action or retrieve
information, such as creating a consignment or retrieving
shipment details.
A Webhook uses an event-driven model. EziShipping sends an HTTP
notification to your configured endpoint when a supported
shipment event occurs.
In simple terms
REST API
Webhooks
Your application requests information or performs an action
EziShipping notifies your application when an event occurs
Request/response model
Event-driven model
Useful for creating consignments and retrieving data
Useful for receiving shipment updates
Initiated by your application
Initiated by EziShipping
Not necessarily. It depends on your integration requirements.
Use the REST API when your application needs to actively request
information or perform an action.
Use Webhooks when you want EziShipping to automatically notify
your application when a supported shipment event occurs.
Recommended approach
For many integrations, using both provides the most complete
experience: the REST API handles actions and data retrieval,
while Webhooks provide event notifications.
Yes. A sandbox environment is available for testing.
https://betaapi.sampsonexpress.com.au/v3.6
Use the sandbox environment to test your integration before
connecting to production.
Yes. Test and production environments should be treated as
separate environments, with the appropriate credentials used
for each.
Security reminder
Production credentials must be stored securely and must not
be included in development code, public repositories,
browser-based applications, or other client-side applications.
02
REST API
REST API requests must include the authentication credentials
required by EziShipping.
Store credentials securely within your application and include
them according to the authentication requirements specified in
the API documentation.
Never expose API credentials
Do not expose credentials in browser-based applications,
mobile applications, public repositories, or other
client-side code.
EziShipping API requests and responses use standard HTTP
conventions and JSON payloads where applicable.
Refer to the documentation for the relevant endpoint for:
Required request fields
Response structure
Data types
Supported HTTP methods
Required headers
Check both the HTTP response status code and the response body
before considering an operation complete.
Where provided, use response identifiers and reference numbers
to track the resulting consignment or shipment.
Important
An HTTP status code alone should not be used to determine
the complete outcome of an operation.
If an API request fails, inspect the HTTP status code and
response details to determine the cause.
Common causes include:
Invalid credentials
Missing or invalid request data
Invalid or unavailable resources
Temporary service issues
Your application should handle failures appropriately.
Do not automatically assume that a failed request means the
operation was not processed.
Where an operation could have been partially or successfully
processed, use the available reference information to verify
its status before retrying.
03
WEBHOOKS
A Webhook is an automated HTTP notification sent by EziShipping
to your application when a supported event occurs.
Instead of repeatedly requesting EziShipping for updates,
your application can receive notifications when relevant
shipment events occur.
Provide EziShipping with the endpoint that should receive your
Webhook notifications, together with any required authentication
or validation details.
Your endpoint should:
Be publicly accessible.
Accept HTTP POST requests.
Use HTTPS in production.
Be available whenever notifications are expected.
Be capable of processing the Webhook payload.
Validate the required authentication header before processing the event.
Yes. Production Webhook endpoints should use HTTPS with a
valid TLS certificate.
HTTPS protects communication between EziShipping and your
application and helps prevent information from being
intercepted during transmission.
EziShipping sends Webhook notifications using
HTTP POST requests.
Your endpoint must be configured to accept POST requests
and process the payload contained in the request.
Webhook payloads contain information about the event that
occurred and the relevant shipment or consignment.
The exact payload structure and available fields depend
on the Webhook event.
{
"datetime": "2026-07-06 10:36:03",
"event": "CONNOTE_TRACKING",
"refNo": "CAFH662058",
"type": "CONNOTE",
"comment": "COD tracking event added to the connote"
}
Validate Webhook requests using the custom header key and
value provided by EziShipping.
Your application should verify the expected authentication
header before processing the payload.
Security reminder
Do not rely solely on the contents of the payload to
determine whether a request is trusted.
If validation fails, the request should not be treated as
a trusted EziShipping notification.
After successfully receiving and processing a Webhook
notification, your endpoint should return:
HTTP 200 OK
Your endpoint should process notifications efficiently
and return the appropriate HTTP response without
unnecessary delays.
If your endpoint is unavailable or does not return a
successful HTTP response, Webhook delivery may be
considered unsuccessful.
Your application should be designed to handle temporary
connectivity issues and safely process the same event
if it is delivered again.
Yes. Your application should be designed to handle
duplicate Webhook notifications safely.
Idempotency
Webhook processing should be idempotent, meaning that
receiving the same event more than once must not result
in duplicate actions or incorrect shipment data.
Where an event identifier is provided, use it to identify
notifications that have already been processed.
Do not assume that Webhook events will always arrive in
chronological order unless EziShipping explicitly
guarantees event ordering.
Your application should use the event information and
shipment status provided in each notification to determine
the appropriate shipment state.
Webhooks are intended to provide timely notifications
when supported shipment events occur.
Actual delivery time may vary depending on system
processing, network conditions, and endpoint availability.
Important
Webhooks should therefore be treated as notifications
rather than a guaranteed real-time connection.
Yes. Webhook integrations should be thoroughly tested
before being enabled for production use.
During testing, verify that your endpoint can:
Receive HTTP POST requests.
Validate the required authentication header.
Parse the Webhook payload correctly.
Handle unexpected or missing fields safely.
Process duplicate notifications without creating duplicate actions.
Return HTTP 200 OK after successful processing.
Log sufficient diagnostic information to troubleshoot failed notifications.
04
SECURITY
API credentials must be stored securely and should never
be hard-coded into publicly accessible source code.
Recommended approaches include:
Secure environment variables
A secrets manager
An appropriate credential-management system
Access to production credentials should be limited to
authorised personnel and systems.
No.
API credentials should be used from a secure server-side
application or another protected environment.
Do not expose credentials in:
Browser JavaScript
Mobile application code
Public Git repositories
Client-side applications
Other environments where credentials can be extracted by end users
If you believe your API credentials or Webhook
authentication details have been compromised:
Contact EziShipping support as soon as possible.
Review application logs for suspicious activity.
Review access controls.
Rotate or replace compromised credentials where supported.
Update affected systems securely.
Never include compromised credentials
Do not include credentials or authentication secrets
in a support request.
05
TROUBLESHOOTING
Your application should handle standard HTTP response
codes and should not assume that every request will
return HTTP 200.
Status
Meaning
Typical action
2xx
Request was successfully received and processed
Process the response
4xx
Problem with the request, authentication, permissions, or supplied data
Review the request and response
5xx
Server-side or temporary service issue
Investigate the response and consider appropriate retry handling
Always review the response body and any available error
or reference information when troubleshooting.
Your application should fail safely if a Webhook payload
does not match the expected structure.
Before processing an event:
Validate required fields.
Handle missing or unexpected fields safely.
Log sufficient diagnostic information.
Prevent the unexpected payload from causing the entire Webhook service to fail.
For troubleshooting and monitoring, consider logging:
Request or event identifiers
Consignment or shipment references
Event type
Timestamp
HTTP status code
Processing result
Relevant error details
Never log sensitive information
Passwords
API credentials
Webhook authentication secrets
Other sensitive security information
Work through the following checks:
Confirm you are using the correct environment.
Confirm your credentials are valid.
Verify the request URL and HTTP method.
Confirm all required headers are included.
Verify that the request body matches the documented schema.
If using Webhooks, confirm the endpoint is publicly accessible over HTTPS.
Confirm the Webhook endpoint accepts HTTP POST requests.
Confirm the required Webhook authentication header is validated.
Confirm your application is returning the expected HTTP status code.
Review application logs and the API or Webhook response for additional details.
Still having trouble?
If the issue persists, contact EziShipping support
with the relevant request or event reference and
error details.
Do not send passwords, API keys, authentication
secrets, or other sensitive credentials.
06
PRODUCTION
Before going live, confirm that your integration has
been thoroughly tested and that:
Production credentials are configured securely.
HTTPS is enabled for production Webhook endpoints.
Webhook authentication is implemented.
API errors are handled appropriately.
Webhook processing is idempotent.
Logging and monitoring are in place.
Temporary service interruptions are handled safely.
Your team knows how to identify and troubleshoot failed requests.
Test and production configurations are clearly separated.
Production integrations should be monitored for:
Failed API requests
Webhook delivery failures
Authentication errors
Unexpected API responses
Unexpected Webhook payloads
Processing failures
Processing delays
Repeated or duplicate events
Monitoring helps identify integration issues before they
affect shipment processing or customer-facing systems.
07
API VERSIONS
Review the applicable EziShipping API documentation
and release communications for information about API
or Webhook changes.
Where API versions are provided, use the version
recommended for your integration and review upgrade
requirements before moving to a newer version.
Compatibility depends on the nature of the change and
the API version being used.
EziShipping should communicate breaking changes,
deprecations, or required migration actions through
the appropriate developer or customer communication
channels.
Before upgrading
Review the relevant documentation and test the
integration before deploying the change to production.
08
SUPPORT
If you have reviewed the API documentation and are still
experiencing an issue, contact EziShipping support with
as much relevant information as possible.
