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 orders API manages the complete transaction flow on ECHO: creating an order for a listed item, tracking its progress through status changes, and communicating between buyer and seller via order messages. All order endpoints require a valid JWT token. A user may only access orders in which they are either the buyer or the seller, unless they hold the ADMIN role.
The base URL for all endpoints on a local development server is http://localhost:8084. Replace this with your deployed API URL in production.

​
Get current user’s orders

GET /orders
Returns all orders associated with the authenticated user, whether as buyer or seller.

​
Authentication

Requires a valid JWT token.

​
Example

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

​
Response fields

​
id
number
required
Unique identifier for the order.
​
buyerId
number
required
The ID of the user who placed the order.
​
itemId
number
required
The ID of the marketplace item being purchased.
​
finalPrice
number
required
The agreed price for the order.
​
status
string
required
Current order status. Starts as PENDING on creation.

​
Get order by ID

GET /orders/{id}
Returns a single order by its numeric ID. You must be the buyer or seller on the order, or hold the ADMIN role.

​
Authentication

Requires a valid JWT token.

​
Path parameters

​
id
number
required
The numeric ID of the order to retrieve.

​
Example

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

​
Response fields

​
id
number
required
Unique identifier for the order.
​
buyerId
number
required
The ID of the buyer.
​
itemId
number
required
The ID of the purchased item.
​
finalPrice
number
required
The agreed price for the order.
​
status
string
required
Current order status.

​
Error codes

StatusMeaning
403You are not the buyer or seller on this order.
404No order exists with the given ID.

​
Create order

POST /orders
Places a new order for a marketplace item. The order is created with a status of PENDING.

​
Authentication

Requires a valid JWT token.

​
Request body

​
itemId
number
required
The ID of the item to order.
​
finalPrice
number
required
The agreed price for the transaction.

​
Example

curl -X POST http://localhost:8084/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"itemId":5,"finalPrice":150.00}'

​
Response fields

​
id
number
required
The newly created order’s ID.
​
buyerId
number
required
The ID of the authenticated user who placed the order.
​
itemId
number
required
The ID of the ordered item.
​
finalPrice
number
required
The price recorded for this order.
​
status
string
required
Always PENDING on a newly created order.

​
Error codes

StatusMeaning
400Missing or invalid request body fields.
404No item exists with the given itemId.

​
Update order status

PATCH /orders/{id}/status?status=...
Advances or changes the status of an existing order. You must be the buyer or seller on the order.

​
Authentication

Requires a valid JWT token.

​
Path parameters

​
id
number
required
The numeric ID of the order to update.

​
Query parameters

​
status
string
required
The new status value to set on the order (e.g., COMPLETED, CANCELLED).

​
Example

curl -X PATCH "http://localhost:8084/orders/12/status?status=COMPLETED" \
  -H "Authorization: Bearer <token>"

​
Error codes

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

​
Order messages

Buyers and sellers can exchange messages within an order using the nested /orders/{orderId}/messages endpoints. All requests require authentication.

​
Get messages for an order

GET /orders/{orderId}/messages
Returns all messages exchanged on the given order. You must be a party to the order.
​
orderId
number
required
The numeric ID of the order whose messages to retrieve.
curl -X GET http://localhost:8084/orders/12/messages \
  -H "Authorization: Bearer <token>"

​
Send a message

POST /orders/{orderId}/messages
Sends a new message on the given order thread.
​
orderId
number
required
The numeric ID of the order to message on.
​
content
string
required
The message text to send.
curl -X POST http://localhost:8084/orders/12/messages \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"content":"Hi, the files are ready for review."}'
​
id
number
required
Unique identifier for the message.
​
orderId
number
required
The ID of the order this message belongs to.
​
senderId
number
required
The ID of the user who sent the message.
​
content
string
required
The message text.
​
sentAt
string
required
ISO 8601 timestamp of when the message was sent.

Build docs developers (and LLMs) love

Get started for freeTalk to us