User Guide: Transaction Management

Transactions 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.

⚠️ Prerequisites

Transactions are 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.

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.

List of Use Cases

Managing Compliance with the Transaction API (for Operators)
Forwarding Upstream DDS References for Traders
Managing Composite Products
Submitting Transactions to TRACES
Linking Transactional Data to Compliance Workflows (e.g. Batches, Shipments)

Key Concepts:

Component Object: Represents a commodity or product, including essential details like type, quantity, and origin, traceable to the supplier or production location. Components are mapped to the requirements for validly creating a Due Diligence Statement in the EU Information System (EU TRACES).
CustomData: Metadata related to the transaction. This flexible structure allows users to store relevant information, provided it follows these rules:
- Maximum of 10 keys.
- Data must be of type string, number, or boolean. Arrays are not supported due to validation and storage constraints.
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.
supplierBusinessId is a unique identifier representing the supplier's business in the TradeAware system. This identifier is used to establish a direct link between a transaction and its immediate supplier, ensuring their required data can be captured against a Due Dilligence Statement.

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. Below is an overview of each status:

DRAFT: The transaction is in draft mode, still being prepared and not yet submitted to the for processing.
TO_SUBMIT: The transaction is marked as ready to be submitted to the EU Information System.
PROCESSING: The transaction is currently being processed by the EU Information System.
SUBMITTED: The transaction has been submitted for validation in the EU Information System but does not yet have a DDS reference or verification number.
COMPLETED: The transaction was successfully validated and accepted by the EU Information
WITHDRAWN: The transaction was withdrawn from the EU Information System and is no longer active.

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 the first person to make a product available on the EU market. Their transactions focus on direct traceability to immediate suppliers, requiring a supplierBusinessId but excluding ddsReferences.

Traders are those to subsequently move products already available in the EU market around it. Their transactions emphasize linking products to upstream DDS references, requiring ddsReferences but not supplierBusinessId. It is important to avoid including both supplierBusinessId and ddsReferences in a single request to prevent errors and maintain traceability integrity.

Why the Distinction? The EU TRACES design separates these responsibilities to reduce duplication of effort. An entity must choose between associating a transaction with supplierBusinessId or ddsReferences, not both. This ensures that existing available information in the EU TRACES system does have to be re-entered.
Common Challenges and Clarifications:
- If both supplierBusinessId and ddsReferences are included in a request, the system will throw an error. This is because EU TRACES does not require both properties together for a single component.
- Users should ensure they store supplier and DDS information separately in their systems if needed for later traceability.

Use Case 1: Managing Compliance with the Transaction API (for Operators)

Business Case:

Operators need a reliable way to link different type of orders from their ERP systems to compliance workflows. Ensuring accurate traceability at the point of importation is critical for meeting EUDR requirements.

Solution:

The Transactions API allows operators to link order data directly to their immediate suppliers, enabling efficient management of Due Diligence Statements and compliance workflows.

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 is required to link the transaction to the immediate supplier.
- ddsReferences should not exist in the request body.
- The focus is on maintaining traceability to the immediate supplier rather than upstream DDS references.

Steps to Implement:

Retrieve a list of suppliers:
- Endpoint: GET /business-connections/suppliersendpoint 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:
  curl -X GET https://api.tradeaware.live-eo.com/business-connections/suppliers \ -H "Authorization: Bearer <token>"
- 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 connections
  - Your {businessId} can be found in the sourceBusiness field under id.
  - Your supplier's unique identifier (id) is located in the targetBusiness field.

Create a transaction with supplier-linked components:

Endpoint: POST /businesses/{businessId}/transactions

Example Request:

curl -X POST https://api.tradeaware.live-eo.com/businesses/{businessId}/transactions \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "activityType": "IMPORT",  // or EXPORT, DOMESTIC, TRADE based on your transaction
  "countryOfActivity": "DE",  // Replace "DE" with a valid ISO31661 Alpha2 code (e.g., AT, BE, FR, etc.)
  "components": [
  {
    "hsn": "4401",  // Replace with a valid code from the /components/hs-codes endpoint
    "quantity": 100,
    "unit": "KGM",
    "description": "Fuel wood",
    "supplierBusinessId": "589df451-a064-48e6-a715-1315a3f6180a",
    "namePairs": [
      {
        "commonName": "fuel wood",
        "scientificName": "Firewood"
      }
    ],
    "dateOfProduction": "2023-01-01T00:00:00.000Z"
  }
]
}'

List all transactions:

Endpoint: GET /transactions

Example Request:

curl -X GET https://api.tradeaware.live-eo.com/transactions?includes=components \
-H "Authorization: Bearer <token>"

Update an existing order:

Endpoint: PATCH /transactions/{transaction_id}
Example Request:

curl -X PATCH https://api.tradeaware.live-eo.com/transactions/{transaction_id} \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "customData": {
    "updatedField": "Updated Value"
  }
}'

Use Case 2: Forwarding Upstream DDS References 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:

Use the Transactions API to include DDS references in transaction components, ensuring compliance and transparency.

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 their immediate suppliers.
Key Requirements:
- supplierBusinessId should not exist in the request body.
- ddsReferences should be provided for traceability.
- The focus is on associating products with upstream DDS references.

Steps to Implement:

Retrieve a list of suppliers:
- Endpoint: GET /business-connections/suppliers
- Example Request:
  curl -X GET https://api.tradeaware.live-eo.com/business-connections/suppliers \ -H "Authorization: Bearer <token>"
- 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).
  - Your {businessId} can be found in the sourceBusiness field under id.
Create a transaction with DDS references:

Endpoint: POST /businesses/{businessId}/transactions
Example Request:

curl -X POST https://api.tradeaware.live-eo.com/businesses/{businessId}/transactions \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "activityType": "IMPORT", 
  "countryOfActivity": "DE", 
  "components": [
    {
      "ddsReferences": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "verificationNumber": "ABC-12345-XYZ"
        }
      ],
      "dateOfProduction": "2023-01-01T00:00:00.000Z"
    }
  ]
}'

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 components with composite products, maintaining traceability for compliance.

Steps to Implement:

Create a composite product with multiple components:

Endpoint: POST /businesses/{businessId}/transactions

Example Request:

curl -X POST https://api.tradeaware.live-eo.com/businesses/{businessId}/transactions \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "activityType": "IMPORT", 
  "countryOfActivity": "DE", 
  "components": [
    {
      "hsn": "4015",
      "quantity": 100,
      "unit": "KGM",
      "description": "Articles of apparel and clothing accessories (including gloves, mittens and mitts), for all purposes, of vulcanised rubber other than hard rubber",
      "supplierBusinessId": "589df451-a064-48e6-a715-1315a3f6180a",  // Replace with your supplier's UUID
      "ddsReferences": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "verificationNumber": "ABC-12345-XYZ"
        }
      ]
    },
    {
      "hsn": "4016",
      "quantity": 200,
      "unit": "KGM",
      "description": "Other articles of vulcanised rubber other than hard rubber",
      "supplierBusinessId": "589df451-a064-48e6-a715-1315a3f6180a",  // Replace with your supplier's UUID
      "ddsReferences": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174001",
          "verificationNumber": "XYZ-67890-ABC"
        }
      ]
    }
  ]
}'

Add a component to a transaction:

Endpoint: POST /transactions/{id}/components

Example Request:

curl -X POST https://api.tradeaware.live-eo.com/transactions/{id}/components \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "hsn": "4015",
  "quantity": 200.5,
  "unit": "KGM",
  "description": "Articles of apparel and clothing accessories (including gloves, mittens and mitts), for all purposes, of vulcanised rubber other than hard rubber",
  "namePairs": [
    {
      "commonName": "rubber gloves",
      "scientificName": "Natural vulcanised rubber"
    }
  ],
  "dateOfProduction": "2023-01-01T00:00:00.000Z",
  "endDateOfProduction": "2023-12-31T00:00:00.000Z",
  "supplierBusinessId": "589df451-a064-48e6-a715-1315a3f6180a"
}'

Update a component to modify DDS references:

Endpoint: PATCH /components/{id}

Example Request:

curl -X PATCH https://api.tradeaware.live-eo.com/components/{id} \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
    "quantity": 125.45,
    "unit": "KGM"
}'

Use Case 4: Submitting Transactions to TRACES

Business Case:

Businesses need to ensure transactions are ready for submission to the EU Information System (TRACES). This step is critical for regulatory compliance but requires careful validation and preparation.

Solution:

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

Steps to Implement:

Submit a transaction:

Endpoint: PUT /transactions/{id}/submit

Example Request:

curl -X PUT https://api.tradeaware.live-eo.com/transactions/{id}/submit \
-H "Authorization: Bearer <token>"

Example Response:

{
  "id": "fb6c9222-3204-4612-8ed7-8db516c6c715",
  "status": "TO_SUBMIT",
  "activityType": "EXPORT",
  "countryOfActivity": "IT",
  "customId": "DEC-24-238620",
  "components": [
    {
      "commodity": "soya",
      "ddsReference": {
        "id": "24DKYIGLPU3439",
        "verificationNumber": "4NAB3QYM"
      }
    }
  ]
// Note: Additional parameters may be returned in the response but are omitted here for brevity.
}

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 /businesses/{businessId}/transactions

Example Request:

curl -X POST https://api.tradeaware.live-eo.com/businesses/{businessId}/transactions \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "activityType": "SALE",
  "countryOfActivity": "US",
  "components": [],
  "customData": {
    "transactionType": "Batch",
    "linkedOrders": "PO001",
    "salesRegion": "North America"
  }
}'

PreviousUser Guide: Commercial network management NextAPI reference

Last updated 8 days ago