Update Dispute Metadata

{
  "amount": 1,
  "created_at": "2024-01-15T09:30:00Z",
  "currency": "string",
  "dispute_id": "string",
  "processor": "STRIPE",
  "processor_dispute_id": "string",
  "reason": "credit_not_processed",
  "state": "inquiry",
  "counters": [
    {
      "counter_id": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "phase": "inquiry",
      "revision": 1,
      "state": "draft",
      "updated_at": "2024-01-15T09:30:00Z",
      "evidence_items": [
        {
          "category": "product_description",
          "file_ids": [
            "string"
          ],
          "text": "string"
        }
      ],
      "submitted_at": "2024-01-15T09:30:00Z",
      "submitted_by": "string"
    }
  ],
  "due_by": "2024-01-15T09:30:00Z",
  "metadata": {},
  "network_reason_code": "string",
  "outcome": "won",
  "phase": "inquiry",
  "prior_dispute_id": "string",
  "resolved_at": "2024-01-15T09:30:00Z"
}

This is a full replace, not a merge: the metadata object you send overwrites whatever was stored, so include every key you want to keep. Metadata is the only writable part of a dispute; its state, phase, reason, amounts, and deadlines are owned by the processor and are read-only. Scoped to your sales channel — you can only update metadata on your own disputes.

Attach your own metadata to a dispute — an internal case ID, the teammate who owns it, a link to your evidence workspace, free-form notes — so you can correlate Truemed disputes with your own systems. This is a **full replace**, not a merge: the `metadata` object you send overwrites whatever was stored, so include every key you want to keep. Metadata is the only writable part of a dispute; its state, phase, reason, amounts, and deadlines are owned by the processor and are read-only. Scoped to your sales channel — you can only update metadata on your own disputes.

Authentication

x-truemed-api-keystring

Sales channel API key for merchant server-to-server authentication

Path parameters

business_idstringRequired

The Truemed dispute ID (UUID).

Request

Request body for DisputeMetadataRequest

metadatamap from strings to anyRequired

Replaces the dispute’s metadata. Only metadata is mutable; state/amounts/deadlines are read-only.

Response

Successful response

amountinteger

The original disputed amount in cents, independent of resolution.

created_atdatetime

When the dispute was created.

currencystring

ISO currency code of the disputed amount.

dispute_idstring

Stable Truemed dispute ID (UUID). Use this as the dispute’s identifier.

processorenum

Payment processor the dispute originated from.

processor_dispute_idstring

Raw payment-processor dispute ID (e.g. Stripe du_…), for reconciliation.

reasonenum

Canonical reason the dispute was filed.

stateenum

Canonical dispute state.

counterslist of objectsDefaults to []

Evidence counters for this dispute (the full chain across phases).

due_bydatetime or null

Evidence submission deadline, if the dispute is challengeable.

metadatamap from strings to anyDefaults to {}

Arbitrary merchant-set metadata.

network_reason_codestring or null

Raw card-network reason code behind the dispute (e.g. Visa 10.4), if provided.

outcomeenum or null

Terminal outcome; null until the dispute resolves.

phaseenum or null

Which round of the dispute (inquiry, dispute, pre-arbitration, arbitration).

prior_dispute_idstring or null

Truemed dispute ID (UUID) of the prior round in a pre-arbitration/re-filing chain, if any.

resolved_atdatetime or null

When the dispute reached a terminal state.

Errors

400

Bad Request Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error

501

Not Implemented Error

$	curl -X POST https://dev-api.truemed.com/api/v1/disputes/business_id/metadata \
>	-H "x-truemed-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"metadata": {}
>	}'