MarketFlow API Documentation

Authentication

All API requests require authentication via Bearer tokens. Include your API key in the Authorization header for every request.

HTTP Header

Authorization: Bearer mf_live_sk_4eC39HqLyjWDarjtT1zdp7dc

Generate your keys in the Developer Dashboard. Use mf_test_ prefixes for sandbox environments and mf_live_ for production.

Products API

Manage product listings, inventory, pricing, and metadata.

GET /v1/products

Retrieve a paginated list of products. Supports filtering by category, price range, and status.

Parameter	Type	Required	Description
`page`	integer	Optional	Page number (default: 1)
`limit`	integer	Optional	Items per page (max: 100)
`status`	string	Optional	Filter: `active`, `draft`, `archived`

cURL

curl -X GET "https://api.marketflow.com/v1/products?page=1&limit=20&status=active" \
  -H "Authorization: Bearer mf_live_sk_4eC39HqLyjWDarjtT1zdp7dc"

JSON

{
  "data: [
    {
      "id: "prod_8f7g6h5j4k3l2m1n",
      "name: "Wireless Noise-Canceling Headphones",
      "price: 149.99,
      "currency: "USD,
      "inventory: 248,
      "status: "active
    }
  ],
  "meta: {
    "total: 1542,
    "page: 1,
    "limit: 20
  }
}

POST /v1/products

Create a new product listing in the marketplace.

Parameter	Type	Required	Description
`name`	string	Required	Product title (max 120 chars)
`price`	number	Required	Price in minor units (e.g., 14999 = $149.99)
`category`	string	Required	Category ID from catalog
`description`	string	Optional	HTML or plain text description

Orders API

Process purchases, manage fulfillment, and track customer orders.

POST /v1/orders

Create a new order and initiate checkout/payment flow.

JSON Body

{
  "items: [
    {
      "product_id: "prod_8f7g6h5j4k3l2m1n,
      "quantity: 2
    }
  ],
  "shipping: {
    "address: "123 Market St, San Francisco, CA 94103",
    "method: "express
  },
  "customer: {
    "email: "buyer@example.com,
    "name: "Alex Johnson
  }
}

Webhooks

Receive real-time event notifications for order updates, inventory changes, and payment statuses. Configure endpoints in your dashboard.

Webhook Payload Example

{
  "event: "order.completed,
  "id: "evt_9x8y7z6w5v4u3t2s1r,
  "timestamp: "2024-11-15T14:32:00Z,
  "data: {
    "order_id: "ord_abc123xyz,
    "total: 299.98,
    "status: "fulfilled
  }
}

Security: All webhook requests include a X-MarketFlow-Signature header. Verify payloads using HMAC-SHA256 with your webhook secret.

HTTP Status Codes

200

OK

Request succeeded normally.

201

Created

Resource successfully created.

400

Bad Request

Invalid parameters or malformed JSON.

401

Unauthorized

Missing or invalid API key.

429

Too Many Requests

Rate limit exceeded. Retry after delay.

500

Internal Server Error

Something went wrong on our end.

MarketFlow API Reference