Generating labels for international shipments requires additional customs information that domestic labels do not. If your label fails when shipping to an international destination, the error is almost always a validation failure from the courier’s API — the courier requires specific data fields that are missing, incorrectly formatted, or incomplete. This article covers the most common causes and how to resolve them.
Common international label errors
International label failures typically fall into one of four categories.
Error category | What it means | Where to look |
UKIMS or customs authorisation | A customs authorisation number required for the shipment is not configured | Courier integration settings |
Missing commodity codes | Products are missing HS codes required by customs for this destination | Product catalogue settings |
Commercial invoice validation | The courier cannot generate a commercial invoice due to missing data | Order details and courier integration settings |
Destination restriction | The selected courier service does not cover the destination country or postcode | Courier service configuration |
UKIMS and customs authorisation errors
UKIMS (UK Internal Market Scheme) numbers are required for certain shipments between Great Britain and Northern Ireland. Some couriers also require customs authorisation numbers for specific international services.
Check the error message for references to UKIMS, authorisation number, or customs credentials.
Click Connect then Courier Integrations, select the affected courier, and click Edit.
Look for a UKIMS Number or Customs Authorisation Number field. Enter your number if the field is present and blank.
If you do not have a UKIMS number and your shipments require one, refer to HMRC guidance at gov.uk or contact your courier account manager.
Missing or invalid commodity codes
Commodity codes (also called HS codes or tariff codes) are required on customs declarations for most commercial international shipments. The courier’s API will reject the label request if codes are missing or invalid.
Open the product in Mintsoft and check whether a commodity code or HS code is populated in the product settings.
If the field is blank, enter the correct code. Use the UK Trade Tariff tool at trade-tariff.service.gov.uk to find the appropriate code for your product type.
Save the product record and retry generating the label.
If you are shipping multiple products, ensure all items in the shipment have a commodity code — a label cannot be generated if any item is missing one.
Note: Some couriers also require a commodity code description in plain English alongside the numeric code. If the error references a missing description, add a short product description to the relevant field in the product or order settings.
Commercial invoice validation errors
Couriers such as FedEx and DHL generate commercial invoices automatically as part of the international label process. If required data is missing, the label request fails. Common causes include:
Sender or recipient address is incomplete — for example, missing postcode, country, or phone number.
Shipment value or currency is not populated on the order.
For FedEx: a signature file or company letterhead required for commercial invoices to certain destinations has not been uploaded to the FedEx integration settings.
For DHL: the shipper details in the DHL integration settings do not exactly match those registered on your DHL account.
Open the order and verify the sender and recipient addresses are complete, including postcode, country, and phone number.
Check the order for a declared or shipment value field. Enter the total value of the goods in the correct currency if blank.
For FedEx commercial invoice errors: click Connect then Courier Integrations, select your FedEx account, and click Edit. Check whether a signature file and company letterhead have been uploaded, and upload them if required.
For DHL commercial invoice errors: verify that the shipper name and address in the DHL integration settings exactly match the details registered on your DHL account.
Save any changes and retry generating the label.
Destination restrictions and service eligibility
Some courier services do not cover all international destinations. If the error references a postcode, country, or service restriction:
Confirm with your courier account manager which countries and postcodes are supported by the selected service.
Switch to an alternative courier service that supports the destination, or contact the courier to request access for that destination.
See the Resolve courier service issues related to service rules and code mapping article for steps to update service configurations in Mintsoft.