Dubai Customs API integration for e-commerce platforms requires more than connecting a checkout or logistics system to a government portal. A production integration needs to account for Mirsal 2 declaration workflows, Dubai Trade registration, UAE Pass authentication, HS code classification, and structured commercial documents such as invoices, packing lists, certificates of origin, and bills of lading. Dubai Customs currently provides a B2B interface for eligible partners, so high-volume platforms need to establish the appropriate business connectivity before treating customs submission as a standard public API integration.

How Dubai Trade Fits Into the Customs Architecture

Dubai Trade is the operational single-window layer through which many Dubai trade and logistics services are accessed. Its ecosystem brings together Dubai Customs, DP World, Jebel Ali Free Zone and other trade and logistics stakeholders rather than requiring every operator to work with completely disconnected government and terminal systems.

For a software platform, that distinction matters.

A company building customs functionality for an e-commerce or logistics product should not treat Dubai Customs as an isolated endpoint. The application needs to understand the relationship between the company's Dubai Trade account, its Dubai Customs business registration, the relevant business type, authorised users, declaration workflows, and the systems through which cargo and customs transactions are processed.

Dubai Customs currently requires businesses to register before they can officially transact with Customs. The registration creates a customs business code associated with the company's licensing information. The current registration service requires a valid trade licence, authorised-person identification documents, and other information depending on the business type.

The registration model also changes according to the licensing structure.

A company holding a Dubai free-zone licence is treated differently from a company holding a licence issued by a free zone in another emirate. Dubai Trade's registration guidance, for example, distinguishes a Dubai free-zone business from an importer/exporter holding a free-zone licence issued elsewhere. Facility registration requirements can also vary according to the business activity.

That is important for platforms serving businesses across JAFZA, Dubai Airport Freezone, Textile City and other Dubai-based trade environments. The application should store the company's licensing and customs identity as structured master data instead of assuming that every customer follows the same registration path.

The same principle applies when the platform is designed for multiple companies.

A multi-tenant logistics or e-commerce platform may have hundreds of importers, exporters, fulfilment businesses, or logistics operators using the same software. Each organisation can have its own customs code, authorised users, declaration permissions, trade activities, and supporting documentation. Those identifiers must remain isolated at the tenant level.

The application therefore needs a customs identity layer sitting between the customer's operational data and the government-facing integration.

This layer can associate a shipment with the correct importing or exporting entity, determine the applicable declaration regime, select the appropriate declaration data, and retain the resulting customs reference and status against the original shipment.

Without that separation, a platform can have perfectly valid shipment data but still fail at the point where the government transaction requires the correct registered entity, business code, authorised user, or declaration type.

Mirsal 2 and UAE Pass Authentication

Mirsal 2 is the Dubai Customs declaration environment used for submitting and processing customs declarations. Dubai Trade provides web-based access, while Dubai Customs also supports electronic business connectivity for eligible partners that need to submit high volumes of declarations directly from their own systems.

This is the part of the architecture where the phrase "API integration" needs to be used carefully.

Dubai Customs does not present its Mirsal 2 B2G/B2B connectivity as an unrestricted public API that any developer can simply register for and start calling. Dubai Customs states that a B2B interface is available for eligible partners. Its B2G model has historically been designed around direct technical connectivity between an eligible company's internal system and Mirsal 2.

For a high-volume platform, this means the software project has two separate workstreams.

The first is the application architecture: modelling declarations, validating data, generating the required payloads, processing acknowledgements, recording customs references, handling payment states, and reconciling clearance or hold messages.

The second is the commercial and technical access arrangement with Dubai Customs.

The application should therefore be designed so that its customs adapter is isolated from the rest of the logistics platform. If the approved interface, message structure, authentication mechanism, or transaction rules change, the customs connector can be updated without rebuilding the shipment, order, inventory, or accounting modules around it.

Authentication has also changed materially in 2026.

Dubai Customs announced that UAE Pass digital identity authentication for Mirsal-related declarations and claims on Dubai Trade went live from 10 May 2026. The new mechanism allows eligible users to authenticate using UAE Pass rather than relying solely on the previous digital certificate authentication route. Dubai Customs also states that the Emirates ID information associated with the Mirsal user profile needs to match the UAE Pass account.

For users submitting declarations, account type matters as well. Basic UAE Pass accounts created without Emirates ID verification are not permitted for declaration and claim submission, while Advanced and Qualified UAE Pass accounts are supported.

The existing digital certificate mechanism continues alongside UAE Pass until further notice.

That creates an important distinction for developers.

A system should not hard-code one authentication method into the entire customs workflow. Authentication should be treated as a replaceable integration component with clear handling for authorised-user identity, company association, credentials, authentication status, expiry, and transaction signing.

For group structures, the same user may also be associated with multiple companies. Dubai Customs specifically supports linking UAE Pass credentials to multiple companies within a group where the user is authorised to act for those entities.

A properly designed platform therefore needs to distinguish the human user, the company they are acting for, and the customs authority transaction being submitted.

HS Code Classification Is Now a Software Problem

HS classification is one of the areas where a customs integration can fail even when the API connection itself works correctly.

The classification assigned to a shipment affects the declaration and can influence customs treatment, duties, restrictions, and statistical reporting. A platform that simply stores an HS code as an unvalidated text field leaves too much room for inconsistent or outdated classifications.

Dubai Customs has also been transitioning toward the GCC Integrated Customs Tariff at the 12-digit level.

The transition is phased, and the current position needs to be reflected carefully in software.

Dubai Customs Customs Notice No. 10/2025 introduced the phased move from the existing 8-digit classification structure toward 12-digit HS codes for relevant trade flows. However, Customs Notice No. 02/2026, issued on 30 January 2026, extended the flexibility to use 8-digit HS classifications until further notice and confirmed that Dubai Customs would continue accepting declarations submitted using 8-digit HS codes during that period.

That means a developer should not simply replace every 8-digit HS code field with a mandatory 12-digit field.

The correct architecture is a classification model capable of supporting both structures and applying the permitted classification according to the declaration's trade flow and the current Dubai Customs rules.

This is especially important for platforms processing different combinations of GCC trade, rest-of-world imports, free-zone movements, transshipments, transit transactions, and local exports.

A shipment record should therefore contain more than a single hs_code string.

The software can maintain the underlying commodity classification, the applicable tariff version, the classification digits permitted for that transaction, and the final code used in the declaration. This creates a historical record that allows the business to understand which classification was submitted and under which rule set.

The distinction is valuable when customs requirements change.

A hard-coded classification field can force developers to modify database structures and validation rules whenever the authority changes the tariff structure. A dedicated customs classification layer can accommodate the transition without affecting unrelated parts of the platform.

The same approach should apply to product catalogues.

An e-commerce platform may contain thousands of SKUs, but customs classification is normally shipment-specific and declaration-specific. Product master data can provide a default classification, while the customs engine validates whether that classification is appropriate for the destination, transaction type, and current tariff requirements before submission.

That prevents the product catalogue from becoming the sole source of truth for customs classification when the declaration context can change the applicable requirements.

Structuring Customs Documents Before Submission

A customs integration should not begin when an operator uploads a PDF.

The commercial documents behind a declaration contain structured information that should already exist inside the platform.

Dubai Customs identifies documents such as commercial invoices, packing lists, certificates of origin, delivery orders, bills of lading or airway bills, and applicable permits among the supporting documentation required for customs clearance, with requirements varying according to the declaration type and cargo channel.

For software developers, this means the document itself should not be the primary data model.

A commercial invoice contains supplier information, buyer information, invoice number, currency, line items, quantities, unit values, total values, and other information that may be required to support the declaration. A packing list provides package-level information. A bill of lading or airway bill identifies the transport movement. A certificate of origin establishes origin information.

Those fields should be represented as structured shipment data first, with the associated documents stored as evidence.

The application can then use the same structured data to generate declarations, validate documents, populate customs forms, support internal approvals, and maintain an audit history.

This also makes reconciliation easier.

If the declared customs value differs from the commercial invoice value, the platform should be capable of identifying the discrepancy before submission. If the consignee on the declaration does not match the shipment record, the system should flag it before the transaction reaches Customs. If an HS classification is missing from one line item, the declaration should not progress simply because the PDF invoice exists.

Document management and customs integration are therefore connected but separate functions.

The document repository stores the evidence. The customs data model stores the structured information extracted from or entered against those documents. The declaration engine determines what needs to be submitted for the relevant transaction.

That separation becomes particularly useful when the same shipment information feeds several systems.

An e-commerce platform might generate the commercial invoice. A warehouse management system might provide package dimensions and weights. A carrier system might provide the airway bill. An ERP might contain supplier and accounting information. The customs integration should reconcile these sources rather than requiring an operations employee to retype the same information into another portal.

Dubai Customs' own policies reflect the importance of consistency between the supporting documents and declaration data. Customs inspection procedures can involve reconciliation of the invoice, packing list, certificate of origin, bill of lading, marks and numbers, and the information contained in the declaration.

The software should therefore perform those checks before submission rather than treating them as something that happens only after Customs receives the declaration.

Dubai Customs' Cross-Border E-Commerce Platform

Dubai Customs has also operated a blockchain-based Cross Border e-Commerce Platform since its launch in 2020.

The platform was designed to connect and automate parts of the e-commerce supply chain involving Customs, free zones, logistics providers, and courier companies. Dubai Customs described the platform as supporting e-commerce transactions, customs declaration processes, returns, and visibility across participating stakeholders.

The existence of this platform is important for developers because it shows that Dubai's customs architecture is broader than the conventional model of one importer submitting one declaration through a web portal.

An e-commerce company processing a high volume of cross-border orders may have customs activity generated directly from its order and fulfilment systems. The software needs to understand where the company's own transaction flow ends and where Dubai Customs' approved digital channels begin.

Participation in an e-commerce customs network should therefore be treated as an integration programme rather than a simple REST endpoint.

The platform needs an internal order-to-shipment model, customs classification, document generation, return handling, customs status tracking, identity management, and exception processing before it can reliably exchange information with an external customs ecosystem.

This also matters for logistics providers and couriers serving multiple e-commerce merchants.

A logistics platform may receive an order from one merchant, fulfil it through a warehouse, assign a courier, generate transport documentation, and then create customs data. The customs transaction should remain connected to the original order and shipment throughout that process.

If the declaration number, customs status, document set, and shipment identifier are stored independently, operations teams eventually end up reconciling records manually.

A well-designed integration instead maintains a traceable chain from order to shipment to declaration to customs outcome.

Free Zone and Mainland Registration Are Not Identical

A customs integration serving UAE businesses cannot assume that every customer has the same licensing structure.

Mainland companies and Dubai free-zone companies enter the Dubai Customs ecosystem through business registration linked to their commercial licensing information. Dubai Trade's current registration guidance distinguishes Dubai free-zone businesses from companies holding free-zone licences issued by other emirates.

For Dubai-based free zones, the registration process can require the business type to be identified as "Free Zone" and may also require facility registration depending on the operation. Other free-zone entities may be classified differently within Dubai Customs' registration workflow.

This matters when building a multi-tenant platform for businesses operating from JAFZA, Dubai Airport Freezone, Textile City, or other specialised environments.

The software should capture the licensing authority, business type, customs business code, facility information where applicable, importer/exporter status, authorised persons, and relevant declaration permissions as separate fields.

That makes the system adaptable when one customer is a mainland importer while another operates from a Dubai free zone and another has a licence from a different emirate.

The objective is not to reproduce the licensing authority's registration system inside the software.

It is to make the customs integration aware of the business identity that already exists outside the application.

That distinction becomes particularly important for platforms serving groups with several companies. One organisation may import goods into the UAE mainland while another moves goods through a free-zone operation. Treating both as identical customers can result in incorrect declaration routing, incorrect facility information, or incomplete customs records.

Manual Customs Brokerage vs. Direct Platform Integration

Manual customs brokerage remains a valid operating model.

For a company importing occasionally, working with a licensed customs broker can be more practical than investing in a direct software integration. A broker can prepare and submit declarations, handle documentation, and coordinate customs procedures on the company's behalf.

The economics change when customs transactions become part of a high-volume digital operation.

An e-commerce marketplace, regional distributor, fulfilment provider, or logistics platform may generate hundreds or thousands of customs-related transactions. In that environment, re-entering order and shipment data into another system creates repeated administrative work and increases the chance of discrepancies.

Direct integration becomes valuable when customs activity is already a core part of the company's transaction flow.

The key point is that direct connectivity does not eliminate the need for customs expertise.

A software system still needs appropriate declaration rules, document controls, HS classification processes, exception handling, and human review where required. Integration automates the movement and validation of data; it does not replace the legal responsibilities of the importer, exporter, declarant, or customs broker.

Dubai Customs' current documentation confirms that high-volume eligible partners can use B2B connectivity for direct submission. The exact access model, technical specifications, onboarding requirements, and eligibility should therefore be confirmed with Dubai Customs before development begins.

For a new platform, that confirmation should happen during technical discovery rather than after the software has already been designed around assumptions about an undocumented public API.

What a Dubai Customs Integration Architecture Should Contain

A practical architecture separates the customs workflow into several logical layers.

The shipment layer holds the commercial movement: consignor, consignee, origin, destination, carrier, packages, weights, values, and shipment references.

The classification layer manages HS codes, tariff versions, product classifications, origin data, and transaction-specific validation.

The document layer stores invoices, packing lists, certificates of origin, bills of lading, airway bills, permits, and other supporting evidence.

The customs layer converts that internal data into the declaration structure required by the applicable Dubai Customs process.

The identity layer manages the relationship between the software user, the registered business, authorised persons, Dubai Customs business code, and applicable authentication mechanism.

The integration adapter then communicates with the approved Dubai Customs channel, whether the transaction is submitted through Dubai Trade or through an approved B2B/B2G connectivity arrangement.

Finally, the status layer receives and stores declaration numbers, charges, clearance messages, holds, amendments, cancellations, and other transaction outcomes.

This separation gives the business a usable customs record even when an external system is temporarily unavailable.

It also prevents the core logistics application from becoming tightly dependent on the implementation details of one government interface.

When Dubai Customs changes authentication, tariff rules, declaration structures, or digital services, the affected integration component can be updated without changing the entire order-management or warehouse system.

Dubai Customs Integration Requirements at a Glance

Requirement	What It Means	Software Implication
Dubai Trade registration	The business needs an appropriate customs identity and registration before transacting	Store business code, licence data, business type, facilities and authorised users
Mirsal 2	Customs declarations are processed through Dubai Customs' declaration environment	Build a dedicated declaration engine and status workflow
B2B/B2G connectivity	Direct system-to-system submission is available to eligible partners	Confirm eligibility and technical access before development
UAE Pass	UAE Pass authentication for Mirsal-related submissions is live from May 2026	Support authorised-user identity and authentication as a replaceable integration layer
HS classification	Dubai Customs is transitioning toward 12-digit GCC tariff classifications while 8-digit flexibility continues until further notice	Support both classification structures and transaction-specific validation
Customs documents	Invoice, packing list, origin, transport and permit data support declarations	Store document evidence separately from structured customs data
Free-zone registration	Dubai free-zone and other licensing structures can follow different registration classifications	Model business identity and facility information by entity
Customs status	Declarations can be cleared, held, amended or otherwise updated	Maintain an event-driven declaration status history

Frequently Asked Questions

What is Dubai Customs API integration?

Dubai Customs API integration connects a company's internal e-commerce, ERP, logistics, or fulfilment software with approved Dubai Customs digital transaction channels so declaration data can be exchanged without repeated manual entry. Dubai Customs currently provides B2B connectivity for eligible partners, so access and technical requirements need to be confirmed for the specific business before development.

Does Dubai Customs support direct system integration with Mirsal 2?

Yes. Dubai Customs supports direct B2B/B2G connectivity for eligible business partners, allowing approved systems to exchange declaration information with Mirsal 2. This should not be treated as an unrestricted public API; eligibility, onboarding, technical specifications, and connectivity arrangements need to be confirmed with Dubai Customs.

Can UAE Pass be used for Dubai Customs declarations?

Yes. Dubai Customs introduced UAE Pass digital identity authentication for declarations and claims on Dubai Trade from 10 May 2026. Advanced or Qualified UAE Pass accounts verified through Emirates ID are required for declaration and claim submission, while the existing digital certificate authentication mechanism continues alongside UAE Pass until further notice.

Are 12-digit HS codes mandatory for every Dubai Customs declaration?

No. Dubai Customs has been introducing the GCC Integrated Customs Tariff at the 12-digit level through a phased approach, but Customs Notice No. 02/2026 extended the flexibility to use 8-digit HS classifications until further notice. Software should therefore support both structures and apply the current rules according to the declaration's specific trade flow.

What documents are required for Dubai Customs clearance?

Requirements depend on the declaration type and cargo channel, but commonly required documents include the commercial invoice, packing list, certificate of origin, delivery order, and bill of lading or airway bill. Applicable permits may also be required for restricted goods. A software platform should structure the underlying information rather than treating these documents as disconnected PDF attachments.

Building Dubai Customs Integration Into the Platform, Not Around It

Dubai Customs integration becomes materially different once customs clearance is part of the core transaction flow rather than an occasional manual activity. Mirsal 2, Dubai Trade registration, UAE Pass authentication, HS classification, structured documentation, and approved B2B connectivity all need to fit into the same shipment lifecycle.

For platforms focused specifically on Jebel Ali operations, the DP World VBS integration and demurrage avoidance guide covers the next layer of the problem: coordinating customs readiness with carrier release and terminal gate appointments. This article is the broader customs and e-commerce integration pillar; the VBS piece focuses specifically on what happens after the customs workflow reaches the port.

The right implementation depends on the company's trade flows, transaction volume, licensing structure, existing ERP or e-commerce stack, and the connectivity Dubai Customs makes available to that business. A software architecture can be scoped around those variables rather than assuming every importer needs the same integration.

For a Dubai e-commerce or logistics platform, the practical starting point is a discovery session that maps the existing order, shipment, document, customs and carrier workflows before development begins. Pixbit can scope the customs integration, internal data model and approved external connectivity together in that session.