Seller API Documentation

Programmatically manage your MarketFlow store, products, inventory, and orders.

The MarketFlow Seller API allows developers to integrate directly with the marketplace ecosystem. All requests must be made over HTTPS. Calls made over plain HTTP will fail. API responses are returned in JSON format.

Base URL: https://api.marketflow.com/v1

Authentication

Access the Seller API using your unique API Key. Include it in the Authorization header of every request.

Example Request

curl -X GET https://api.marketflow.com/v1/products \n  -H "Authorization: Bearer mf_live_8xK9p2LqR4vT7wN1" \n  -H "Content-Type: application/json"

Security Notice: Never expose your live API keys in client-side code or public repositories. Use environment variables to store them securely.

Rate Limits

To ensure platform stability, API requests are limited based on your seller tier:

Free Tier: 60 requests per minute
Pro Tier: 300 requests per minute
Enterprise: Custom limits (contact sales)

Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests left in window
X-RateLimit-Reset: Unix timestamp when limit resets

API Endpoints

GET /products

Retrieves a paginated list of products belonging to your seller account. Supports filtering by status, category, and date range.

Parameter	Type	Description
`status`	string	Optional Filter by status: `active`, `draft`, `archived`
`limit`	integer	Optional Number of items per page (max 100, default 20)
`cursor`	string	Optional Pagination cursor from previous response

Response (200 OK)

{
  "data": [
    {
      "id": "prod_8f3a2b9c",
      "title": "Wireless Noise-Cancelling Headphones",
      "price": { "amount": 12999, "currency": "USD" },
      "inventory": { "quantity": 45, "status": "in_stock" },
      "created_at": "2024-11-15T08:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJwYWdlIjogMn0=",
    "has_more": true
  }
}

POST /products

Creates a new product listing in your store. All prices are submitted in cents to avoid floating-point precision issues.

Parameter	Type	Description
`title`	string	Required Product title (max 150 chars)
`price_amount`	integer	Required Price in smallest currency unit (e.g., 12999 = $129.99)
`currency`	string	Required ISO 4217 currency code (e.g., "USD")
`inventory_quantity`	integer	Required Initial stock count
`category_id`	string	Optional MarketFlow category identifier

Request Body

{
  "title": "Artisan Ceramic Mug Set",
  "price_amount": 3499,
  "currency": "USD",
  "inventory_quantity": 120,
  "category_id": "home_kitchen",
  "images": ["https://cdn.marketflow.com/img/mug-1.jpg"]
}

PUT /products/{product_id}/inventory

Updates the stock quantity for a specific product. Use this to sync with external ERP or warehouse management systems.

Response (200 OK)

{
  "id": "prod_8f3a2b9c",
  "inventory": {
    "quantity": 38,
    "status": "in_stock",
    "updated_at": "2025-01-20T14:22:00Z"
  }
}

POST /orders/{order_id}/fulfill

Marks an order as shipped. Automatically notifies the buyer and updates order status in the dashboard.

Parameter	Type	Description
`tracking_number`	string	Required Carrier tracking ID
`carrier`	string	Optional e.g., "USPS", "DHL", "FedEx"

Webhooks

Subscribe to real-time events like new orders, payment confirmations, and inventory alerts. Configure your webhook endpoints in the Seller Dashboard.

order.created New order placed

payment.paid Payment confirmed

inventory.low Stock below threshold

order.refunded Buyer initiated refund

All webhook payloads are signed using HMAC-SHA256. Verify the X-MarketFlow-Signature header before processing.

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses include a detailed error object.

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Rate Limited

500 Server Error

Error Response

{
  "error": {
    "code": "invalid_parameter",
    "message": "Price amount must be a positive integer.",
    "field": "price_amount"
  }
}

Official SDKs

Speed up development with our maintained libraries:

Node.js / JavaScript: npm install @marketflow/seller-sdk
Python: pip install marketflow-seller
PHP: composer require marketflow/seller-api

Source code and examples are available on our GitHub organization.

API Support

Having trouble with an integration? Our developer support team is available via the dashboard chat or at api-support@marketflow.com. Include your API key prefix and request logs when reaching out.