disputes

Update a dispute's metadata (only metadata is mutable)

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.

post/api/v1/disputes/{business_id}/metadata

Request

  • Base URL: https://dev-api.truemed.com
  • URL: https://dev-api.truemed.com/api/v1/disputes/{business_id}/metadata
  • Auth: API key in header x-truemed-api-key

Path parameters

business_idstring required

The Truemed dispute ID (UUID).

Request body

metadataobject required

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

Response

Successful response

amountinteger required

The original disputed amount in cents, independent of resolution.

created_atstring date-time required

When the dispute was created.

currencystring required

ISO currency code of the disputed amount.

dispute_idstring required

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

due_bystring date-time nullable

Evidence submission deadline, if the dispute is challengeable.

metadataobject

Arbitrary merchant-set metadata.

network_reason_codestring nullable

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

outcome'won' | 'lost' | 'accepted' | 'expired' | 'closed'

Denormalized terminal outcome of a dispute; null until terminal.

payment_session_idstring nullable

The Truemed payment session this dispute belongs to. Null for disputes on non-payment-session charges.

phase'inquiry' | 'dispute' | 'pre_arbitration' | 'arbitration'

Which round of a dispute this is — orthogonal to DisputeState (comparison doc §4.3/§5).

prior_dispute_idstring nullable

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

processor'STRIPE' | 'FAKE' | 'EXTERNAL' required

Payment platforms supported by the public dispute API.

processor_dispute_idstring required

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

reason'credit_not_processed' | 'duplicate' | 'fraudulent' | 'general' | 'noncompliant' | 'product_not_received' | 'product_unacceptable' | 'subscription_canceled' | 'unrecognized' required

Canonical, card-network dispute reason — the only reasons Truemed can receive, since it settles HSA/FSA card payments over Stripe and never ACH/bank-debit. The enum is the processor-independent contract: each processor adapter maps its native reason vocabulary into this set (Adyen's raw card-scheme reason codes collapse into these buckets), so the enum itself carries no processor specifics.

Human labels live in _DISPUTE_REASON_LABELS, exposed via .label — the single backend contract the frontend and merchant emails hydrate from instead of maintaining their own label maps.

resolved_atstring date-time nullable

When the dispute reached a terminal state.

state'inquiry' | 'needs_response' | 'under_review' | 'won' | 'lost' | 'accepted' | 'expired' | 'closed' required

Canonical, processor-agnostic dispute state — the 8-state model in the Processor Disputes Comparison doc §4.3. Distinct from the Stripe-shaped DisputeStatus: a processor adapter maps raw status/eventCodes → (DisputeState, DisputePhase). closed is the favorable no-contest inquiry outcome (excluded from win-rate), kept separate from won.

Changes

No recorded changes to this operation across all 1 revision of this API.