Update DDS Record

See Create Audit Trail for the field-by-field reference, per-field validation rules, and the full "who/what each block represents" preamble. Validation applies to every field that is present: an invalid email or hs_code is still a 400 even if the rest of the body is valid.

• commodity.supplementary_unit / supplementary_unit_qualifier — the optional goodsMeasure second TARIC unit (net weight in kg always rides on product_quantity_kg). The qualifier is a UN/CEFACT Rec20 code: MTQ (cubic metres — timber volume), NAR (number of articles) or KSD (kilograms of dry substance — pulp). KGM is rejected (it is net weight's unit). The amount and qualifier must be present together: setting one and clearing the other — after merging with the stored values — is a 422.

• commodity species — species_scientific_name / species_common_name are required only for timber / timber-derived commodities (HS chapters 44, 47); enforced at submit via the species_missing pre-submission blocker, not rejected here.

• activity_type — DOMESTIC, IMPORT, or EXPORT. Cross-field rules run against the merged (stored + patch) state, so patching one half of an invariant is a 422: DOMESTIC requires the merged country_of_activity to be null; IMPORT/EXPORT require the merged operator to be EORI-identified (not VAT); a non-EU operator (outside EU-27 + XI) can only file IMPORT. Two ergonomic carve-outs: (a) the activity/operator rules fire only when the patch actually changes a participating value — re-sending a field at its stored value is a no-op, and a pre-existing (e.g. create-time default) combination is tolerated until the operator_identifier_invalid / activity_not_allowed_for_operator_country pre-submission blockers stop it at filing; (b) switching to DOMESTIC without sending country_of_activity auto-clears any stored country (the field is hidden on DOMESTIC forms, so requiring an explicit null would trap them) — the record_update audit event carries the cleared value as country_of_activity_autocleared. Explicitly sending DOMESTIC together with a non-null country_of_activity is still a 422.

  A 422 from the two activity/operator rules carries a data.details.issues array anchoring the rejection to the request-body fields that produced it, shaped like flattened Zod issues ({ "path": [...], "message": "..." }). Both participating fields are listed, because either one is a valid fix — an IMPORT with a VAT-identified operator is resolved by switching the identifier to EORI or by switching the activity to DOMESTIC, and the API cannot know which the caller intended:

  {
    "error": "For IMPORT the operator must be identified by EORI (not VAT); ...",
    "code": "VALIDATION_ERROR",
    "tracking_id": "req-1a2b3c",
    "details": {
      "issues": [
        { "path": ["data", "attributes", "activity_type"], "message": "..." },
        { "path": ["data", "attributes", "operator", "identifier_type"], "message": "..." }
      ]
    }
  }
  

  activity_not_allowed_for_operator_country anchors to data.attributes.operator.country instead of identifier_type. The other 422 arms on this endpoint (the DOMESTIC/country contradiction, the supplementary-unit pair) name no single field and so omit details entirely — read code first, then details if present.

• country_of_activity — EU-27 or XI (Northern Ireland) only (TRACES allow-list); lowercase input is uppercased. Only meaningful for IMPORT/EXPORT (it doubles as the border-cross country); null clears it back to "derive from operator.country at filing".

• comment — free text, trimmed, max 1024 chars; null clears.

Coffee policy note: TRACES acceptance accepts bare 0901 (IMPORT and EXPORT re-probed on 2026-10-19), and Epoch now accepts the bare heading alongside its five subheadings. Production has not been verified. Coffee acceptance fields and examples here describe the current fm-api policy.

A rubber record declared as 401290 reads hs_code_not_accepted_by_traces in meta.submission on Get DDS Record. The blocker's accepted_hs_codes lists 40129030. PATCH that code:

{ "data": { "type": "dds_record", "attributes": { "commodity": { "hs_code": "40129030" } } } }

The next GET no longer carries the blocker. The same PATCH clears hs_code_too_broad. supplementary_unit_required and supplementary_unit_qualifier_mismatch clear with a PATCH of commodity.supplementary_unit and supplementary_unit_qualifier. See HS codes TRACES accepts.

All string fields are trimmed server-side; pure-whitespace input is rejected. The lengths and formats listed in Create Audit Trail apply identically here for any field the caller chooses to patch.

Top-level attributes keys that don't map to an editable field are rejected with a 400 (the attributes object is strict — a typo'd or non-editable key surfaces as an error rather than a silent no-op):