Webhooks

  • dispute.evidence.added

  • dispute.evidence.removed

  • dispute.state.changed

Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

<- Disputes webhooks

Disputes webhooks

All versions ->

dispute state changed

DEPRECATED

 dispute.state.changed

Published when the state of a Dispute changes. This includes the dispute resolution (WON, LOST) reported by the bank. The event data includes details of what changed.

Permissions:PAYMENTS_READ
Link to section

Event payload

Example code

Link to section

merchant_id

string

The ID of the target merchant associated with the event.

Link to section

location_id

string

The ID of the target location associated with the event.

Link to section

type

string

The type of event this represents.

Link to section

event_id

string

A unique ID for the event.

Link to section

created_at

string

Read only Timestamp of when the event was created, in RFC 3339 format.

Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

UTC: 2020-01-26T02:25:34Z

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00

Link to section

data

Data associated with the event.

Link to section

Examples

All versions ->

Response JSON

{ "merchant_id": "0HPGX5JYE6EE1", "location_id": "VJDQQP3CG14EY", "type": "dispute.state.changed", "event_id": "e89ff114-1972-4be0-9481-a621f2385fff", "created_at": "2020-02-19T21:34:41.851Z", "data": { "type": "dispute", "id": "ORSEVtZAJxb37RA1EiGw", "object": { "dispute": { "amount_money": { "amount": 8801, "currency": "USD" }, "brand_dispute_id": "r9rKGSBBQbywBNnWWIiGFg", "card_brand": "VISA", "created_at": "2020-02-19T21:24:53.258Z", "dispute_id": "ORSEVtZAJxb37RA1EiGw", "disputed_payment": { "payment_id": "fbmsaEOpoARDKxiSGH1fqPuqoqFZY" }, "due_at": "2020-03-04T00:00:00.000Z", "evidence_ids": [ "Vjq6LG8b95cnnq1AoG5bP" ], "location_id": "VJDQQP3CG14EY", "reason": "AMOUNT_DIFFERS", "reported_date": "2020-02-19T00:00:00.000Z", "state": "WON", "updated_at": "2020-02-19T21:34:41.851Z", "version": 6 } } } }