Customer disputes

Fetching customer disputes, accepting and contesting; deadline, evidence and outcome rules.

Endpoints on this page

Each row links to the full definition in the API reference — fields, response codes and the try-it console.

Flow

When a customer reports a missing, wrong or damaged item, a late delivery or cold food after delivery, a dispute is opened and a response is expected from the business. The response window defaults to 15 dk from the moment the dispute is opened; the platform may change it and each dispute's deadline field is the binding cut-off. The response time is recorded in the business's performance. An accepted dispute closes with a refund. A contested dispute, or one left unanswered when deadline passes, moves to platform review. Late delivery (late) and cold food (cold_food) disputes are the exception: when contested, the dispute is closed and no refund is made. cold_food occurs on restaurants only.

text

dispute opened ──▶ awaiting business response ──accept──▶ closed (refund)
                                  │
                                  ├──contest──▶ platform review ──▶ closed
                                  ├──deadline passes──▶ platform review (platform decides)
                                  └──contest (late, cold_food)──▶ closed (no refund)

Fetching disputes

GET /disputes response

{
  "items": [
    {
      "id": "cm_ornek_talep",
      "orderId": "cm_ornek_siparis",
      "orderRef": "AB12CD34",
      "type": "missing_item",
      "amount": 50,
      "items": [{ "id": "cm_ornek_kalem", "name": "Örnek Ürün", "quantity": 1, "amount": 50 }],
      "evidencePhotoCount": 0,
      "deadline": "2026-01-31T16:00:00.000Z",
      "deadlineMinutes": 42,
      "createdAt": "2026-01-31T15:00:00.000Z",
      "acceptRemedies": ["refund"],
      "contestReasons": ["not_my_fault", "product_correct", "other"]
    }
  ],
  "nextCursor": null
}

Only disputes awaiting a response are returned. The list is not paged (the full list) and the dispute with the nearest deadline comes first; nextCursor is always null. deadlineMinutes is the minutes left to the deadline, 0 if it has passed.

Alan	Tip	Açıklama
`type`	enum	`cancel · missing_item · wrong_item · damaged · other · not_delivered · late · cold_food`. `cold_food`: the food arrived cold; opened for selected items. `late`: late delivery; opened without selecting items. The set is closed for this version; handle a type you do not recognise with a safe default instead of ignoring it.
`amount`	number	Total amount claimed. For a `late` dispute it is the order's item total and the upper limit of the refund on acceptance.
`items[]`	array	Item-level claim: `id` (the input of an item-level response), `name`, `quantity`, `amount`. On Çarşı also `clientReferenceId`, `sku`, `barcode`.
`evidencePhotoCount`	integer	The number of evidence photos the customer uploaded. The photos are not served through this surface; they are seen in the business console.

Accepting and contesting

Accept (refund)

curl -X POST "https://api.supergelsin.com/api/partner/v1/disputes/cm_ornek_talep/respond" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "action": "accept", "remedy": "refund" }'

Late delivery dispute: refund part of the amount

curl -X POST "https://api.supergelsin.com/api/partner/v1/disputes/cm_ornek_talep/respond" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "action": "accept", "remedy": "refund", "acceptedAmount": 120.5 }'

Contest

curl -X POST "https://api.supergelsin.com/api/partner/v1/disputes/cm_ornek_talep/respond" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "action": "contest", "contestReason": "product_correct" }'

A dispute is answered as a whole with action or per item with items; sending both, or neither, returns 400 invalid_body. Acceptance starts a refund. The upper limit and the calculation of the refund amount are done on the platform; if the limit is exceeded 409 refund_cap_exceeded is returned. A dispute whose response time has passed, or which has already been answered, returns 409 dispute_closed. The action appears in the audit trail with the X-Integrator and X-Operator values.

Alan	Tip	Açıklama
`action`	enum	`accept · contest`
`remedy`	enum	Only `refund`: the amount is returned to the customer. Any other value on acceptance returns `400`. A missing or `null` value counts as `refund`; the field is ignored when contesting.
`acceptedAmount`	number	For a late delivery dispute, when accepting the whole dispute: the amount to refund, greater than 0 and not greater than the dispute amount. If omitted, the full dispute amount is refunded. `null` or a string returns `400`.
`contestReason`	enum	`not_my_fault · product_correct · other`. Required when `action` is `contest`; if missing, `400` is returned.

Response (200)

Alan	Tip	Açıklama
`stage`	string	The stage of the dispute after the response.
`mode`	string	The kind of response (for example partial on a partial acceptance).
`refundedAmount`	number	The amount refunded immediately.
`refundPath`	enum	Through which path the refund was made: `online` or `door` (the same vocabulary as `payment.channel`).

Evidence images cannot be sent through this surface; evidence is uploaded from the business console. A contest without evidence is still valid, but leaves nothing for the platform review to weigh in the business's favour.

Item-level response

When a dispute contains several items you can answer each one separately (at most 200 items). When items is given, the decision is derived from the items: all accepted means the dispute is accepted, none accepted means it is contested, a mix means partial: the amount of the accepted items is refunded immediately and the rest goes to platform review. For a cold_food dispute the rest does not go to platform review; the dispute is closed. An item missing from the decision counts as contested; there is no silent acceptance. Sending acceptedAmount together with an item-level response returns 400.

Request

curl -X POST "https://api.supergelsin.com/api/partner/v1/disputes/cm_ornek_talep/respond" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "items": [ { "id": "cm_ornek_kalem_1", "action": "accept" }, { "id": "cm_ornek_kalem_2", "action": "contest" } ], "contestReason": "product_correct" }'