Send CDS import declaration

Builds an H1 import declaration from reviewed invoice data and the client’s tables, checks it, sends it to HMRC and waits for acceptance or release.

@lainstack/hmrc/send-cds-import-declaration · Customs · Available on Lainstack Cloud

How to use it

Send CDS import declaration builds an H1 import declaration, checks it, sends it to HMRC Customs Declarations and waits for HMRC’s decision.

It builds from reviewed invoice and packing-list data, the client’s row in the client table (matched on client_key) and that client’s rows in the product table. The declaration is checked against CDS rules and HMRC’s XSD schemas before it is sent.

• Check errors stop the send and open a document review. A reviewer fixes the fields and the block sends with the changes. Errors no field can fix fail the step. A reviewer who rejects routes Rejected.
• HMRC refusing the submission (HTTP 4xx) or rejecting the declaration later also opens a review. A resend takes a new LRN.
• After sending, the block checks HMRC’s notifications on a durable timer: often at first, then at most every 30 minutes. Wait until Accepted continues once HMRC issues the MRN. Released waits for release and routes Held by customs when customs holds the goods for a control or documents.
• No decision within timeoutMinutes (default 15, at most 14 days) routes Timed out. @lainstack/hmrc/get-cds-declaration-status can check later.
• On send, HMRC rate limits (429), timeouts (408) and server errors fail the step.
• A test run sends only to a sandbox Connection. With a production Connection it builds and checks the declaration, returns not_sent_test_run and stops.
• The block is not replayable, and sends at most once per attempt.
• The declaration XML and its document record are saved as run files.
• The client table must have exactly one row for the client. A client with more product rows than one lookup returns fails the step.

Settings

Setting	Key	Type	Details
HMRC connection (required)	credentialId	Connection	The trader’s HMRC Customs Declarations connection. A test run sends only to a sandbox connection. At most 160 characters.
Invoice data (required)	invoice	Value	The reviewed invoice and packing list, usually Reviewed data from the review step.
Client (required)	client	Text	Who the declaration is for, by their client key.
Declaration type	declarationTypeCode	One of Goods have arrived (IMA), Before arrival, pre-lodged (IMD)	Default IMA.
Wait until	waitUntil	One of Accepted (MRN issued), Released (goods cleared)	Accepted continues as soon as HMRC accepts the declaration and issues the MRN. Released keeps waiting until the goods are released, and stops early if customs holds them. Default accepted.
Entry summary MRN	entrySummaryMrn	Text	Optional. The carrier’s ENS MRN. Without it only the DUCR is declared.
Client table (required)	clientsTableId	Text	One row per client key: EORIs, payment and authorisations.
Product table (required)	productLibraryTableId	Text	Each client’s products with their commodity codes.
Goods location	goodsLocationId	Text	HMRC goods location code. Defaults to WLALONBTW.
Declaration fields	document	Value	Every field of the declaration, filled from the inputs above. Change a field to override how it’s filled. At most 100 items.
Give up after (minutes)	timeoutMinutes	Number	Take the Timed out path when HMRC has not decided by then. Defaults to 15; up to 20160 (14 days, as long as HMRC keeps notifications). From 1 to 20,160. Default 15.

Outputs

Output	Path	Type
Outcome	outcome	Choice
Summary	summary	Text
LRN	lrn	Text
DUCR	ducr	Text
MRN	mrn	Text
Environment	environment	Text
Conversation ID	conversationId	Text
Submitted At	submittedAt	Text
Accepted At	acceptedAt	Text
Checked At	checkedAt	Text
Next Check At	nextCheckAt	Text
HMRC Problem	hmrcProblem	Text
Issues	issues	List
Refusal > Code	refusal.code	Text
Refusal > Message	refusal.message	Text
Refusal > Errors	refusal.errors	List
Refusal > Explanation	refusal.explanation	Text
Errors	errors	List
Tax Lines	taxLines	List
Tax Total > Amount	taxTotal.amount	Text
Tax Total > Currency	taxTotal.currency	Text
Notifications	notifications	List
Unreadable Notifications	unreadableNotifications	List
Document	document	Value
Document Record	documentRecord	Value

Exits

Exit	Port	Notes
Accepted	out
Rejected	rejected	Failure exit.
Held by customs	held
Timed out	timedOut