search

truck-fastManage your transactions

Transaction Management provides a systematic way to link EUDR compliance data with the product level information required to evidence compliance with the Regulation in the form of a Due Diligence Statement (DDS) in the EU Information System (EU TRACES). It enables key information from your ERP, such as Purchase Orders and Sales Orders, to be captured in these DDS as well providing a way of managing linkages with existing DDS and connections between different product level documentation.

hashtag
⚠️ Prerequisites

  • Transaction Management is a premium feature in TradeAware. To use this functionality, your account must be enabled for transactions. If you do not have this enabled, contact your Customer Success Manager.

  • Your business will also need to have an identifier added to the account details to submit a transaction to TRACES. This must be an EORI for import and export transactions but can be VAT for domestic (internal EU transactions). You can update this in your Manage Account page.

  • Your business will need to be connected to plots of the relevant commodity to submit a Transaction to TRACES. This can be done either through connected supplier businesses or through plots managed under your own business account (self-managed model).

  • You will be able to see the data with your associated account on TRACES. By default the system is connected to the ACCEPTANCE testing systemRemember to stay on Acceptance while testing and switch to PRODUCTION only when ready to submit legally valid due diligence statements.

hashtag
Overview

Transaction Management provides a way to link transaction data, such as Purchase Orders (PO) and Sales Orders (SO) to compliance data in TradeAware to create and manage Due Diligence Statements.

Customers can:

  • Manage Due Diligence Statements: Link orders from your ERP system to compliance data in TradeAware.

  • Enhance Traceability: Connect DDS compliance data to orders, streamlining regulatory reporting and audit preparation.

  • Automate Compliance Workflows: Minimize manual data entry by automating key compliance and transaction workflows.

hashtag
Activity Types and Required Fields

⚠️ Note: The following table is intended as a quick reference for understanding the main differences between activity types. For the complete and up-to-date list of required fields, please refer to the API Referencearrow-up-right.

Each transaction contains one or more components, where each component represents a product or commodity line (HS code + quantity + unit + description). Depending on your business process, a component can be built using:

  • Supplier-based traceability (one or more suppliers, with optional plot selection), and/or

  • Upstream DDS reference traceability (one or more DDS references), and/or

  • Self-managed plot traceability (plots managed under your own business account, without supplier IDs).

Typical patterns by activity type

ActivityType

When to Use

Typical component inputs

IMPORT

First placement of goods on the EU market from a third country

Supplier-based traceability (supplierBusinessId or supplierBusinessIds) + optional plotIds

TRADE

Reselling goods already on the EU market, no change

Upstream DDS references (ddsReferences) are typical

EXPORT

Shipping goods from the EU to a non-EU country

Upstream DDS references (ddsReferences) are typical; supplier plots may be included for hybrid workflows where neededw

DOMESTIC

Processing goods within the EU (HS code change) or placing EU-produced goods on the market

Upstream DDS references (ddsReferences) are typical; supplier plots may be included for hybrid workflows where needed

Optional product information (components) plotIds, namePairs, dateOfProduction, endDateOfProduction, customData, isGeoLocationConfidential

📘 Tip: If you need to represent a single final product that has multiple upstream sources, see the “Mixed-origin / Hybrid / Self-managed” patterns below.

hashtag
List of Use Cases

  1. Transaction Management for Operators (Activity: Import, Export, Domestic)

  2. Transaction Management for Traders (Activity: Trade)

  3. Managing Composite Products

  4. Submitting Transactions to TRACES

  5. Linking Transactional Data to Compliance Workflows (e.g. Batches, Shipments)

hashtag
Key Concepts:

  • Component Object: Represents a commodity or product, including essential details like HS code, quantity, unit, and description. Components are mapped to the requirements for validly creating a Due Diligence Statement in the EU Information System (EU TRACES).

    A component can include:

    • Supplier traceability using supplierBusinessId (single supplier) or supplierBusinessIds (multiple suppliers for mixed-origin).

    • Plot selection using plotIds (optional). Omit this field to attach all plots of the supplier business.

    • Upstream DDS traceability using ddsReferences (one or more DDS reference + verification pairs).

    • Hybrid traceability by combining ddsReferences with supplier/plot information in the same component when your final product includes mixed inputs.

    • Self-managed plots by omitting supplierBusinessId(s) and providing plotIds for plots managed under your business account.

  • CustomData: Metadata related to the transaction. This flexible structure allows users to store relevant information, provided it follows these rules:w

    • Maximum of 50 keys

    • Maximum key length of 255 characters

    • Maximum string value length of 255 characters

    • Values must be either strings, numbers, or booleans

    • Keys cannot contain the substrings proto, constructor, or prototype

  • supplierBusinessId / supplierBusinessIds

    • supplierBusinessId is a unique identifier representing a single supplier business in TradeAware.

    • supplierBusinessIds is a list of supplier business IDs used when a single component includes inputs from multiple suppliers (mixed-origin).

  • ddsReferences: Links a transaction component to one or more Due Diligence Statements (DDS), ensuring compliance and traceability. Each DDS in the array includes:

    • id: Unique identifier for the DDS.

    • verificationNumber: Code validating the DDS’s authenticity.

    • Validation Rules:

      • When a DDS reference is included in a transaction, the system will verify both the DDS ID and the verificationNumber before submission.

      • If the TRACES API is unavailable or returns an unknown error, new transactions referencing DDS numbers will be rejected with a recommendation to message.

    • ⚠️ Regulatory note (Re-Import / Hybrid): The EU is discussing simplifications to EUDR processes, including how upstream DDS references may be reused. If these changes are implemented, some re-import/hybrid workflows may become less relevant. TradeAware will align with official guidance and this guide will be updated accordingly.

  • Legal Entity (legalEntityId) TRACES requires the exact legal entity responsible for a transaction so the correct name, address and EORI/VAT appear on the DDS. Use legalEntityId to select that specific legal entity for a transaction.

    businessId vs legalEntityId

    • businessId → your TradeAware account.

    • legalEntityId → a registered legal entity (name, address, EORI/VAT) that can submit to TRACES. A single account can have multiple legal entities (e.g., DE GmbH, IT S.p.A.). Each transaction must specify one legal entity (the DDS primary actor) to ensure the correct EORI/VAT and address are used.

hashtag
Transaction Statuses

Transactions progress through various statuses during their lifecycle, from creation to final processing in the EU Information System (EU TRACES) as a Due Diligence Statement (DDS). Below is an overview of each status:

  • DRAFT: The transaction is in draft mode, still being prepared and not yet submitted for processing. It remains editable by the user.

  • TO_SUBMIT: The transaction is pending submission to the EU TRACES. At this stage, all necessary data should be finalized.

  • PROCESSING / SUBMITTED: The transaction has been submitted to EU TRACES and is waiting for validation. This does not guarantee that a DDS reference number or verification number has been assigned. This process might take up to a few hours or, in some cases, longer, depending on EU TRACES' response times.

  • AVAILABLE: The transaction has been accepted by EU TRACES and now has a reference and verification number.

  • ERROR / REJECTED: The transaction was rejected by TRACES or could not be processed successfully.

  • WITHDRAWN: The transaction was withdrawn from EU TRACES and is no longer active. No DDS reference or verification number will be assigned to a withdrawn transaction.

DDS reference/verification numbers are returned once the transaction is AVAILABLE.

hashtag
Transaction Management accommodate for both Operators and Traders needs

Operators and traders play distinct roles in the compliance chain under the EU Information System (EU TRACES).

  • Operators are typically the first person to make a product available on the EU market. Their transactions usually focus on direct traceability to immediate suppliers (supplierBusinessId / supplierBusinessIds) and plot-level geolocation.

  • Traders are those who subsequently move products already available in the EU market. Their transactions typically emphasize linking products to existing DDS references (ddsReferences).

💡 Note: While these are the most common patterns, TradeAware also supports advanced workflows where a component needs both upstream DDS references and supplier plot traceability (hybrid / re-import), and workflows where plots are managed centrally under one account (self-managed model).

hashtag
DDS Reference Validation in Transactions API

When referencing a previously submitted Due Diligence Statement (DDS), the API performs validation checks to ensure the provided DDS ID and verificationNumber are correct.

Error Handling: If the provided DDS reference is invalid or does not match, the API will return:

If the TRACES system is unavailable, new transactions using DDS references will be rejected with an instruction to retry later.

hashtag
Use Case 1: Transaction Management for Operators

Operators need a reliable way to submit transactions that either place goods on the EU market for the first time (Import), export goods out of the EU (Export), or document processing of EU goods (Domestic). They must provide the correct inputs—supplier information, upstream DDS references, or a combination—depending on the workflow.

The API enables operators to create transactions tied to the correct compliance data for their activity type:

  • Import: Typically requires supplier info + geolocation (plots). Mixed-origin is supported using multiple supplier IDs.

  • Export: Typically requires upstream DDS references; hybrid workflows are supported where needed.

  • Domestic: Typically requires upstream DDS references; hybrid workflows are supported where needed.

Create a New Transaction as an Operator:

  • Description: This is for the entity that is the first to import goods into the EU. Operators are responsible for ensuring that products meet EUDR compliance at the initial point of entry into the EU market.

  • Key Requirements:

    • supplierBusinessId (or supplierBusinessIds) s used to link the transaction component to one or more suppliers.

    • plotIds can be used to select specific plots; omit plotIds to attach all supplier plots.

    • ddsReferences may be used only when your workflow requires hybrid traceability.

Steps to Implement:

  1. Retrieve a list of suppliers:

    • Endpoint: GET /business-connections/suppliers to fetch supplier details.

    • Important: When linking a transaction to a supplier, you can use any of the following identifiers: EORI, VAT number, email, or the customData field if none of the other identifiers are sufficient. We recommend prioritizing EORI or VAT for better traceability and compliance alignment.

    • Example Request:

    • This returns a list of all the business connections that have you as sourceBusiness with the data of your suppliers in targetBusiness (for each item in the list). Check what sourceBusiness and targetBusiness mean in our API reference for business connectionsarrow-up-right

      • Your {businessId} can be found in the sourceBusiness field under id.

      • Your supplier's unique identifier (id) is located in the targetBusiness field.

  2. Create a transaction with supplier-linked components:

    • Endpoint: POST /transactions

    • Example Request:

    📘 Note: legalEntityId is optional when creating a transaction.

  3. Create a transaction for mixed-origin inputs (multiple suppliers on one component):

    Use supplierBusinessIds when one component includes inputs from multiple suppliers.

    Example Request:

  4. Assign Specific Plots to Components via API

    When creating or updating a component, you can optionally associate it with specific geolocation plots using the plotIds field.

    • If you do not wish to assign any plots, omit the plotIds field entirely.

    • Passing an empty array (plotIds: []) is not supported and will result in a validation error.

    1. Retrieve available plots Endpoint: GET /businesses/{businessId}/plots Returns a list of plots (each with a unique id) you can later pass in the plotIds array.

      📘 Tip: Use filters such as filter.riskAssessmentStatus=$eq:EUDR_Non_Compliant to identify and review non-compliant plots before selection. TradeAware will not automatically exclude them—you decide what to include.

    2. Add components with specific plots Endpoint: POST /transactions/{transaction_id}/components

      Example Request:

      📘 Note: Plot selection is always user-driven. TradeAware does not automatically filter or restrict plot inclusion. This flexibility allows you to align selected plots with shipment documentation, harvest batches, or internal sourcing policies.

    3. Important Validation Rule: Sending plotIds: [] (an empty array) is not supported and will return an error:

  5. List all transactions:

    • Endpoint: GET /transactions

    • Example Request:

  6. Update an existing order:

    • Endpoint: PATCH /transactions/{transaction_id}

    • Example Request:

hashtag
Use Case 2: Transaction Management for Traders

Business Case:

Traders must comply with regulatory requirements by ensuring traceability of DDS references for each transaction. Forwarding upstream DDS references can be complex when dealing with multiple components.

Solution:

Traders need to submit transactions to forward or reuse existing DDS references when reselling goods within the EU without transformation. In advanced workflows, a component may also include supplier plot traceability (hybrid) where required.

Create a New Transaction as a Trader:

  • Description: This is for entities that make relevant products available on the market. Traders are involved in the subsequent movement of goods and must link products to upstream DDS references.

  • Key Requirements:

    • supplierBusinessId(s) are typically not required when referencing upstream DDS, but may be included for hybrid workflows where needed.

    • ddsReferences should be provided for traceability.

Steps to Implement:

  1. Create a transaction with DDS references:

  • Endpoint: POST /transactions

  • Example Request:

Note: The system will validate the provided DDS referenceNumber and verificationNumber before accepting the transaction.

  1. Retrieve Information about an existing DDS from the EU Information System

Optional: This action allows you to retrieve and check the data in a reference DDS before making use of it.

  • Endpoint: GET /dds/fetch-dds-data

  • Example Request:

hashtag
Use Case 3: Managing Composite Products

Business Case:

Managing products composed of multiple components while ensuring compliance requires a structured approach to track each material’s origin and DDS references.

Solution:

Use the Transactions API to associate multiple components with a transaction. Each component represents a separate HS code line.

💡 Note: Composite products (multiple component rows) are different from mixed-origin components (one component row with multiple suppliers). Use supplierBusinessIds for mixed-origin.

Steps to Implement:

  1. Create a composite product with multiple components:

    • Endpoint: POST /transactions

    • Example Request:

  2. Add a component to a transaction:

    • Endpoint: POST /transactions/{id}/components

    • Example Request:

  3. Update a component:

    • Endpoint: PATCH /components/{id}

    • Example Request:

hashtag
Use Case 4: Submitting Transactions to TRACES

Business Case:

Submitting a transaction to the EU Information System (TRACES) is required to obtain a valid Due Diligence Statement (DDS). This step must include correct company (Legal Entity) details and passes through asynchronous validation in TRACES.

hashtag
Prerequisites

  • A Legal Entity is associated with the transaction at submission time. Link it via legalEntityId (on create or with PATCH /transactions/{id}) or provide a full legalEntity object in the submit request. If you set legalEntityId, the API resolves the full Legal Entity for you—no need to resend it on submit.

    • If legalEntityId is not provided, TradeAware will auto-select the oldest Legal Entity on your account at submit time.

  • Required identifiers live on the Legal Entity used for submission: EORI for Import/Export; VAT acceptable for Domestic/Trade.

  • Supplier plots for the component commodity exist. If you send plotIds, they must reference valid plots for that supplier (or permitted upstream).

Solution:

Use the submit endpoint to update a transaction’s status to TO_SUBMIT, signaling its readiness for TRACES submission.

Steps to Implement:

  1. Find (or create) your Legal Entity ID (if you prefer the legalEntityId path)

    List existing Legal Entities

    Create a Legal Entity (if none exists yet)

    📘 Note: Copy the id from the response and use it as legalEntityId on create or via PATCH /transactions/{id} before submitting.

  2. Submit a transaction:

    • Endpoint: PUT /transactions/{id}/submit

    • Example Request:

    • Example Response:

  3. Receiving a DDS Reference and Verification Number

After a transaction is successfully submitted to TRACES, the system continuously checks for the assigned DDS reference and verification number. Since TRACES assigns these asynchronously, TradeAware automatically retrieves and updates them.

  • Endpoint: GET /transactions/{id}

  • Example Request:

DDS reference and verification numbers are returned once the transaction is AVAILABLE.

hashtag
Use Case 5: Linking Transactional Data to Compliance Workflows (e.g., Batches, Shipments)

Business Case:

Businesses need to link transactional data, such as batches, shipments, Purchase Orders etc. to compliance workflows to create a robust audit trail and maintain regulatory compliance. Without this linkage, inefficiencies and compliance risks can arise.

Solution:

Leverage the customData field in the Transactions API to associate SOs with POs for seamless traceability.

Create a Batch linked to a purchase order:

  • Endpoint: POST /transactions

  • Example Request:

PreviousAssess risk in your supply chainNextAPI reference

Last updated