dispute

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/cash-app/main/json-schema/cash-app-dispute-schema.json",
  "title": "dispute",
  "description": "Dispute object",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cash-app-disputes-api-openapi.yml#/components/schemas/dispute",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Dispute identifier"
    },
    "order": {
      "type": "string",
      "description": "The token of the order that the dispute is for."
    },
    "amount": {
      "type": "string",
      "description": "The amount of the dispute"
    },
    "reason": {
      "$ref": "#/$defs/DisputeReason",
      "description": "The reason for the dispute."
    },
    "status": {
      "$ref": "#/$defs/DisputeStatus",
      "description": "The current state of the dispute. Values depend on how the dispute state machine is modeled."
    },
    "open": {
      "type": "boolean",
      "default": true,
      "description": "`True` if a final decision on the dispute hasn't been made yet."
    },
    "responseDueBy": {
      "type": "string",
      "description": "Deadline by which the merchant must respond to the dispute. (Epoch timestamp in seconds, timezone UTC +0.00)"
    },
    "createdAt": {
      "type": "string",
      "description": "A timestamp indicating when the dispute was created. (Epoch timestamp in seconds, timezone UTC +0.00)"
    },
    "openingNote": {
      "type": "string",
      "description": "Text from the customer describing why the dispute was opened or the reason for the complaint. While dispute category codes are helpful at informing what a merchant should present, it doesn’t provide reasoning behind the customer’s complaint. In some cases, this can help merchants troubleshoot the dispute directly with their customers."
    },
    "openingNoteAttachments": {
      "type": "string",
      "description": "Attachments to supplement the `openingNote` if the customer provided photos or screenshots as part of their dispute description."
    },
    "updatedAt": {
      "type": "string",
      "description": "Timestamp when the dispute was updated. (Epoch timestamp in seconds, timezone UTC +0.00)"
    },
    "closingReason": {
      "$ref": "#/$defs/DisputeClosingReason",
      "description": "A reason indicating how the final decision on the dispute was reached. Recommended possible values listed in Closing Reasons."
    },
    "closingNote": {
      "type": "string",
      "description": "Text describing in detail how the final decision on the dispute was reached. This supplements the `closingReason`."
    },
    "merchantOrderId": {
      "type": "string",
      "description": "The identifier for the transaction on the merchant side."
    },
    "transactionDate": {
      "type": "string",
      "description": "The timestamp of the order created by the customer. (Epoch timestamp in seconds, timezone UTC +0.00)"
    },
    "settlementAmount": {
      "type": "string",
      "description": "The settlementAmount for audit usage."
    },
    "meta": {
      "$ref": "#/$defs/meta",
      "description": "The extra information for merchants to match payment."
    }
  },
  "required": [
    "id",
    "order",
    "amount",
    "reason",
    "status",
    "open",
    "responseDueBy",
    "createdAt",
    "openingNote",
    "closingReason",
    "merchantOrderId",
    "transactionDate",
    "settlementAmount"
  ],
  "$defs": {
    "DisputeClosingReason": {
      "type": "string",
      "enum": [
        "merchant_accepted",
        "evidence_accepted",
        "evidence_rejected",
        "deadline_expired",
        "customer_cancelled"
      ],
      "description": "A reason indicating how the final decision on the dispute was reached. Recommended possible values listed in Closing Reasons.",
      "title": "DisputeClosingReason"
    },
    "DisputeReason": {
      "type": "string",
      "enum": [
        "product_not_received",
        "product_unacceptable",
        "credit_not_processed",
        "order_canceled",
        "duplicate",
        "incorrect_amount",
        "paid_by_other_means",
        "fraudulent",
        "fraudulent_merchant"
      ],
      "description": "The reason for the dispute.",
      "title": "DisputeReason"
    },
    "DisputeStatus": {
      "type": "string",
      "enum": [
        "needs_response",
        "under_review",
        "won",
        "lost",
        "merchant_refunded",
        "merchant_voided"
      ],
      "description": "The current state of the dispute. Values depend on how the dispute state machine is modeled.",
      "title": "DisputeStatus"
    },
    "meta": {
      "type": "object",
      "properties": {
        "transactionAmount": {
          "type": "string",
          "description": "The transaction amount for the order."
        },
        "network": {
          "type": "string",
          "description": "The payment network used by the customer. (For example, `Visa` or `MasterCard`)"
        },
        "networkReferenceId": {
          "type": "string",
          "description": "The identifier for the payment."
        },
        "orderType": {
          "type": "string",
          "description": "The type of order. `ONLINE` or `INSTORE`"
        }
      },
      "required": [
        "transactionAmount",
        "orderType"
      ],
      "title": "meta"
    }
  }
}