Declaration items represent individual goods items (Government Agency Goods Items) within a declaration. These endpoints allow you to manage items on a declaration directly, without re-ingesting the entire customs shipment.

When to use these endpoints

Use declaration item endpoints when you need to:

• Add a new goods item to an existing declaration
• Update specific fields on an existing goods item
• Remove a goods item from a declaration
• Retrieve the details of a specific goods item

Preconditions

Item management is only possible when the declaration has not yet been sent to customs or has been rejected by customs. Attempting to modify items on a declaration in other statuses will result in an error.

Endpoints

Method	Endpoint	Scope	Response	Description
GET	/v1/declarations/{declarationId}/items/{id}	read:declarations	200 or 404	Get a specific goods item
POST	/v1/declarations/{declarationId}/items	create:messages	202 Accepted	Create a new goods item
PATCH	/v1/declarations/{declarationId}/items/{id}	create:messages	202 Accepted	Update an existing goods item
DELETE	/v1/declarations/{declarationId}/items/{id}	create:messages	202 Accepted	Delete a goods item

Retrieving an individual item

Use the GET endpoint to retrieve a specific goods item by its ID. This is useful when you need to:

• Inspect the current state of a single item after an update
• Verify that a PATCH operation was applied correctly
• Retrieve item details without fetching the entire declaration

The {id} path parameter is the governmentAgencyGoodsItemId, which can be found in the declaration GET response.

Selective update model

Item updates follow the same selective update model as declaration header updates (see Customs flows):

• Only fields explicitly provided in the request body will be updated
• Fields not included in the request remain unchanged
• Collections provided without casReference will fully replace the existing collection
• Elements identified by casReference will be partially updated -- only provided fields change

Processing

Creating, updating, or deleting items triggers the same deductions and validations as other declaration modifications. The response is 202 Accepted, indicating that the operation has been accepted for asynchronous processing.

Results are communicated through Notifications. If the operation fails validation, the declaration will move to the Invalid status and errors can be retrieved using the Get declaration endpoint with ?include=errors.

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