Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Order negotiation platform

Negotiate post-delivery issues with customers — cancellations, returns, refunds through mediated proposals.

Quickstart

Consume HANDSHAKE_DISPUTE via polling or webhook
Respond with /accept, /reject, or /alternative before expiresAt
Process HANDSHAKE_SETTLEMENT confirming resolution

Requirements:

You must respond to every dispute — no response activates timeoutAction automatically
One response per disputeId (not reusable)
Analyze each negotiation individually

Scenarios

After delivery: Full or partial cancellation request
During preparation: Full cancellation request
Late delivery: Cancellation or time extension request
Reshipment: Missing items (experimental)

See implementation guide for workflow examples.

Entities and attributes

HandshakeDispute

Entity sent in HANDSHAKE_DISPUTE event containing negotiation, requested action, evidence, deadline, and automatic timeout action. Includes DisputeAlternative for refunds and Item/GarnishItem for partial cancellations.Identification and context

Attribute	Description	Type	Required
id	Negotiation ID	`uuid`	✓
parentDisputeId	Original negotiation ID (if counteroffer)	`uuid`
createdAt	Creation timestamp	`DateTime`	✓
message	Customer justification	`String`	✓

Negotiation type

Attribute	Description	Type	Required
action	Negotiation purpose	`String`	✓
handshakeType	Negotiation type	`String`	✓
handshakeGroup	Classification	`String`	✓

Valid values for action:

CANCELLATION — Full cancellation
PARTIAL_CANCELLATION — Partial cancellation
PROPOSED_AMOUNT_REFUND — Proposed refund
PROPOSED_ADDITIONAL_TIME — Proposed time extension
VOID — No action

Valid values for handshakeType:

AFTER_DELIVERY — Cancellation after customer receives
DELAY — Cancellation due to late delivery
PREPARATION_TIME — Cancellation during preparation
AFTER_DELIVERY_PARTIALLY — Partial cancellation after delivery

Deadline and automation

Attribute	Description	Type	Required
expiresAt	Response deadline	`DateTime`	✓
timeoutAction	Action if no response	`String`	✓

Valid values for timeoutAction:

ACCEPT_CANCELLATION — Auto-accept cancellation
REJECT_CANCELLATION — Auto-reject cancellation
VOID — No automatic action

Negotiation content

Attribute	Description	Type
alternatives	Available response options	`List of DisputeAlternative`
metadata.item	Items for partial cancellation	`List of Item`
metadata.garnishItems	Sub-items (add-ons)	`List of GarnishItem`
metadata.evidences	Photos/media from customer	`List of Media`
metadata.acceptCancellationReasons	Valid reasons to accept	`List of String`

HandshakeSettlement

Entity sent in HANDSHAKE_SETTLEMENT event containing resolution status and reason. Includes SelectedDisputeAlternative for accepted counteroffers.

Attribute	Description	Type	Required
id	Settlement ID	`uuid`	✓
disputeId	Resolved negotiation ID	`uuid`	✓
status	Final result	`String`	✓
reason	Rejection justification	`String`
selectedDisputeAlternative	Counteroffer (if status = ALTERNATIVE_REPLIED)	`SelectedDisputeAlternative`

Valid values for status:

ACCEPTED — Negotiation accepted
REJECTED — Negotiation rejected
EXPIRED — No response until deadline
ALTERNATIVE_REPLIED — Counteroffer sent and accepted

DisputeAlternative

Alternative resolution options accompanying HandshakeDispute. Valid values for type: REFUND, BENEFIT, ADDITIONAL_TIME.

Attribute	Description	Type	Required
id	Alternative ID	`uuid`	✓
type	Resolution type	`String`	✓
metadata.maxAmount	Maximum amount (REFUND/BENEFIT)	`Amount`	Cond
metadata.allowedsAdditionalTimeInMinutes	Time extension options (minutes)	`List of Int`	Cond
metadata.allowedsAdditionalTimeReasons	Delay reasons	`List of String`	Cond

SelectedDisputeAlternative

Accepted counteroffer accompanying HandshakeSettlement. Valid values for type: REFUND, BENEFIT, ADDITIONAL_TIME.

Attribute	Description	Type	Required
id	Alternative ID	`uuid`	✓
type	Resolution type	`String`	✓
metadata.amount	Amount (REFUND/BENEFIT)	`Amount`	Cond
metadata.additionalTimeInMinutes	Time extension	`int`	Cond
metadata.reason	Delay reason	`String`	Cond

Media

Photo sent by customer.

Attribute	Type
url	`String` (requires authentication)
contentType	`String` (MIME type)

Item

Item for partial cancellation.

Attribute	Type
id	`uuid`
uniqueId	`uuid`
externalCode	`String`
quantity	`int`
index	`int`
amount	`Amount`
reason	`String`

GarnishItem

Sub-item (add-on) for partial cancellation.

Attribute	Type
id	`uuid`
parentUniqueId	`uuid`
externalCode	`String`
quantity	`int`
index	`int`
amount	`Amount`
reason	`String`

Amount

Monetary value per ISO 4217.

Attribute	Description	Type
value	Amount without decimals ($1.00 = 100)	`String`
currency	Currency code (ex: USD)	`String`

Constants

`handshakeType`

Value	Description
`AFTER_DELIVERY`	Cancellation after customer received
`DELAY`	Cancellation for late delivery
`PREPARATION_TIME`	Cancellation during preparation
`AFTER_DELIVERY_PARTIALLY`	Partial cancellation after delivery

`handshakeGroup`

Value	Description
`CUSTOMER_ORDER_SUPPORT`	Customer-initiated negotiation

`action`

Value	Description
`CANCELLATION`	Full cancellation
`PARTIAL_CANCELLATION`	Partial cancellation
`PROPOSED_AMOUNT_REFUND`	Cancellation with refund option

`timeoutAction`

Value	Action
`ACCEPT_CANCELLATION`	Cancel automatically
`REJECT_CANCELLATION`	Reject cancellation automatically
`VOID`	No automatic action

`status`

Value	Description
`ACCEPTED`	Negotiation accepted
`REJECTED`	Negotiation rejected
`EXPIRED`	No response before deadline
`ALTERNATIVE_REPLIED`	Counteroffer sent and accepted

`type`

Value	Description
`REFUND`	Money refund
`BENEFIT`	Credit/benefit
`ADDITIONAL_TIME`	Time extension

`negotiationReasons`

Reasons for negotiation decisions. Use in request bodies when required.

Reason	Context
`HIGH_STORE_DEMAND`	Store at capacity
`UNKNOWN_ISSUE`	Unspecified issue
`CUSTOMER_SATISFACTION`	Customer service
`INVENTORY_CHECK`	Availability verification
`SYSTEM_ISSUE`	Technical issue
`WRONG_ORDER`	Incorrect order
`PRODUCT_QUALITY`	Quality concern
`LATE_DELIVERY`	Late delivery
`CUSTOMER_REQUEST`	Customer request

API Endpoints

Accept proposal

POST https://merchant-api.ifood.com.br/order/v1.0/disputes/{disputeId}/acceptParameters:

Name	Type	Description
`disputeId`	`uuid`	Dispute ID (URL)
`reason`	`string`	Reason from `metadata.acceptCancellationReasons`
`detailReason`	`string`	Description (250 chars max)

Request example:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/dispute_001/accept" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "CUSTOMER_SATISFACTION", "detailReason": "Refund for courtesy"}'

Response (201 Created):

{
  "id": "settlement_001",
  "status": "ACCEPTED",
  "disputeId": "dispute_001",
  "createdAt": "2024-04-25T18:05:00Z"
}

Common errors:

Status	Code	Reason
401	-	Invalid token
404	`DISPUTE_NOT_FOUND`	Dispute not found
422	`DISPUTE_ALREADY_ANSWERED`	Already answered
400	`INVALID_REASON`	Invalid reason

Reject proposal

POST https://merchant-api.ifood.com.br/order/v1.0/disputes/{disputeId}/rejectParameters:

Name	Type	Description
`disputeId`	`uuid`	Dispute ID (URL)
`reason`	`string`	Reason from `negotiationReasons`

Request example:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/dispute_002/reject" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "INVENTORY_CHECK"}'

Response (201 Created):

{
  "id": "settlement_002",
  "status": "REJECTED",
  "disputeId": "dispute_002",
  "createdAt": "2024-04-25T18:08:00Z"
}

Common errors:

Status	Code	Reason
401	-	Invalid token
404	`DISPUTE_NOT_FOUND`	Dispute not found
422	`DISPUTE_ALREADY_ANSWERED`	Already answered
400	`INVALID_REASON`	Invalid reason

Make counteroffer

POST https://merchant-api.ifood.com.br/order/v1.0/disputes/{disputeId}/alternativeParameters:

Name	Type	Description
`disputeId`	`uuid`	Dispute ID (URL)
`type`	`string`	`REFUND`, `BENEFIT` or `ADDITIONAL_TIME`
`metadata.amount`	`Amount`	Amount (REFUND/BENEFIT)
`metadata.additionalTimeInMinutes`	`int`	Minutes (ADDITIONAL_TIME)
`metadata.reason`	`string`	Delay reason (ADDITIONAL_TIME)

Examples by type:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/dispute_001/alternative" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "REFUND",
    "metadata": {
      "amount": {
        "value": "5000",
        "currency": "BRL"
      }
    }
  }'

Response (201 Created):

{
  "id": "settlement_003",
  "status": "ALTERNATIVE_REPLIED",
  "disputeId": "dispute_003",
  "selectedDisputeAlternative": {
    "id": "alt_001",
    "type": "ADDITIONAL_TIME",
    "metadata": {
      "additionalTimeInMinutes": 30,
      "reason": "HIGH_STORE_DEMAND"
    }
  },
  "createdAt": "2024-04-25T18:12:00Z"
}

Common errors:

Status	Code	Reason
401	-	Invalid token
404	`DISPUTE_NOT_FOUND`	Dispute not found
422	`DISPUTE_ALREADY_ANSWERED`	Already answered
400	`INVALID_AMOUNT`	Amount out of range

Negotiation matrix

Scenario	handshakeType	action	Responses
Full after delivery	AFTER_DELIVERY	CANCELLATION	Accept / Reject / REFUND
Full during preparation	PREPARATION_TIME	CANCELLATION	Accept / Reject
Full (late)	DELAY	CANCELLATION	Accept / Reject / ADDITIONAL_TIME
Partial after delivery	AFTER_DELIVERY_PARTIALLY	PARTIAL_CANCELLATION	Accept / Reject / REFUND

See implementation guide for complete examples.

Timeout

If no response before expiresAt, timeoutAction executes:

ACCEPT_CANCELLATION: Order canceled
REJECT_CANCELLATION: Cancellation rejected
VOID: No action

Generates HANDSHAKE_SETTLEMENT with status: EXPIRED.

Events Reference

HANDSHAKE_DISPUTE

Published when customer initiates eligible negotiation (cancellation meeting criteria).Event structure

Attribute	Type
id	`string`
code	`string` (always "HSD")
fullCode	`string` (always "HANDSHAKE_DISPUTE")
orderId	`uuid`
merchantId	`uuid`
createdAt	`DateTime`
metadata	`HandshakeDispute`

Examples by scenario:

{
  "id": "evt_001",
  "code": "HSD",
  "fullCode": "HANDSHAKE_DISPUTE",
  "orderId": "ord_12345",
  "merchantId": "merchant_001",
  "createdAt": "2024-04-25T18:02:46.921Z",
  "metadata": {
    "id": "dispute_001",
    "action": "CANCELLATION",
    "handshakeType": "AFTER_DELIVERY",
    "handshakeGroup": "CUSTOMER_ORDER_SUPPORT",
    "message": "Food arrived cold",
    "expiresAt": "2024-04-25T18:09:46Z",
    "timeoutAction": "REJECT_CANCELLATION",
    "createdAt": "2024-04-25T18:02:46Z",
    "alternatives": [
      {
        "id": "alt_001",
        "type": "REFUND",
        "metadata": {
          "maxAmount": {
            "currency": "BRL",
            "value": "5000"
          }
        }
      }
    ],
    "acceptCancellationReasons": ["PRODUCT_QUALITY", "CUSTOMER_SATISFACTION"],
    "evidences": [
      {
        "url": "https://merchant-api.ifood.com.br/orders/ord_12345/evidences/abc123",
        "contentType": "image/jpeg"
      }
    ]
  }
}

HANDSHAKE_SETTLEMENT

Published when negotiation resolves (accepted, rejected, counteroffer, or timeout).Event structure

Attribute	Type
id	`string`
code	`string` (always "HSS")
fullCode	`string` (always "HANDSHAKE_SETTLEMENT")
orderId	`uuid`
merchantId	`uuid`
createdAt	`DateTime`
metadata	`HandshakeSettlement`

Examples by outcome:

{
  "id": "evt_settlement_001",
  "code": "HSS",
  "fullCode": "HANDSHAKE_SETTLEMENT",
  "orderId": "ord_12345",
  "merchantId": "merchant_001",
  "createdAt": "2024-04-25T18:05:00Z",
  "metadata": {
    "id": "settlement_001",
    "disputeId": "dispute_001",
    "status": "ACCEPTED",
    "reason": "CUSTOMER_SATISFACTION",
    "createdAt": "2024-04-25T18:05:00Z"
  }
}

Next steps

Implementation guide — Workflow examples
Events polling — Configuration
Order workflow — Order states

Was this page helpful?

Rate your experience in the new Developer portal: