> For the complete documentation index, see [llms.txt](https://docs.live-eo.com/tradeaware/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/api-integration-use-cases-for-eudr-due-diligence.md).

# API integration use cases for EUDR due diligence

This page is for developers who create Due Diligence Statements (DDS) through the TradeAware API. Each answer covers one thing your integration may need to do: when you need it, why it matters under the EUDR, which calls to make, and what to watch out for.

The transaction API is flexible by design. It files the plots a component points to and doesn't leave plots out because of their assessment status, deforestation risk, location or link date. If your company's policy is that only reviewed plots go into a DDS, your integration applies that policy before it creates and submits the transaction. Every check on this page is optional: pick the ones your due-diligence policy requires, or follow the recommended strict setups.

## Quick start

### Create a transaction without a product catalogue

For an ERP that knows the supplier and picks the plots per purchase. The minimal safe sequence:

{% stepper %}
{% step %}

## Get the supplier's business ID

Get the supplier's business id once with `GET /business-connections/suppliers` and store it.
{% endstep %}

{% step %}

## List the supplier's plots

List its plots with `GET /businesses/{supplierId}/plots?includes=suppliers,riskLevel,riskAssessmentStatus`, 500 per page.
{% endstep %}

{% step %}

## Keep plots that pass your checks

Keep only the plots that pass your checks (C1 to C7): `riskAssessmentStatus EUDR_COMPLIANT, riskLevel` not null, the component’s `commodity`, `countryCode` not XX, `species` for timber.
{% endstep %}

{% step %}

## Create the draft transaction

Create the transaction as DRAFT with `POST /transactions` and always send those plots as `plotIds`. Without `plotIds`, TradeAware files all of the supplier's plots of that commodity, whatever their status. TradeAware takes the production period and, for timber, the species from those plots. Send `dateOfProduction`, `endDateOfProduction` or `namePairs` only to set your own values.
{% endstep %}

{% step %}

## Recheck, submit, and track

Check the statuses again, submit with `PUT /transactions/{id}/submit`, and track the transaction until it is `AVAILABLE` or `ERROR`.
{% endstep %}
{% endstepper %}

### Create a transaction with a product catalogue

For buyers whose suppliers link plots to products. The minimal safe sequence:

{% stepper %}
{% step %}

## Read linked plots

Read the linked plots with `GET /products/{productId}/plots?includes=riskAssessmentStatus,riskLevel`.
{% endstep %}

{% step %}

## Validate suppliers and linked plots

Check that every supplier on the component has linked plots and that its valid-until date hasn't passed (C8, C9), then run C2 to C7 on the linked plots.
{% endstep %}

{% step %}

## Create the transaction

If everything passes, send `productIds` with the suppliers. If some plots fail, send only the passing plots as `plotIds`, without `productIds`.
{% endstep %}

{% step %}

## Preserve the product and suppliers

Don't delete the product or remove a supplier from it until the transaction is processed.
{% endstep %}

{% step %}

## Recheck, submit, and track

Read the links again right before `PUT /transactions/{id}/submit`, then track the transaction until it is `AVAILABLE` or `ERROR`.
{% endstep %}
{% endstepper %}

## Before you start

* **Access.** Your account needs API access (Enterprise) and Transaction Management.
* **Authentication.** All examples use the base URL `https://api.tradeaware.live-eo.com` and a bearer token from `POST /auth/machine-to-machine-clients/token` (grant type `client_credentials`). Tokens are valid for 24 hours.
* **Test on ACCEPTANCE.** Accounts are connected to the TRACES ACCEPTANCE environment by default, so you can run full submissions without filing anything legally binding. Contact your Customer Success Manager when you're ready to move to PRODUCTION.
* **Legal entity.** Every transaction is filed for one of your legal entities. Get its id with `GET /legal-entities`. It needs an EORI for IMPORT and EXPORT; a VAT number is enough for DOMESTIC.
* **Pagination.** Plot lists return up to 500 plots per page (`limit=500`). Request the next page until one returns fewer than 500.
* **Timeouts.** Set a client timeout of at least 60 seconds for `GET /business-connections/suppliers` (see the first question below).

## Know your suppliers and their plots

### How do I get my suppliers' ids and match them to my ERP vendors?

**When:** once when you set up the integration, and again when you onboard a new supplier.

**Why:** every transaction component names the supplier the goods came from, and the EUDR asks you to record who supplied you (Art. 9(1)(e)).

**Steps**

{% stepper %}
{% step %}

## List your suppliers

The supplier's business id is `targetBusiness.id`; the connection's own id is `id`.
{% endstep %}

{% step %}

## Match suppliers to ERP vendors

Match each supplier to your ERP vendor on EORI or VAT number. If neither is enough, store your vendor number on the connection with `PATCH /business-connections/{id}`.
{% endstep %}
{% endstepper %}

```bash
curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/business-connections/suppliers' \
  --header 'Authorization: Bearer YOUR_TOKEN'

curl --request PATCH \
  --url 'https://api.tradeaware.live-eo.com/business-connections/{connectionId}' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "customData": { "erpVendorId": "100234" } }'
```

**Watch out**

* The supplier list also computes each supplier's risk score and can take more than 45 seconds when it isn't cached. Call it once and store the ids rather than calling it for every transaction.
* The PATCH replaces the whole `customData` object, so send every key you want to keep.

### How do I list all plots behind a supplier, including its own suppliers' plots?

**When:** before you create a transaction, to know which plots you can declare for that supplier.

**Why:** the DDS must contain the geolocation of all plots of land where the commodities were produced (Art. 9(1)(d)). Many of those plots are owned by your supplier's own suppliers.

**Steps**

```bash
curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/businesses/{supplierId}/plots?includes=suppliers&limit=500&page=1' \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

Each plot carries the fields most checks need: `id`, `commodities`, `countryCode`, `species`, `productionDateStart` and `productionDateEnd`. You can narrow the list with `filter.commodities=$contains:coffee` (use your commodity) or `filter.countryCode=$eq:BR`.

**Watch out**

* Keep `includes=suppliers`. Without it, plots owned by your supplier's own suppliers are left out of the list.
* `GET /plots` lists only your own business's plots, not your suppliers'.

### What is `riskLevel` and how should I use it?

**When:** to see whether a plot's deforestation analysis is complete and what it found, before you assess or declare the plot.

**Why:** before placing products on the market you must verify and analyse the information you collected, and conclude that the risk is no more than negligible (Art. 10). `riskLevel` is TradeAware's analysis signal; your conclusion is the assessment status you set yourself (next section).

`riskLevel` is read-only and returned only when you add `includes=riskLevel`. It comes from the most relevant analysis of the plot:

| Analysis available                | Risk 0 | Risk above 0 |
| --------------------------------- | ------ | ------------ |
| PRECISION (overrides open-source) | `none` | `high`       |
| Open-source only                  | `low`  | `medium`     |
| No completed analysis yet         | `null` | `null`       |

`null` means the analysis isn't ready yet; check again later. This matches what the web app shows, so automations behave like the UI.

**Steps**

```bash
curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/businesses/{supplierId}/plots?includes=suppliers,riskLevel&limit=500&page=1' \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

For your own plots, use `GET /plots?includes=riskLevel&limit=500&page=1`.

**Watch out**

* Which values you accept is your policy. For example, some customers mark `low` plots as compliant and send `medium` and `high` plots to review or mitigation.
* Never act on `null`: the analysis isn't finished.

## Record your assessment

### How do I set or update a plot's status?

**When:** after you have reviewed a plot, for example its risk level and documents, or when you move it into risk mitigation.

**Why:** the status records the outcome of your risk assessment (Art. 10) and of any mitigation (Art. 11). Products may only be placed on the market when the assessment shows no or only negligible risk. TradeAware never sets this status for you.

**Values:** `NEW`, `UNDER_REVIEW`, `IN_RISK_MITIGATION`, `EUDR_COMPLIANT`, `EUDR_NON_COMPLIANT`.

**Steps**

{% stepper %}
{% step %}

## Get existing statuses

Get the statuses your business has already set. Each entry has its own `id`, the `plotId` and the `status`.
{% endstep %}

{% step %}

## Update an existing assessment

If the plot already has an entry, update it with `PATCH /plot-risk-assessments/{id}`. Use the entry's `id`, not the plot id.
{% endstep %}

{% step %}

## Create a new assessment

If it has none, create one with `POST /plots/{plotId}/plot-risk-assessments` and store the `id` it returns. If the plot already has an entry, the POST returns 400 "Assessment already exists. Please update the existing assessment with id … instead.", with the id to update.
{% endstep %}
{% endstepper %}

```bash
curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/plot-risk-assessments' \
  --header 'Authorization: Bearer YOUR_TOKEN'

curl --request PATCH \
  --url 'https://api.tradeaware.live-eo.com/plot-risk-assessments/{assessmentId}' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "UNDER_REVIEW", "notes": "Waiting for supporting documents" }'

curl --request POST \
  --url 'https://api.tradeaware.live-eo.com/plots/{plotId}/plot-risk-assessments' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "EUDR_COMPLIANT", "notes": "Marked compliant after internal review" }'
```

`notes` is optional (up to 1,000 characters).

**Watch out**

* You can read your statuses from `GET /plot-risk-assessments`, or on the plots themselves by adding `includes=riskAssessmentStatus` to the plots call. The riskAssessmentStatus field is a plain value such as “`EUDR_COMPLIANT`”, null when your business hasn’t assessed the plot, and is also filled on plots owned by your supplier’s suppliers.
* The API sets one plot per call. To change many plots at once, use the bulk status update in the web app.
* If you set statuses automatically from `riskLevel`, that rule is your policy decision. Skip plots whose `riskLevel` is `null`.

### How do I set or update a supplier's status?

**When:** when you start, progress or conclude the assessment of a supplier.

**Why:** the supplier is part of your risk assessment (Art. 10), and the status lets your integration block transactions for suppliers you haven't cleared (check C1).

**Values:** `NEW`, `UNDER_REVIEW`, `READY_FOR_ASSESSMENT`, `CMS_ASSESSMENT_REQUESTED`, `CMS_ASSESSMENT_COMPLETED`, `IN_RISK_MITIGATION`, `EUDR_COMPLIANT`, `EUDR_NON_COMPLIANT`. The two CMS statuses require an entitlement.

**Steps**

{% stepper %}
{% step %}

## Find the supplier assessment

`GET /supplier-risk-assessments`: find the entry whose `supplierId` is your supplier.
{% endstep %}

{% step %}

## Update or create the assessment

If there is one, update it with `PATCH /supplier-risk-assessments/{id}`. Otherwise create one with `POST /businesses/{supplierId}/supplier-risk-assessments` and store the `id` it returns. If the supplier already has an entry, the POST returns 400 "Assessment already exists. Please update the existing assessment with id … instead."
{% endstep %}
{% endstepper %}

```bash
curl --request POST \
  --url 'https://api.tradeaware.live-eo.com/businesses/{supplierId}/supplier-risk-assessments' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "UNDER_REVIEW", "notes": "Initial assessment started", "attachmentIds": [] }'
```

**Watch out**

* `attachmentIds` replaces the whole list. Always send every attachment you want to keep; send `[]` to remove them all.
* The API sets one supplier per call.
* Subscribe to the `supplier_risk_assessment.updated` webhook if other systems need to react to status changes.

## Create transactions

### Should a failed check filter plots out or block the transaction?

Each check can run in one of two modes:

* **Filter:** leave out the plots that fail and continue with the rest.
* **Block:** stop, don't submit, and send the transaction to someone for review.

**Why it matters:** Filter changes which plots appear in the DDS, not where the goods came from. Use it only when the plots you leave out did not supply the goods in this transaction, for example when a supplier's plot list covers more than this shipment. If they did supply them, use Block: the DDS must list the geolocation of all plots the product was produced on (Art. 9(1)(d)).

The next question lists every check with the mode we recommend as a strict default. Change the modes to fit your due-diligence policy.

### Which checks can I run, and how?

**When:** every time you pick plots. The API accepts these mistakes on the draft, and they only surface after submission, if at all.

**Why:** the DDS must describe the product correctly, including the species for wood, the geolocation of every plot and the production period (Art. 9(1)(a) and (d)), and only products assessed as no or negligible risk may be placed on the market (Art. 10).

Most checks read fields from the supplier’s plot list, `GET /businesses/{supplierId}/plots?includes=suppliers,riskLevel,riskAssessmentStatus&limit=500`, one page at a time.

<table><thead><tr><th width="160.5234375">Check</th><th>How to check</th><th>What happens if you skip it</th><th>Recommended mode</th></tr></thead><tbody><tr><td><strong>C1</strong> Supplier assessed as compliant</td><td><code>GET /supplier-risk-assessments</code>: the entry with this <code>supplierId</code> has status <code>EUDR_COMPLIANT</code>. No entry means your business hasn't assessed the supplier.</td><td>TradeAware doesn't check the supplier's status; the transaction goes through.</td><td>Block</td></tr><tr><td><strong>C2</strong> Plot assessed as compliant</td><td><code>riskAssessmentStatus</code> is EUDR_COMPLIANT in the plots call (needs includes=riskAssessmentStatus), or the entry with this plotId in <code>GET /plot-risk-assessments</code> has status EUDR_COMPLIANT. null, or no entry, means your business hasn’t assessed the plot. In Filter mode you can add <code>filter.riskAssessmentStatus=$eq:EUDR_COMPLIANT</code> to the plots call instead.</td><td>The plot is filed whatever its status.</td><td>Filter or Block</td></tr><tr><td><strong>C3</strong> Deforestation analysis done and acceptable</td><td><code>riskLevel</code> in the plots call (needs <code>includes=riskLevel</code>). <code>null</code> means no completed analysis yet. Which values you accept is your policy.</td><td>You may file a plot nobody has analysed.</td><td>Filter; on <code>null</code>, wait and retry</td></tr><tr><td><strong>C4</strong> Plot belongs to the supplier and grows the component's commodity</td><td>The plot appears in the plots call for a supplier on the component, and its <code>commodities</code> contains the commodity of the component's HS code (cattle, cocoa, coffee, oil palm, rubber, soya or timber). <code>GET /transactions/{id}</code> shows TradeAware's mapping in <code>components[].commodity</code>. In the plots call, <code>filter.commodities=$contains:&#x3C;commodity></code> does this for you.</td><td>The draft accepts it without an error. If no plot of the commodity is left, the transaction ends in ERROR "missing plots for …" followed by the commodity. If at least one is left, the others are dropped without an error, so the DDS holds fewer plots than you sent.</td><td>Filter</td></tr><tr><td><strong>C5</strong> Plot lies within a country</td><td><code>countryCode</code> is not <code>XX</code>. TradeAware sets <code>XX</code> when a plot falls outside every country, for example at sea.</td><td>TRACES rejects the producer country and the transaction ends in ERROR.</td><td>Filter</td></tr><tr><td><strong>C6</strong> Timber species recorded</td><td>For timber, the plot's <code>species</code> list is not empty. </td><td>TradeAware adds the species of the plots you send to <code>namePairs</code>. If none of them has species and you don’t send <code>namePairs</code>, the component is rejected with 400.</td><td>Block</td></tr><tr><td><strong>C7</strong> Production period recorded</td><td><code>productionDateStart</code> and <code>productionDateEnd</code> are not null. They come back date-only (for example <code>2026-08-31</code>); </td><td>TradeAware sets the period from the plots that have both dates and ignores the others, so the DDS period may not cover every plot. If no plot has both dates, the component gets no production period, which Art. 9(1)(d) requires.</td><td>Block or flag</td></tr><tr><td><strong>C8</strong> Product link not expired (products only)</td><td>In <code>GET /products/{productId}/plots</code>, the supplier's <code>plotsExpiryDate</code> is null, today or later.</td><td>Expired links are still used at submission.</td><td>Block</td></tr><tr><td><strong>C9</strong> Every supplier linked plots (products only)</td><td>In <code>GET /products/{productId}/plots</code>, every supplier on the component has at least one plot in <code>assignedPlots</code>.</td><td>A supplier without linked plots adds no plots, and the API returns no error. If no supplier has linked plots, the transaction ends in ERROR "missing plots for …" followed by the commodity.</td><td>Block</td></tr></tbody></table>

### How do I create a transaction for plots I selected?

**When:** your ERP knows the supplier of a purchase and your integration decides which plots go into the DDS.

**Why:** you must submit a due diligence statement before placing products on the market or exporting them (Art. 4(2)). It carries the geolocation of the plots and the date or time range of production (Art. 9(1)(d)) and, for wood products, the common and scientific name of each species (Art. 9(1)(a)).

**Steps**

{% stepper %}
{% step %}

## Check the supplier

Check the supplier (C1).
{% endstep %}

{% step %}

## List the supplier's plots

List the supplier’s plots with `includes=suppliers,riskLevel,riskAssessmentStatus`, page by page (see “How do I list all plots behind a supplier?”).
{% endstep %}

{% step %}

## Get plot statuses

Read your status from each plot’s `riskAssessmentStatus`, or get all your statuses once with `GET /plot-risk-assessments`.
{% endstep %}

{% step %}

## Run checks C2 to C7

Run C2 to C7 on each plot and keep the ids that pass. If a check in Block mode fails, stop and route the transaction to review.
{% endstep %}

{% step %}

## Create the draft transaction

Create the transaction as DRAFT with the kept ids as `plotIds` (example below).
{% endstep %}

{% step %}

## Recheck before submission

Right before you submit, run C2 and C3 again on the component's plots: statuses and analyses can change after you created the draft. Change the plots with `PATCH /components/{id}` if needed.
{% endstep %}

{% step %}

## Submit and track the result

Submit and track the result (see "How do I submit and get the DDS reference number?").
{% endstep %}
{% endstepper %}

Example: a timber import with checked plots.

```bash
curl --request POST \
  --url 'https://api.tradeaware.live-eo.com/transactions' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "customId": "PO-4500012345",
    "activityType": "IMPORT",
    "countryOfActivity": "DE",
    "legalEntityId": "<legal entity id>",
    "customData": { "erpPurchaseOrder": "4500012345" },
    "components": [
      {
        "hsn": "440791",
        "description": "Oak sawn wood",
        "quantity": 12000,
        "unit": "KGM",
        "supplierBusinessId": "<supplier id>",
        "plotIds": ["<plot id 1>", "<plot id 2>"],
        "namePairs": [
          { "commonName": "Oak", "scientificName": "Quercus robur" }
        ],
        "dateOfProduction": "2026-03-01T00:00:00.000Z",
        "endDateOfProduction": "2026-06-30T00:00:00.000Z"
      }
    ]
  }'
```

You can leave out `namePairs` and the two dates; TradeAware then takes them from the plots.

**Watch out**

* **Always send `plotIds`.** A component with a supplier and no `plotIds` gets all of that supplier's plots of the component's commodity, whatever their assessment status. The draft then shows `plotIds: null`, so you can't see which plots will be filed. An empty list (`plotIds: []`) is rejected with 400.
* **Period and species come from the plots.** Leave out `dateOfProduction` and `endDateOfProduction`, and TradeAware sets them from the earliest `productionDateStart` to the latest `productionDateEnd` of the plots you send. For timber, it adds the plots’ species to `namePairs`, so send `namePairs` only when the plots carry no species. Species you send are kept.
* **Removing plots doesn’t narrow them.** When you change `plotIds` with `PATCH /components/{id}`, the period is only widened and species are only added for newly included plots. If you remove plots after the recheck, send `dateOfProduction`, `endDateOfProduction` and `namePairs` in the same request. Sending `namePairs` replaces the list.
* **Dates are full UTC timestamps** ending in `Z`, as in the example. Date-only values are rejected with 400.
* **Several suppliers:** use `supplierBusinessIds`. Each listed supplier must keep at least one plot in `plotIds`, otherwise the API returns 400 "Some suppliers were referenced but do not have any plots associated with them". The DDS lists one producer per supplier.
* Set `customId` now. It can’t be changed after you submit; `customData` can (see “Can I change a transaction after I submitted it?”).
* Some HS codes also need `supplementaryUnit` and `supplementaryUnitQualifier`; see Manage your transactions.

{% hint style="info" %}
**Recommended strict setup:** C1 in Block mode; C2 to C5 in Filter mode on the supplier's plots, so only assessed, analysed, in-country plots of the right commodity are sent; C6 and C7 in Block mode; and the re-check in step 6 before every submission. If you can't confirm that the plots you leave out did not supply the goods, run C2 and C3 in Block mode as well.
{% endhint %}

### How do I include only plots I marked `EUDR_COMPLIANT`?

**When:** your policy is that only plots your team has reviewed and cleared go into a DDS.

**Why:** products may only be placed on the market when your risk assessment shows no or only negligible risk (Art. 10). TradeAware files the plots you send and doesn't leave any out because of their status, so this filter lives in your integration.

**Steps**

{% stepper %}
{% step %}

## List the supplier's plots

List the supplier’s plots with `includes=suppliers,riskAssessmentStatus` (see “How do I list all plots behind a supplier?”).
{% endstep %}

{% step %}

## Keep compliant plots

Keep the plots whose riskAssessmentStatus is `EUDR_COMPLIANT`.
{% endstep %}

{% step %}

## Send the compliants plots

Send them as `plotIds`.
{% endstep %}
{% endstepper %}

**Shortcut**: `filter.riskAssessmentStatus=$eq:EUDR_COMPLIANT` on the plots call returns only compliant plots in one call, including plots owned by your supplier’s suppliers.

```bash
curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/businesses/{supplierId}/plots?includes=suppliers&filter.riskAssessmentStatus=$eq:EUDR_COMPLIANT&limit=500&page=1' \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

**Watch out**

* Leaving plots out changes which plots appear in the DDS, not where the goods came from (see "Should a failed check filter plots out or block the transaction?").
* Statuses can change after you create the draft. Check them again right before you submit; no webhook fires when a plot status changes.

### How do I create a transaction from my product catalogue?

**When:** you created products, shared them with your suppliers, and your suppliers linked the plots each product comes from (see Manage products and plot links).

**Why:** product links let your suppliers maintain which plots stand behind each product, and the DDS still has to list all of those plots (Art. 9(1)(d)).

**How TradeAware picks the plots:** for a component with `productIds`, it adds the plots that each supplier listed on the component has linked to those products, plus any `plotIds` you send. It reads the links when it processes the submission, which happens asynchronously after `PUT /transactions/{id}/submit`, so a supplier's change before that point reaches the DDS:

* Plots a supplier deleted or unlinked before that point are left out.
* A link whose valid-until date has passed is still used.
* `plotIds` can only add plots: while `productIds` is on the component, a linked plot can't be left out.

**Steps**

{% stepper %}
{% step %}

## Read product links

Read the links with `GET /products/{productId}/plots?includes=riskAssessmentStatus,riskLevel.` You get one entry per supplier with `plotsExpiryDate` and `assignedPlots`; each plot carries its `id, commodities, country code, species, production dates,` your `status` and its `riskLevel`.
{% endstep %}

{% step %}

## Run supplier checks

For each supplier on the component, run C1, C8 and C9.
{% endstep %}

{% step %}

## Run linked-plot checks

Add `includes=riskAssessmentStatus,riskLevel` to `GET /products/{productId}/plots`. Each linked plot then carries your status and its `riskLevel`, so C2 and C3 need no other call. Any other `includes` value returns 400.
{% endstep %}

{% step %}

## Choose a transaction pattern

If every check passed, use pattern A. If some plots failed and your policy allows leaving them out, use pattern B. If a check in Block mode failed, don't create or submit the transaction: the supplier corrects its link in the web app or with `PUT /products/{productId}/plots`, and your team updates plot statuses with the plot risk assessment endpoints.
{% endstep %}

{% step %}

## Submit and track the result

Submit and track the result (see "How do I submit and get the DDS reference number?").
{% endstep %}
{% endstepper %}

#### Pattern A: reference the product

Send `productIds` together with the suppliers and no `plotIds`.

```json
{
  "hsn": "1801",
  "description": "Raw cocoa beans, Grade A",
  "quantity": 24000,
  "unit": "KGM",
  "productIds": ["<product id>"],
  "supplierBusinessIds": ["<supplier id>"],
  "dateOfProduction": "2026-06-01T00:00:00.000Z",
  "endDateOfProduction": "2026-08-31T00:00:00.000Z"
}
```

On the draft, `GET /transactions/{id}` shows the product under `products` and `plotIds: null`: the linked plots are added at submission. Right before you submit, read `GET /products/{productId}/plots` again and compare the plot ids with the set you checked. If they differ, run the checks again.

**Watch out**

**Period and species are set when you create the component.** For a component with `productIds`, TradeAware takes the production period and, for timber, the species from the plots linked to the product at that moment. If a supplier changes its links before you submit, these values aren’t updated, but the DDS files the plots linked at submission. Right before you submit, read `GET /products/{productId}/plots` again. If the plots changed, send `dateOfProduction`, `endDateOfProduction` and `namePairs` with `PATCH /components/{id}`, or use pattern B.

#### Pattern B: send the checked plots

Send the plots that passed as `plotIds` with their suppliers and leave `productIds` out. The DDS then contains exactly those plots, and later changes to the product links don't affect the transaction. The component has no product reference, so keep your product id or reference in the transaction's `customData` if you need it for your records.

**Watch out**

* List the suppliers on the component. A component with `productIds` and no supplier is rejected with 400, and linked plots come only from the suppliers you list. `productIds` must be products your business owns.
* With `supplierBusinessIds` in pattern B, list only suppliers that keep at least one plot in `plotIds`; otherwise the API returns 400 "Some suppliers were referenced but do not have any plots associated with them".
* Don't delete a product while a transaction that uses it hasn't been processed. The component loses its product reference, and TradeAware then files all of the listed suppliers' plots of that commodity, including plots they never linked.
* No webhook fires when a supplier changes its links, so read them again before you submit.

{% hint style="info" %}
**Recommended strict setup:** C1 to C9 in Block mode for every supplier and linked plot, pattern A, and the comparison before every submission. Use pattern B when your policy allows leaving out plots that did not supply this shipment, or when the DDS must not change after your checks: a supplier can still change its links between your submit call and TradeAware processing it.
{% endhint %}

## Submit and follow up

### How do I submit and get the DDS reference number?

**When:** the draft is final and your checks passed.

**Why:** the DDS must be submitted before the products are placed on the market or exported (Art. 4(2)). Downstream operators who buy from you must collect the reference number of your DDS (Art. 5(3)(a)), so pass it on to your customers.

**Steps**

{% stepper %}
{% step %}

## Run checks again

Run your status and risk checks again; both can change after you created the draft.
{% endstep %}

{% step %}

## Submit the transaction

Submit. The call returns 202 and the status `TO_SUBMIT`.
{% endstep %}

{% step %}

## Track the result

Track the result with the `transaction.updated` webhook or by polling `GET /transactions/{id}`. Submission is asynchronous: wait at least 30 minutes after submitting before you poll. The status moves from `TO_SUBMIT` to `SUBMITTED` and then to `AVAILABLE` or `ERROR`.
{% endstep %}

{% step %}

## Read the DDS references

At `AVAILABLE`, read `dds.tracesDdsReferenceNumber` and `dds.tracesDdsVerificationNumber` from `GET /transactions/{id}`. The webhook payload doesn't include them.
{% endstep %}
{% endstepper %}

```bash
curl --request PUT \
  --url 'https://api.tradeaware.live-eo.com/transactions/{id}/submit' \
  --header 'Authorization: Bearer YOUR_TOKEN'

curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/transactions/{id}' \
  --header 'Authorization: Bearer YOUR_TOKEN'
```

To read back what TRACES holds, call `GET /dds/fetch-dds-data?referenceNumber={ref}&verificationNumber={ver}`. It is limited to 2 requests per 10 seconds per client.

**Watch out**

* After you submit, only `customData` can still be changed (see “Can I change a transaction after I submitted it?”).
* On PRODUCTION, every submitted transaction is a legally binding DDS. Within 72 hours of submission you can amend or withdraw it. See Amend or withdraw a submitted transaction.

### My transaction ended in ERROR. How do I fix it?

**When:** the status is `ERROR`: TradeAware or TRACES refused the statement, and no DDS exists yet.

**Why:** nothing has been filed, so you can correct the transaction and submit it again.

**Steps**

{% stepper %}
{% step %}

## Read the error reason

Read the reason in `dds.errors` on `GET /transactions/{id}`.
{% endstep %}

{% step %}

## Fix the data

Fix the data. Change plots with `PATCH /components/{id}`; the `plotIds` you send replace the existing list, and an empty list is rejected with 400. Change transaction fields with `PATCH /transactions/{id}`.
{% endstep %}

{% step %}

## Submit again

Submit again with `PUT /transactions/{id}/submit`. The transaction goes back to `TO_SUBMIT`.
{% endstep %}
{% endstepper %}

| Error                                                                                 | Usual cause                                                                                    |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| "missing plots for …" followed by the commodity                                       | No plot of the component's commodity: wrong plots, or a product without linked plots (C4, C9). |
| An error about the producer country code                                              | A plot with `countryCode` `XX` (C5).                                                           |
| `EUDR-COMMODITIES-HS-CODE-INVALID`                                                    | TRACES doesn't accept the HS code.                                                             |
| A TRACES rejection on an IMPORT or EXPORT that sent `percentageEstimationOrDeviation` | The field is only accepted on DOMESTIC.                                                        |
| Error: “Plots payload exceeds the maximum allowed size of 25 MB”                      | Usual cause: the geolocation of the plots is larger than TRACES accepts for one DDS (25 MB).   |

**Watch out:** after you resubmit, `dds.errors` can still show the previous error until the new attempt has been processed.

### Can I change a transaction after I submitted it?

Only its `customData`. Once you have submitted a transaction (TO\_SUBMIT), and in every later status, `PATCH /transactions/{id}` accepts `customData` on its own and saves it without changing the status or the DDS; nothing is resubmitted. Any other field in the body, customId included, and every `PATCH /components/{id}`, returns 409 “The transaction is not in draft state and therefore cannot be modified”, and nothing is changed. Only DRAFT transactions, and ones that ended in ERROR, can be changed fully.

`customData` is replaced as a whole, so send every key you want to keep. To clear it, send {}; null is rejected with 400.

So set `customId` (for example your purchase order or shipment number) before you submit, or keep the mapping between the TradeAware transaction id and your own reference in your system.

To correct or cancel a DDS that’s already `AVAILABLE`, amend or withdraw it within 72 hours of the original submission. An amendment doesn’t restart that window, and it replaces the whole statement, so send every component again. See Amend or withdraw a submitted transaction.

### How do I retry safely after a timeout?

**When:** a `POST /transactions` call timed out or the connection dropped, and you don't know whether it went through.

**Why:** TradeAware doesn't check for duplicates. Every create call makes a new transaction, even with the same `customId` and data, and each one you submit becomes its own DDS.

**Steps**

{% stepper %}
{% step %}

## Check for an existing transaction

Before you retry, call `GET /transactions` and look for your `customId`. The call returns all your transactions, so search the list in your integration.
{% endstep %}

{% step %}

## Reuse the transaction if found

If you find it, use that transaction instead of creating a new one.
{% endstep %}

{% step %}

## Delete an extra draft

If you end up with a duplicate, delete the extra one with `DELETE /transactions/{id}` while it is still a `DRAFT`.
{% endstep %}
{% endstepper %}

**Watch out:** turn off automatic retries for `POST` requests in your HTTP client or middleware, or route them through the check above.

### Which webhook events can I subscribe to?

**When:** you want to react to changes instead of polling.

**Events:** `transaction.updated`, `business_invitation.updated`, `analysis.precision.updated` and `supplier_risk_assessment.updated`. `GET /webhooks/events` returns the current list.

```bash
curl --request POST \
  --url 'https://api.tradeaware.live-eo.com/webhooks' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://example.com/tradeaware-events", "events": ["transaction.updated"] }'
```

Get the endpoint secret with `GET /webhooks/{id}/secret`, send a test message with `POST /webhooks/{id}/send-example`, and see delivery attempts with `GET /webhooks/{id}/attempts`.

**Watch out**

* No event fires when a plot's status or a product's links change. Read them again right before you submit.
* `transaction.updated` doesn't carry the DDS numbers. Read them from `GET /transactions/{id}`.

## Sources

Article numbers refer to Regulation (EU) 2023/1115 (EUDR) as amended by Regulations (EU) 2024/3234 and 2025/2650: [consolidated text on EUR-Lex](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX%3A02023R1115-20251226). API behaviour follows the TradeAware API reference (v0.62.0).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/api-integration-use-cases-for-eudr-due-diligence.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
