Skip to Content
ConfigurationDeclarant Configuration

Declarant Configuration

Declarants are customs-registered entities authorized to submit declarations on behalf of importers and exporters. This page explains how to configure and manage declarants in Borderbolt.

What is a Declarant?

A declarant is a legal entity registered with customs authorities and authorized to:

  • Submit customs declarations electronically
  • Act on behalf of importers/exporters
  • Hold customs authorizations (AEO, surety, DVA)
  • Communicate with customs authorities electronically

Key Characteristics:

  • Must have valid EORI number
  • Registered with customs authorities
  • Authorized to use customs declaration systems
  • May hold financial guarantees (surety, DVA)

Relationship to Customers:

  • In Borderbolt, declarants are a specialized type of customer
  • Marked with is_declarant = true flag
  • Have additional fields: postbus, surety settings, DVA guarantee

Managing Declarants

Declarants are managed in two locations:

1. Settings → Declarants

The primary location for declarant-specific configuration.

Available Functions:

  • Add new declarants
  • Configure EORI and postbus numbers
  • Sync with customs integration service
  • Test customs connectivity
  • View declarant status and authorizations

2. Customers Page (for Declarant Customers)

Per-declarant surety and DVA settings are now on the Customer page for customers with is_declarant = true.

Why This Location?:

  • Consolidates all declarant-related configuration
  • Declarants are a specialized type of customer
  • Simplifies data model and UI

Declarant-Specific Settings on Customer Page:

  • Surety limit per declarant
  • DVA guarantee amount
  • Declarant-specific thresholds
  • Customs authorization details

EORI Number

Economic Operator Registration and Identification

EORI is a unique identifier for customs operators in the EU.

Format: Country code (2 letters) + unique number

  • Netherlands: NL + 12 digits (e.g., NL123456789012)
  • Germany: DE + 9 digits (e.g., DE123456789)
  • Belgium: BE + 10 digits (e.g., BE0123456789)

Purpose:

  • Identifies declarant in customs communications
  • Required on all customs declarations
  • Used for authorization verification
  • Links to customs accounts and guarantees

Where EORI Appears:

  • Declaration header (Declarant field)
  • Customs communications
  • Electronic signature on declarations
  • Customs authorizations (AEO, DVA)

Critical: EORI number must exactly match your customs registration. Incorrect EORI will result in declaration rejections.

Postbus Number

Customs Mailbox Identifier

The postbus (Dutch: “post box”) is a unique identifier for receiving customs responses.

Format: EORI + extension + department code

  • Standard: NL123456789012.01.60
  • Pattern: {EORI}.{Extension}.{Department}

Components:

  • EORI: Your EORI number (e.g., NL123456789012)
  • Extension: Usually 01 for main account
  • Department: Typically 60 for declarations

Purpose:

  • Routes customs responses to correct recipient
  • Used by the customs integration service for automatic routing
  • Allows multiple postbus per EORI (departments)

Example:

Company: CustomsFlows B.V.
EORI: NL123456789012
Postbus Options:
- NL123456789012.01.60 (main declaration department)
- NL123456789012.02.60 (Amsterdam office)
- NL123456789012.03.60 (Rotterdam office)

EORI and Postbus Mapping

Customs Integration Service

Borderbolt uses a customs integration service to route customs responses to the correct organization.

How It Works:

  1. Customer sends declaration with declarant EORI
  2. Borderbolt submits to customs integration service
  3. Dutch Customs sends response to postbus
  4. Customs integration service looks up organization by EORI/postbus
  5. Customs integration service sends response to correct Borderbolt organization
  6. Borderbolt processes response and updates declaration

Registering Identifier Mappings

Mappings are created automatically when you add a declarant in Settings → Declarants.

Manual Configuration (if needed):

  • Contact your system administrator to manually configure identifier mappings
  • Provide your EORI number, postbus number, and environment settings
  • Administrator can configure mappings for production, test, or both environments

Environment Options:

  • production - Production customs environment only
  • test - Test/preprod environment only
  • both - Both environments (recommended)

Checking Mappings

To view all identifier mappings:

  • Navigate to Settings → Declarants
  • Review the sync status column to verify mappings are active
  • Contact your system administrator to review detailed mapping configuration if needed

Surety and DVA Guarantee

Per-Declarant Settings

While company-wide surety settings are in Settings → Surety, per-declarant surety and DVA are configured on the Customer page for customers with is_declarant = true.

Declarant Surety Limit

The financial guarantee amount held by this specific declarant.

Configuration (on Customer page):

  1. Navigate to Customers
  2. Select customer with is_declarant = true
  3. Find “Surety & DVA Settings” section
  4. Enter surety limit in EUR

Use Case: If you operate with multiple declarants, each may have different surety limits.

Example:

Declarant A (NL111111111111): €500,000 surety
Declarant B (NL222222222222): €250,000 surety
Declarant C (NL333333333333): €1,000,000 surety

DVA Guarantee

DVA (Deferred VAT Accounting) allows deferring VAT payment on imports.

Requirements:

  • Customs authorization for DVA
  • Financial guarantee amount
  • Monthly reporting to tax authorities

Configuration (on Customer page):

  1. Navigate to Customers
  2. Select customer with is_declarant = true
  3. Find “Surety & DVA Settings” section
  4. Enter DVA guarantee amount in EUR

Example:

Declarant: CustomsFlows B.V.
EORI: NL123456789012
DVA Guarantee: €100,000
DVA Authorization: NL/12345/2025

Auto-Sync with Customs Integration Service

Automatic Synchronization

When you add or update a declarant in Borderbolt, the system automatically syncs with the customs integration service.

What is Synced:

  • Declarant EORI number
  • Postbus identifier
  • Organization association
  • Environment settings (production/test/both)

Sync Triggers:

  • Creating new declarant
  • Updating declarant EORI or postbus
  • Changing declarant status (active/inactive)

Sync Process:

  1. Borderbolt sends request to customs integration service
  2. Customs integration service creates/updates identifier mapping
  3. Customs integration service confirms registration
  4. Borderbolt displays sync status

Verification:

  • Navigate to Settings → Declarants
  • Check “Sync Status” column
  • Green checkmark = successfully synced
  • Red X = sync failed (check error message)

Manual Sync

If automatic sync fails, you can manually trigger synchronization.

Process:

  1. Navigate to Settings → Declarants
  2. Click “Sync” button next to declarant
  3. Review sync status and any error messages
  4. Contact support if sync continues to fail

Common Sync Errors:

  • Invalid API key (Settings → Customs Settings)
  • Customs integration service unavailable
  • Duplicate EORI/postbus mapping
  • Network connectivity issue

Adding a New Declarant

Step-by-Step Process

  1. Navigate to Settings → Declarants
  2. Click “Add Declarant”
  3. Enter Declarant Information:
    • Company name
    • EORI number (must be valid and registered with customs)
    • Postbus number (format: EORI.XX.YY)
    • Environment (production/test/both)
  4. Save Declarant
  5. Verify Sync: Check sync status shows green checkmark
  6. Configure Surety/DVA (if needed):
    • Navigate to Customers
    • Find the customer (automatically created with is_declarant = true)
    • Enter surety limit and DVA guarantee in “Surety & DVA Settings”

Declarant vs. Customer

When you add a declarant in Settings → Declarants:

  • A Customer record is created automatically
  • Customer is marked with is_declarant = true
  • Customer inherits declarant EORI and postbus
  • Customer can be used in declaration Declarant field

Relationship:

Declarant (Settings) → Creates → Customer (with is_declarant=true)
                                           ↓
                              Used in Declaration Header

Testing Customs Connectivity

Verify Integration

Test that your declarant configuration works with the customs integration service.

Process:

  1. Navigate to Settings → Declarants
  2. Select declarant
  3. Click “Test Connection”
  4. Review test results

Successful Test:

  • Connection to customs integration service: ✓
  • EORI/postbus mapping found: ✓
  • Organization correctly identified: ✓

Failed Test:

  • Check EORI and postbus are correct
  • Verify sync status is green
  • Ensure customs API key is set (Settings → Customs)
  • Review customs integration service status

Best Practices

EORI and Postbus Management

Verify Before Use:

  • Confirm EORI is active with customs authorities
  • Test with preprod environment before production
  • Document EORI and postbus for each declarant
  • Keep list of authorizations (AEO, DVA, etc.)

Multiple Declarants:

  • Use separate postbus for each office/department
  • Configure per-declarant surety limits
  • Track which declarant is used for which customers
  • Monitor surety balance per declarant

Customs Integration Configuration

Environment Strategy:

  • Use both for most declarants (simplifies testing)
  • Use production only for declarants never used in test
  • Use test only for test-only declarants

Monitoring:

  • Check sync status regularly
  • Test connectivity monthly
  • Review customs response logs for errors
  • Monitor declarant surety balances

Authorization Management

Track Authorizations:

  • AEO (Authorized Economic Operator) status
  • DVA (Deferred VAT Accounting) authorization
  • Surety guarantee amounts
  • Special procedure authorizations
  • Authorization expiry dates

Documentation:

  • Keep copies of authorization letters
  • Document EORI and postbus registration
  • Maintain list of customs contacts
  • Track guarantee certificate details

Updating Declarants

  1. Navigate to Settings → Declarants
  2. Click declarant name to edit
  3. Update EORI, postbus, or other fields
  4. Save changes
  5. Verify sync status updates to green checkmark
  6. Test connectivity after changes

Caution: Changing EORI or postbus may affect active declarations and customs routing. Test in preprod environment first.

Permissions

To manage declarants, users must have the Settings permission. This is typically assigned to:

  • Admin role
  • Manager role

To use declarants in declarations, users must have the Declarations permission.

Troubleshooting

EORI Validation Failed

Problem: Cannot save declarant due to invalid EORI number.

Solutions:

  • Verify EORI format matches country requirements
  • Check EORI is registered with customs authorities
  • Validate EORI on VIES: https://ec.europa.eu/taxation_customs/vies/ 
  • Ensure EORI is active and not suspended
  • Remove any spaces or special characters

Sync Failed - Duplicate EORI

Problem: Sync fails with “EORI already registered” error.

Solutions:

  • Check if EORI is already used by another organization
  • Verify EORI and postbus are correct for your organization
  • If EORI is legitimately used by multiple organizations, use different postbus
  • Contact Borderbolt support if EORI conflict cannot be resolved

Customs Responses Not Received

Problem: Declarations submitted but no customs responses received.

Solutions:

  • Verify declarant sync status is green
  • Check EORI and postbus are correctly registered
  • Test connectivity in Settings → Declarants
  • Contact your administrator to review customs integration service logs for routing errors
  • Ensure customs API key is set (Settings → Customs)
  • Verify declaration office is NL000396 for preprod testing

Postbus Format Error

Problem: Cannot save declarant due to invalid postbus format.

Solutions:

  • Verify format: {EORI}.{Extension}.{Department}
  • Ensure EORI portion matches declarant EORI exactly
  • Use standard extension 01 unless otherwise specified
  • Use standard department 60 for declarations
  • Remove any spaces or special characters
  • Example: NL123456789012.01.60

Surety Settings Not Available

Problem: Cannot find surety settings for declarant.

Solutions:

  • Surety settings moved to Customer page
  • Navigate to Customers (not Settings → Declarants)
  • Find customer with same EORI as declarant
  • Customer must have is_declarant = true flag
  • Surety & DVA Settings section appears for declarant customers only
Last updated on
Roles & PermissionsAuthentication