Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HelenaLM32/ECHO/llms.txt

Use this file to discover all available pages before exploring further.

The disputes API gives buyers and sellers a structured way to raise and resolve problems with an order on ECHO. Any authenticated party to an order can open a dispute, exchange messages with the other party, and track status. Admins can view all disputes platform-wide, contribute messages, and record resolutions to close disputes.
The base URL for all endpoints on a local development server is http://localhost:8084. Replace this with your deployed API URL in production.

​
Create dispute

POST /disputes
Opens a new dispute for an existing order. The authenticated user must be a party to the referenced order.

​
Authentication

Requires a valid JWT token.

​
Request body

​
orderId
number
required
The ID of the order the dispute relates to.
​
reason
string
required
A description of the issue. Maximum 500 characters.

​
Example

curl -X POST http://localhost:8084/disputes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"orderId":12,"reason":"Deliverable did not match the agreed specifications"}'

​
Response fields

​
id
number
required
Unique identifier for the newly created dispute.
​
orderId
number
required
The ID of the order under dispute.
​
createdByUserId
number
required
The ID of the user who opened the dispute.
​
createdByUsername
string
required
The username of the user who opened the dispute.
​
reason
string
required
The stated reason for the dispute.
​
status
string
required
Always OPEN on a newly created dispute.
​
resolution
string
The recorded resolution. null until the dispute is closed by an admin.
​
createdAt
string
required
ISO 8601 timestamp of when the dispute was opened.
​
closedAt
string
ISO 8601 timestamp of when the dispute was closed. null while the dispute is open.

​
Error codes

StatusMeaning
400Missing required fields or reason exceeds 500 characters.
403You are not a party to the referenced order.
404No order exists with the given orderId.

​
Get dispute by ID

GET /disputes/{disputeId}
Returns a single dispute by its numeric ID. You must be the user who created the dispute or hold the ADMIN role.

​
Authentication

Requires a valid JWT token.

​
Path parameters

​
disputeId
number
required
The numeric ID of the dispute to retrieve.

​
Example

curl -X GET http://localhost:8084/disputes/5 \
  -H "Authorization: Bearer <token>"

​
Response fields

​
id
number
required
Unique identifier for the dispute.
​
orderId
number
required
The ID of the order under dispute.
​
createdByUserId
number
required
The ID of the user who opened the dispute.
​
createdByUsername
string
required
The username of the user who opened the dispute.
​
reason
string
required
The stated reason for the dispute.
​
status
string
required
Current dispute status (e.g., OPEN, CLOSED).
​
resolution
string
The recorded resolution, if the dispute has been closed.
​
createdAt
string
required
ISO 8601 timestamp of when the dispute was opened.
​
closedAt
string
ISO 8601 timestamp of when the dispute was closed, if applicable.

​
Error codes

StatusMeaning
403You did not create this dispute and do not hold the ADMIN role.
404No dispute exists with the given ID.

​
Get dispute for order

GET /disputes/order/{orderId}
Returns the dispute associated with a specific order.

​
Authentication

Requires a valid JWT token.

​
Path parameters

​
orderId
number
required
The numeric ID of the order whose dispute to retrieve.

​
Example

curl -X GET http://localhost:8084/disputes/order/12 \
  -H "Authorization: Bearer <token>"

​
Error codes

StatusMeaning
404No dispute exists for the given order.

​
Get own disputes

GET /disputes/user/my-disputes
Returns all disputes created by the authenticated user.

​
Authentication

Requires a valid JWT token.

​
Example

curl -X GET http://localhost:8084/disputes/user/my-disputes \
  -H "Authorization: Bearer <token>"

​
Get open disputes

GET /disputes/open
Returns open disputes. Admins receive all open disputes on the platform; non-admin users receive only their own open disputes.

​
Authentication

Requires a valid JWT token.

​
Example

curl -X GET http://localhost:8084/disputes/open \
  -H "Authorization: Bearer <token>"

​
Get all disputes

GET /disputes
Returns disputes. Admins receive all disputes on the platform; non-admin users receive only their own disputes.

​
Authentication

Requires a valid JWT token.

​
Example

curl -X GET http://localhost:8084/disputes \
  -H "Authorization: Bearer <token>"

​
Add message to dispute

POST /disputes/{disputeId}/messages
Adds a message to the dispute thread. Both parties to the dispute and admins can post messages.

​
Authentication

Requires a valid JWT token.

​
Path parameters

​
disputeId
number
required
The numeric ID of the dispute to add a message to.

​
Request body

​
message
string
required
The message text to add to the dispute thread.

​
Example

curl -X POST http://localhost:8084/disputes/5/messages \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"message":"I have attached the original brief for reference."}'

​
Response fields

​
id
number
required
Unique identifier for the message.
​
disputeId
number
required
The ID of the dispute this message belongs to.
​
userId
number
required
The ID of the user who sent the message.
​
username
string
required
The username of the message sender.
​
message
string
required
The message text.
​
createdAt
string
required
ISO 8601 timestamp of when the message was sent.

​
Error codes

StatusMeaning
403You are not a party to this dispute.
404No dispute exists with the given ID.

Build docs developers (and LLMs) love

Get started for freeTalk to us