v1 · stable

MarketSquare API

RESTful endpoints with JSON payloads, cursor-based pagination, and idempotency keys on writes. Rate limits: 60 req/min per token, 600 req/min per seller account.

Authentication

POST/v1/auth/session

Create a session token

Request

{ "email": "ava@marketsquare.co", "provider": "magic_link" }

Response 200

{ "token": "sess_a1b2c3", "expires_in": 3600 }

DELETE/v1/auth/session

Revoke the current session

Response 200

{ "revoked": true }

Products

GET/v1/products

List products with filters, sort, and pagination

Response 200

{ "data": [{ "id": "p1", "title": "Handthrown Terracotta Mug", "price": 28, "seller": "Elena Marín" }], "page": 1, "total": 132 }

POST/v1/products

Create a product (seller)

Request

{ "title": "Ceramic Bowl", "price": 42, "stock": 12 }

Response 200

{ "id": "p_new", "status": "active" }

PATCH/v1/products/:id

Update product

Request

{ "price": 45 }

Response 200

{ "ok": true }

DELETE/v1/products/:id

Delete product

Response 200

{ "deleted": true }

Orders

POST/v1/orders

Create an order

Request

{ "items": [{ "productId": "p1", "qty": 1 }], "address": "..." }

Response 200

{ "id": "o_1032", "status": "pending", "total": 34 }

GET/v1/orders/:id

Fetch order

Response 200

{ "id": "o_1032", "status": "shipped" }

POST/v1/orders/:id/status

Update order status (seller)

Request

{ "status": "shipped" }

Response 200

{ "ok": true }

Messaging

GET/v1/threads

List threads for the current user

Response 200

{ "data": [{ "id": "t1", "subject": "About the mug" }] }

POST/v1/threads/:id/messages

Send a message

Request

{ "text": "Yes, still in stock." }

Response 200

{ "id": "m_x", "at": 1721539200000 }

Admin

POST/v1/admin/sellers/:id/verify

Mark seller verified

Response 200

{ "verified": true }

POST/v1/admin/disputes/:id/resolve

Resolve dispute

Request

{ "resolution": "refund" }

Response 200

{ "status": "resolved" }