This guide explains how to use Mintsoft's Shipping API and Courier Developer Portal to integrate courier services. The portal enables developers to create standardised shipping connections that function alongside Mintsoft's native integrations.
The guide covers both administrative setup and technical implementation, including API specifications, authentication requirements, and response structures.
Overview
Shipping API
The Shipping API provides a standardised set of calls and webhooks for extracting shipping information from Mintsoft. Developers can use this API to build middleware that connects Mintsoft with courier systems for data exchange, label generation, and returns processing.
Courier Developer Portal
The Courier Developer Portal allows developers to submit courier services to the Mintsoft team for approval and deployment. Once approved, developers can configure live and test endpoints, manage API authentication keys, and deploy services that function identically to Mintsoft-developed integrations.
Important: Integrations added through the Courier Development Portal aren't supported or updated by Mintsoft Development. They must be maintained by either development services or the third-party developer who built the connection.
Solution Data Flow
The integration follows this workflow:
The courier portal deploys new couriers and services to Mintsoft.
Users select these services as they would any standard courier.
A label request triggers a webhook.
Standard information is sent via the Shipping API.
Developer-built middleware translates this into courier-specific requests.
The request is sent over the courier's API.
The label returns to the middleware.
The label is returned to Mintsoft for printing.
Administrator Guide
Creating Accounts
An existing administrator must create an account for new users.
Viewing Accounts and Connections
Click Accounts to view all accounts for your courier connection.
From this screen, you can create new accounts.
For developer accounts, click Connections to see associated connections.
Alternatively, click Courier Connections to view all connections.
Managing Connection Details
Select Details from the connections list to administer a connection.
Configure the following settings:
Available to All Customers
When enabled, the integration appears under Partners on Mintsoft's courier connection page. When disabled, the integration appears under the Custom tab.
Require Customer Approval
When enabled, customers must request access before creating an account. An Approvals menu option becomes available for managing access requests. Administrators receive email notifications when accounts are requested.
Enabled
Controls whether the courier's services are available in Mintsoft.
Note: For a connection to appear in Mintsoft, it must be both published and enabled.
Managing Customers
The Customers tab lists Mintsoft users currently using the integration.
Specific customers can be assigned to the integration. These customers are restricted to using only this integration if Available to All Customers isn't selected. Enabling Available to All Customers makes the integration available regardless of customer selection.
Managing Approvals
The Approvals tab only appears if Requires Customer Approval is enabled on the connection.
When enabled, administrators receive email notifications when accounts are requested from within Mintsoft. Administrators can grant or revoke connection access as required. Once approved, customers are automatically added to the Customers tab.
Developer Guide
Creating a Courier Connection
Click Courier Connections to add a new connection or view existing ones.
Enter the courier's name (maximum 50 characters).
Provide an email address for customer assistance.
Edit the courier connection to add additional information.
Enter the test and production endpoints (base URLs that Mintsoft will call to create and manage shipments).
Uploading Service Images
Upload an image of your service to appear on the courier connection page.
Click the Services tab to create named courier services (maximum 100 characters per service name).
Important: Image dimensions must be 800 pixels wide by 500 pixels high.
Managing API Keys
Click the API Keys tab to create API keys.
Your system will use these keys to validate Mintsoft service calls.
Important: Only one API key can be active at any time, but you can create multiple keys to enable seamless migration when needed.
Submitting for Approval
When you've finished configuring your services, submit the setup for approval.
Mintsoft will review your setup and either approve or reject your request.
If approved, you can publish your connection when you're ready.
If rejected, Mintsoft will contact you to explain what needs to be corrected.
Publishing Your Connection
Once published, your courier connection will appear either under the Partners or Custom tab on Mintsoft's courier connection page for use by customers.
Managing Account Settings
Click your login name to change account settings at any time.
Syncing Services
Mintsoft automatically syncs any edits or new services added through the portal. Users can also manually sync courier services within Mintsoft:
Go to Connect > Courier Integrations > Partner or Custom
Select the courier.
Click Sync Services.
Note: To automatically send services to Mintsoft from the developer portal, click Back and then Save on the courier connection screen.
Order Tracking
If a tracking URL is included in the Create Shipment response under the Packages Object, users can track orders:
Navigate to the order overview.
Click the Action button.
Select Tracking.
Users will be directed to the correct URL to track their order.
Shipping API Technical Guide
Authentication
The active API key from the Developer Portal is included in request headers under the key x-api-key. Customer account numbers and passwords are sent in the request body.
Endpoints
Create two endpoints at your base URL:
Create Shipment:
POST {url}/CreateShipmentCancel Shipment:
DELETE {url}/CancelShipment
All data is passed in JSON format in both requests and responses.
API Reference
Create Shipment Request - Shipment Object
Endpoint: POST /CreateShipment
Parameter | Description | Type | Optional |
Account Number | Client account number | String | No |
Password | Client password | String | No |
Shipment ID | Unique reference for the shipment | String | No |
Service Name | Service name | String | No |
Service Code | Service code | String | No |
Delivery Notes | Delivery notes | String | No |
Client | Supplier | String | No |
Warehouse | Source warehouse of items | String | No |
Order Number | Mintsoft order number | String | No |
External Order Reference | Third-party order number | String | No |
Channel | Sales channel | String | No |
Ship From | Supplier address and contact information | Ship From Object | No |
Ship To | Recipient address and contact information | Ship To Object | No |
Parcels | Unit of parcels | Parcel Object Array | No |
Cash On Delivery | Cash on delivery information | Cash on Delivery Object | No |
ShippingTotalExVat | Shipping total excluding VAT | String | Yes |
ShippingTotalVAT | Shipping total VAT | String | Yes |
Ship From Object
Parameter | Description | Type | Optional |
Email address for this entity | String | No | |
Phone | Telephone number for this entity | String | No |
Name | Contact name | String | No |
Company Name | Company name of the address | String | No |
Address Line 1 | First line of the address | String | No |
Address Line 2 | Second line of the address | String | Yes |
Address Line 3 | Third line of the address | String | Yes |
Town | Town of the address | String | No |
County | County of the address | String | No |
Postcode | Postcode of the address | String | No |
Country code | Two-character ISO 3166-1 country code | String | No |
VAT Number | VAT number of supplier | String | Yes |
EORI Number | Economic operators registration and identification number | String | Yes |
IOSS Number | Import One-stop shop number | String | Yes |
UKIMS Number | UK Internal Market Scheme number | String | Yes |
VOEC Number | VAT on eCommerce number | String | Yes |
Recipient Type | B2B or B2C | String | Yes |
Cash on Delivery Object
Parameter | Description | Type | Optional |
Amount | Amount in decimal format | Decimal | No |
Currency | Currency in three-letter format (e.g., GBP) | String | No |
Ship To Object
Parameter | Description | Type | Optional |
Email address for this entity | String | No | |
Phone | Telephone number for this entity | String | No |
Name | Contact name | String | No |
Company Name | Company name of the address | String | No |
Address Line 1 | First line of the address | String | No |
Address Line 2 | Second line of the address | String | Yes |
Address Line 3 | Third line of the address | String | Yes |
Town | Town of the address | String | No |
County | County of the address | String | No |
Postcode | Postcode of the address | String | No |
Country code | Two-character ISO 3166-1 country code | String | No |
VAT Number | VAT number of supplier | String | Yes |
EORI Number | Economic operators registration and identification number | String | Yes |
PID Number | PID Number | String | Yes |
Recipient Type | B2B or B2C | String | Yes |
National Address Code | National Address Code | String | Yes |
Parcel Object
Parameter | Description | Type | Optional |
Parcel Number | Sequence number of the parcel | Integer | No |
Unit of Length | Unit of measurement for length, width, and height (allowed value: cm) | String | No |
Length | Length of parcel | Decimal | No |
Width | Width of parcel | Decimal | No |
Height | Height of parcel | Decimal | No |
Unit of Weight | Unit of measurement for weight (allowed value: kg) | String | No |
Weight | Weight of the parcel | Decimal | No |
Cost | Total cost of items in the parcel | Decimal | No |
Parcel Items | List of items in the parcel | Parcel Item Object Array | No |
Note: Exact values are sent for parcel weight and cost.
Parcel Item Object
Parameter | Description | Type | Optional |
Title | Product name | String | No |
SKU | Product SKU | String | No |
Quantity | Quantity of the product | Integer | No |
Unit Weight | Weight of one item | Decimal | No |
Unit Price | Price of one item | Decimal | No |
Commodity Code | Product commodity code | String | Yes |
Customs Description | Description for customs | String | Yes |
Country of Manufacture | Country of manufacture for customs purposes | String | Yes |
Note: Exact values are sent for parcel item weight and price.
Create Shipment Response
Response Object
Parameter | Description | Type | Optional |
Success | Operation success or failure | Boolean | No |
Error Message | Error messages on failure | String Array | Yes |
Shipment | Shipment object | Shipment Object | Yes |
Shipment Object
Parameter | Description | Type | Optional |
Main Tracking Number | Tracking number of main or only parcel | String | No |
Label Format | Format label returned as (allowed values: PNG, PDF) | String | No |
Customs document format | Format of customs documents | String | No |
Packages | List of parcels | Package Object Array | No |
Packages Object
Parameter | Description | Type | Optional |
Parcel Number | Parcel sequence number | Boolean | No |
Tracking Number | Tracking number for this parcel | String Array | Yes |
Tracking URL | URL for tracking this parcel | String | Yes |
Label as Base 64 | Label image encoded as Base 64 | String | Yes |
Customs Document Name | Name of customs form (allowed values: CN22, CN23) | String | Yes |
Customs PDF Document as Base 64 | Customs document encoded as Base 64 | Package object Array | Yes |
Cancel Shipment Request
Endpoint: DELETE /CancelShipment
Parameter | Description | Type | Optional |
Account Number | Client account number | String | No |
Password | Client password | String | No |
Tracking Number | Mintsoft unique reference for the shipment | String | No |
Cancel Shipment Response - Response Object
Parameter | Description | Type | Optional |
Success | Operation success or failure | Boolean | No |
Error messages | Error messages on failure | String Array | Yes |