Suppliers

If your plot file carries supplier columns, Epoch links each plot to a supplier as part of the normal POST /ingestions/assets flow. No separate call is required.

Recognized supplier columns:

These columns apply uniformly across upload formats — CSV, GeoJSON properties, Parquet, GeoPackage, Excel. Rows that share an external_id (or whose identity fields produce the same fingerprint) reuse the existing supplier rather than creating a duplicate.

A facility upload that names its supplier via producer_name or Supplier_Address (instead of the supplier_* columns above) is also registered: a deduplicated supplier row is created and linked to the facility, and it resolves onto that facility's plots at DDS time. Previously such a supplier appeared only as a display name on the DDS and never became a first-class, filterable registry row — see Supplier-name fallback.

Shapefiles (.zip) are the exception: the DBF attribute table truncates field names to 10 characters, so supplier_name, supplier_address, etc. arrive mangled and won't be matched. For shapefile uploads, attach the supplier with the upload-wide supplier object instead (next section).

Country and other identity fields are validated as part of upload validation. Invalid values surface as soft validation issues on the asset task, not as a hard 400 — the upload still completes and the rows missing valid supplier data get flagged for review.

When a whole file represents one supplier — or the format can't carry per-row columns cleanly (shapefiles) — pass a structured supplier object on the POST /ingestions/assets body (JSON flow) or as a JSON-stringified supplier form field (multipart). It applies to every location in the upload as the fallback supplier; any per-row supplier columns still win where present.

"supplier": {
  "name": "Café Verde Cooperativa",   // required
  "external_id": "CV-001",
  "address_line1": "Rua do Café 100",
  "city": "Patrocínio",
  "region": "MG",
  "postcode": "38740-000",
  "country": "BR",                     // ISO 3166-1 alpha-2, validated
  "statement": "100% smallholder, deforestation-free."
}

Unlike the per-row columns (which the file format limits), the object accepts the full supplier field set and validates country against the ISO 3166-1 alpha-2 set. It writes to the same deduplicated registry, so re-uploading the same identity reuses the existing row. See Asset Upload — Attaching a supplier.

When you don't have a CSV column for a supplier (e.g. you're onboarding a small subset by hand), POST /parties/suppliers creates or reuses a supplier row directly. The supplier is automatically linked to your organization on create.

When locations were already uploaded without supplier information — or you need to correct or assign a supplier later — you don't have to re-upload. POST /parties/suppliers/:id/locations attaches an existing registry supplier to locations that are already in Epoch, writing the same link the ingestion path would have.

• The path :id is the supplier's UUID or your external_id (supplierid) — Epoch tries it as a UUID first, then falls back to your organization's external_id namespace.
• Choose locations one of two ways (you can combine them):
  • location_ids — the id values returned by GET /locations (staged-location ids).
  • asset_task_ids — attach the supplier to every location in those uploads.
• Both fields accept a single value or an array.
• It is latest-wins: attaching a different supplier to a location replaces the previous link.

POST /parties/suppliers/2fdff3fb-480c-43b0-84d8-6dd8aaacce61/locations
{
  "location_ids": ["b1c0…", "b1c1…"],   // ids from GET /locations
  "asset_task_ids": "9f3a…"             // or sweep a whole upload
}

The response echoes the supplier and a meta block reporting how many staged-locations were linked and which ids didn't resolve to a location visible to your organization (unresolved_location_ids, unresolved_asset_task_ids) — the request still succeeds for the ids that did resolve. Only an unknown or unlinked supplier returns 404.

Everything is scoped to your acting organization. As a parent organization, use the x-acting-as header to attach to a child organization's locations.

Each arm accepts up to 500 ids, but asset_task_ids expand to every location in those uploads. A single request that resolves to more than 10,000 distinct locations is rejected with 413 PAYLOAD_TOO_LARGE before anything is written — split the work across smaller batches of asset_task_ids / location_ids and retry.

Once attached, the supplier flows into any DDS you build from those locations through the normal plot → shed → facility resolution.

Required scope: parties:write

When a plot or shed has no registry supplier attached — for example data uploaded before supplier registration named suppliers via producer_name / Supplier_Address — the supplier rollup falls back to the normalised supplier name from the facility upload (supplier_name, then producer_name, then the Supplier_Address blob). This keeps the DDS showing a human-readable supplier instead of a raw shed identifier.

New uploads register the supplier instead of relying on this fallback. A facility upload naming its supplier via any of those columns now creates a deduplicated registry row and links it (see above), so it resolves through the normal supplier path and is visible/filterable. The read-time fallback below mainly covers data ingested before that behaviour, and any upload you deliberately opt out of registration for.

This fallback is enabled by default. To turn it off for a record, set resolve_supplier_by_name: false on the create body:

POST /regulations/eudr/audit-trail
{
  "data": {
    "type": "dds_record",
    "attributes": {
      "filter": { "assets.task_id": { "eq": "…" } },
      "resolve_supplier_by_name": false
    }
  }
}

With the flag set to false, a supplier that isn't attached to the registry is not backfilled from the upload's normalised name — it surfaces as the raw shed name (or an unresolved/null supplier in the rollup) instead. Suppliers that are attached (per-row columns, the upload-wide supplier object, or a registry link) are unaffected.

The choice is frozen on the version and inherited when you cut a new version, so a record created with the fallback disabled stays disabled across re-cuts unless you explicitly create it again with the flag enabled.