MarketFlow API Documentation

Integrate with the world's fastest-growing digital marketplace. Build sellers dashboards, automated order routing, or custom checkout experiences using our RESTful API.

Note: This API is currently in v1 stable. Breaking changes will be communicated 90 days in advance via email and webhook events.

All API requests return JSON responses and use standard HTTP status codes. Authentication is handled via Bearer tokens included in the Authorization header.

Base URL

All API requests should be made to:

https://api.marketflow.com/v1

For testing, use the sandbox environment:

https://sandbox-api.marketflow.com/v1

Authentication

MarketFlow uses API keys for authentication. Obtain your keys from the Developer Dashboard under Settings → API Keys.

Include your secret key in the Authorization header as a Bearer token:

Authorization: Bearer mk_live_sk_7f9a2c1d8e4b6f3a5g0h9j

Security Warning: Never expose your secret key in client-side code, public repositories, or browser extensions. Use environment variables or secure vaults.

Rate Limiting

API requests are limited to 1,000 requests per minute per API key. Rate limit headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When exceeded, the API returns 429 Too Many Requests with a retry-after header.

Endpoints

GET /products

Retrieve a paginated list of products matching your query parameters.

Query Parameters

Parameter	Type	Required	Description
`category`	string	No	Filter by category slug (e.g., electronics, fashion)
`min_price`	number	No	Minimum price in cents
`max_price`	number	No	Maximum price in cents
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Results per page (max: 50)

Example Response

{ "data": [ { "id": "prod_8xK2mN9pL4", "name": "Wireless Noise-Cancelling Headphones", "category": "electronics", "price": 12999, "currency": "usd", "stock": 142, "seller_id": "usr_3jF8kQ2wR7", "created_at": "2024-11-15T08:30:00Z" } ], "meta": { "page": 1, "limit": 50, "total": 1240 } }

POST /orders

Create a new order from an existing shopping cart or product selection.

Request Body (JSON)

{ "buyer_id": "usr_9mX4vB1nK2", "items": [ { "product_id": "prod_8xK2mN9pL4", "quantity": 2 } ], "shipping_address": { "street": "123 Market St", "city": "San Francisco", "state": "CA", "zip": "94103", "country": "US" }, "payment_method": "pm_card_visa_4242" }

Example Response

{ "id": "ord_2pL9mK4nX8", "status": "pending_payment", "total": 26598, "currency": "usd", "created_at": "2025-01-20T14:22:10Z" }

GET /users/:id

Fetch public or authenticated seller/buyer profile details.

Example Response

{ "id": "usr_3jF8kQ2wR7", "username": "techstore_official", "type": "seller", "verified": true, "rating": 4.9, "total_sales": 12840, "joined_at": "2022-03-10T00:00:00Z" }

Error Codes

MarketFlow uses standard HTTP status codes and returns structured error JSON:

Code	Message	Meaning
400	Bad Request	Invalid parameters or malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for this resource
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal MarketFlow error (retry after 5s)

Error Response Format

{ "error": { "code": "invalid_api_key", "message": "The provided API key is expired or revoked.", "status": 401 } }

Webhooks

Subscribe to real-time events for orders, payments, and inventory changes. Configure your endpoint URLs in the Developer Dashboard.

Supported Events

order.created
order.paid
order.shipped
product.stock_low
payment.payout_completed

Webhook payloads include a X-Webhook-Signature header for verification using your secret.