Declaration actions

Once a declaration is created, there are a number of actions that can be executed on the declaration.

For example, in case the automatic submission is disabled in the customs flow step configuration, it is possible to trigger the submission of a declaration to customs by executing the Submit action using the following API call:

https://api-<env>.customs4trade.com/v1/declarations/<declarationId>/submit

The most efficient way to retrieve the declarationId, the unique internal ID for a declaration which is needed to invoke any declaration action through the API, is through a webhook event as described in Notifications.

However, it is also possible to search for a declaration based on a number of criteria (e.g. your own reference for the customs shipment externalReference) by using the Search declarations endpoint.

Not all actions are available for every declaration status. For example, Goods Arrived only applies to pre-lodge declarations.

More info can be found with the individual actions

Action	Description
Goods Arrived	Trigger presentation notification upon goods arrival for pre-lodge declarations. Declaration type will move from D to A
Invalidate	Invalidate declaration from an allowed status by providing a reason for the invalidation.
Submit	Submit a declaration to customs (relevant when auto-submit is not configured, or after validation errors have been corrected)
Validate	Explicitly run the CAS validations
Generate SAD	Trigger the single administrative document (SAD) PDF creation
Receipt Report	Submit report of receipt for an excise movement
Complementary Explanation	Submit complementary explanations for a declaration
Change Destination	Trigger a change of destination for an EMCS excise declaration (splits the declaration and submits the change)
Reject or Alert EAD	Reject or alert the electronic administrative document (EAD) for excise movements
Delay for Delivery	Submit a delay for delivery notification for an EMCS excise movement

All actions are invoked with POST /v1/declarations/{declarationId}/{action} and return 202 Accepted on success or 404 Not Found if the declaration does not exist. Actions that do not require a request body (Goods Arrived, Submit, Validate, Generate SAD) can be called with an empty body.

Scope: create:messages

Action request bodies

Some actions require a request body containing additional parameters. Below are the details for each.

Invalidate

Provide a reason for the invalidation:

{
  "reason": "Incorrect commodity code submitted, declaration needs to be corrected and resubmitted"
}

Receipt Report

Submit a report of receipt for an inbound EMCS excise movement. The report includes a global conclusion at the shipment level and optionally item-level details:

{
  "exciseGoodsShipment": {
    "destinationOfficeCode": "GB000060",
    "exciseMovement": {
      "reportOfReceipt": {
        "dateOfArrivalOfExciseProducts": "2026-03-20T10:30:00Z",
        "globalConclusionOfReceipt": "1",
        "complementaryInformation": "All goods received in good condition",
        "complementaryInformationLanguage": "en"
      }
    }
  },
  "governmentAgencyGoodsItems": [
    {
      "casReference": "item-cas-ref-001",
      "commodity": {
        "itemId": "ITEM-001"
      },
      "exciseGoodsItem": {
        "bodyReportOfReceipt": {
          "indicatorOfShortageOrExcess": "S",
          "observedShortageOrExcess": 2.5,
          "exciseProductCode": "W200",
          "refusedQuantity": 0,
          "unsatisfactoryReasons": []
        }
      }
    }
  ]
}

Global conclusion of receipt codes:

1 -- Receipt accepted and satisfactory
2 -- Receipt accepted although unsatisfactory
3 -- Receipt refused
4 -- Receipt partially refused

Indicator of shortage or excess: S (shortage) or E (excess).

Complementary Explanation

Submit complementary explanations for a declaration, typically after a shortage or excess has been reported. A global explanation is required:

{
  "exciseGoodsShipment": {
    "analysis": {
      "globalExplanation": "Discrepancy in declared quantities due to measurement conversion at dispatch",
      "globalExplanationLanguage": "en"
    }
  },
  "governmentAgencyGoodsItems": [
    {
      "casReference": "item-cas-ref-001",
      "exciseGoodsItem": {
        "bodyAnalysis": {
          "explanation": "Quantity difference caused by temperature-related volume change during transport",
          "explanationLanguage": "en",
          "actualQuantity": 998.50
        }
      }
    }
  ]
}

Change Destination

Trigger a change of destination for an EMCS excise movement. This action splits the declaration and submits the change to the relevant customs authority:

{
  "invoice": {
    "date": "2026-03-20",
    "number": "INV-2026-0042"
  },
  "exciseGoodsShipment": {
    "headerEadEsad": {
      "destinationTypeCode": 1,
      "journeyTime": "D02"
    },
    "transportMode": {
      "transportModeCode": 3,
      "complementaryInformation": "Road transport via highway",
      "complementaryInformationLanguage": "en"
    },
    "consigneeTrader": {
      "name": "New Consignee Ltd",
      "address": {
        "street": "456 New Street",
        "city": "Brussels",
        "zipCode": "1000",
        "country": "BE"
      },
      "businessPartnerReferences": [
        {
          "type": "Eori",
          "code": "BE0123456789"
        }
      ]
    },
    "deliveryPlaceTrader": {
      "name": "Warehouse Brussels",
      "address": {
        "street": "789 Warehouse Road",
        "city": "Brussels",
        "zipCode": "1000",
        "country": "BE"
      }
    },
    "transportDetails": [
      {
        "transportUnitCode": 1,
        "identityOfTransportUnits": "ABC-123",
        "commercialSealIdentification": "SEAL-98765"
      }
    ],
    "movementGuarantee": {
      "guarantorTypeCode": 1,
      "guarantorTraders": [
        {
          "name": "Guarantor Company NV",
          "businessPartnerReferences": [
            {
              "type": "Eori",
              "code": "BE9876543210"
            }
          ]
        }
      ]
    }
  }
}

Reject or Alert EAD

Reject or raise an alert on the electronic administrative document (e-AD) for an inbound excise movement:

{
  "destinationOfficeCode": "GB000060",
  "eadEsadRejectedFlag": true,
  "alertOrRejectionOfMovementReasonCode": "2",
  "complementaryInformation": "Received goods do not match the ordered product specification",
  "complementaryInformationLanguage": "en"
}

Reason codes:

0 -- Other
1 -- The e-AD/e-SAD does not concern the consignee/recipient
2 -- The products do not correspond with the order
3 -- The quantities do not correspond with the order

Set eadEsadRejectedFlag to true to reject, or false to only raise an alert.

Delay for Delivery

Submit a delay for delivery notification for an EMCS excise movement when goods cannot be delivered within the expected timeframe:

{
  "explanationCode": "1",
  "messageRole": "1",
  "complementaryInformation": "Transport delayed due to adverse weather conditions on route",
  "complementaryInformationLanguage": "en"
}

Explanation codes:

0 -- Other
1 -- Commercial problems
2 -- Strike or other labour dispute
3 -- Severe weather conditions
4 -- Accident or incident on route
5 -- Inspection by customs or other authority

For HTTP status codes and error response formats, see Error handling.

← Previous Page Next Page →