API Documentation

Integrate your store data with external systems using our REST API

Base URL: https://api-marketplace.devskin.com/api/v1

Authentication

All API requests must be authenticated using an API key sent via the X-API-Key header. API keys are scoped to a single store and provide read-only access to your store's metrics and data.

Creating an API Key

To create an API key, go to your store's Settings page in the dashboard and navigate to the API Keys tab. Click "Create New Key", give it a descriptive name, and the key will be displayed once. Copy it immediately — keys are stored as SHA-256 hashes and cannot be retrieved later.

Important: API keys are shown only once at creation time. They are stored as irreversible hashes on our servers. If you lose a key, you must revoke it and create a new one.

Using the Key

Include your API key in every request header:

HTTP Header 
X-API-Key: your_api_key_here
Rate Limits API keys are rate-limited to 100 requests per minute. If you exceed this limit, you will receive a 429 Too Many Requests response.

Endpoints

All endpoints return JSON responses with a consistent structure. Successful responses include { "success": true, "data": {...} }. Error responses include { "success": false, "error": "message" }.

GET /api/v1/orders List orders (paginated, filterable)

Query Parameters

Parameter Type Description
page integer Page number (default: 1) optional
limit integer Items per page, max 100 (default: 20) optional
status string Filter by status: pending, paid, shipped, completed, cancelled optional
date_from string Start date (YYYY-MM-DD) optional
date_to string End date (YYYY-MM-DD) optional

Example Request

cURL 
curl -X GET "https://api-marketplace.devskin.com/api/v1/orders?page=1&limit=10&status=paid" \
  -H "X-API-Key: your_api_key_here"

Example Response

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1234,
        "order_number": "ORD-2026-001234",
        "status": "paid",
        "total": 199.90,
        "customer_name": "John Doe",
        "customer_email": "[email protected]",
        "created_at": "2026-02-10T14:30:00.000Z"
      }
    ],
    "total": 156,
    "page": 1,
    "limit": 10
  }
}
GET /api/v1/orders/:id Get order detail

Path Parameters

Parameter Type Description
id integer Order ID required

Example Request

cURL 
curl -X GET "https://api-marketplace.devskin.com/api/v1/orders/1234" \
  -H "X-API-Key: your_api_key_here"

Example Response

JSON 
{
  "success": true,
  "data": {
    "order": {
      "id": 1234,
      "order_number": "ORD-2026-001234",
      "status": "paid",
      "total": 199.90,
      "subtotal": 189.90,
      "shipping_cost": 10.00,
      "discount": 0,
      "customer_name": "John Doe",
      "customer_email": "[email protected]",
      "items": [
        {
          "product_id": 42,
          "name": "Premium Widget",
          "quantity": 2,
          "price": 94.95
        }
      ],
      "shipping_address": {
        "street": "123 Main St",
        "city": "Sao Paulo",
        "state": "SP",
        "zip": "01310-100"
      },
      "created_at": "2026-02-10T14:30:00.000Z",
      "updated_at": "2026-02-10T15:00:00.000Z"
    }
  }
}
GET /api/v1/revenue Revenue summary

Query Parameters

Parameter Type Description
period string Time period: 7d, 30d, 90d, 1y (default: 30d) optional

Example Request

cURL 
curl -X GET "https://api-marketplace.devskin.com/api/v1/revenue?period=30d" \
  -H "X-API-Key: your_api_key_here"

Example Response

JSON 
{
  "success": true,
  "data": {
    "period": "30d",
    "total": 24580.50,
    "daily": [
      {
        "date": "2026-02-13",
        "total": 1250.00,
        "count": 8
      },
      {
        "date": "2026-02-12",
        "total": 890.50,
        "count": 5
      }
    ]
  }
}
GET /api/v1/products List products (paginated)

Query Parameters

Parameter Type Description
page integer Page number (default: 1) optional
limit integer Items per page, max 100 (default: 20) optional

Example Request

cURL 
curl -X GET "https://api-marketplace.devskin.com/api/v1/products?page=1&limit=20" \
  -H "X-API-Key: your_api_key_here"

Example Response

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 42,
        "name": "Premium Widget",
        "slug": "premium-widget",
        "price": 94.95,
        "stock": 150,
        "status": "active",
        "created_at": "2026-01-15T10:00:00.000Z"
      }
    ],
    "total": 87,
    "page": 1,
    "limit": 20
  }
}
GET /api/v1/customers List customers (paginated)

Query Parameters

Parameter Type Description
page integer Page number (default: 1) optional
limit integer Items per page, max 100 (default: 20) optional

Example Request

cURL 
curl -X GET "https://api-marketplace.devskin.com/api/v1/customers?page=1&limit=20" \
  -H "X-API-Key: your_api_key_here"

Example Response

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 501,
        "name": "Jane Smith",
        "email": "[email protected]",
        "total_orders": 12,
        "total_spent": 2450.80,
        "created_at": "2025-11-20T09:15:00.000Z"
      }
    ],
    "total": 342,
    "page": 1,
    "limit": 20
  }
}
GET /api/v1/analytics/overview Analytics overview

Returns a high-level overview of your store's key metrics. No parameters required.

Example Request

cURL 
curl -X GET "https://api-marketplace.devskin.com/api/v1/analytics/overview" \
  -H "X-API-Key: your_api_key_here"

Example Response

JSON 
{
  "success": true,
  "data": {
    "total_orders": 1563,
    "monthly_orders": 127,
    "total_revenue": 185420.50,
    "monthly_revenue": 24580.50,
    "total_products": 87
  }
}

Webhook Events

Webhooks allow your application to receive real-time notifications when events occur in your store. Configure webhook endpoints in your store's Settings → Webhooks tab. When an event fires, we send an HTTP POST request to your configured URL with the event data as JSON.

Supported Events

order.created
order.paid
order.cancelled
order.shipped
order.completed
product.created
product.updated
product.deleted
payment.received
payment.failed
payment.refunded
booking.created
booking.confirmed
booking.cancelled

Webhook Payload

Each webhook POST request includes the following structure:

JSON Payload 
{
  "event": "order.paid",
  "store_id": 15,
  "timestamp": "2026-02-13T14:30:00.000Z",
  "data": {
    "id": 1234,
    "order_number": "ORD-2026-001234",
    "total": 199.90,
    "status": "paid"
  }
}

Signature Verification

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body, using your webhook secret as the key. Always verify this signature before processing the webhook to ensure the request is authentic.

Signature format X-Webhook-Signature: sha256=HMAC(secret, body) — The signature is the hex-encoded HMAC-SHA256 of the raw request body using your webhook secret.

Verification Example — JavaScript (Node.js)

JavaScript 
const crypto = require('crypto');

function verifyWebhookSignature(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// Express middleware example
app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const rawBody = req.body; // use express.raw() middleware

  if (!verifyWebhookSignature(rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(rawBody);
  // Process the event...
  res.status(200).json({ received: true });
});

Verification Example — Python

Python 
import hmac
import hashlib

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask example
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature', '')
    raw_body = request.get_data()

    if not verify_webhook_signature(raw_body, signature, WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401

    event = request.get_json()
    # Process the event...
    return jsonify({'received': True}), 200

Code Examples

Complete examples showing how to authenticate and fetch data from the API in different languages.

cURL — List recent paid orders 
# List paid orders from the last 30 days
curl -X GET \
  "https://api-marketplace.devskin.com/api/v1/orders?status=paid&date_from=2026-01-14&date_to=2026-02-13&limit=50" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

# Get revenue summary for the last 90 days
curl -X GET \
  "https://api-marketplace.devskin.com/api/v1/revenue?period=90d" \
  -H "X-API-Key: your_api_key_here"

# Get analytics overview
curl -X GET \
  "https://api-marketplace.devskin.com/api/v1/analytics/overview" \
  -H "X-API-Key: your_api_key_here"
JavaScript (fetch) — List orders & revenue 
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api-marketplace.devskin.com/api/v1';

async function fetchAPI(endpoint, params = {}) {
  const url = new URL(`${BASE_URL}/${endpoint}`);
  Object.entries(params).forEach(([key, val]) =>
    url.searchParams.append(key, val)
  );

  const response = await fetch(url, {
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// List recent paid orders
const orders = await fetchAPI('orders', {
  status: 'paid',
  limit: '50',
  date_from: '2026-01-14'
});
console.log(`Found ${orders.data.total} orders`);

// Get revenue for last 30 days
const revenue = await fetchAPI('revenue', { period: '30d' });
console.log(`Total revenue: $${revenue.data.total}`);

// Get analytics overview
const analytics = await fetchAPI('analytics/overview');
console.log(`Total products: ${analytics.data.total_products}`);
Python (requests) — List orders & revenue 
import requests

API_KEY = 'your_api_key_here'
BASE_URL = 'https://api-marketplace.devskin.com/api/v1'

headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
}

def fetch_api(endpoint, params=None):
    response = requests.get(
        f'{BASE_URL}/{endpoint}',
        headers=headers,
        params=params
    )
    response.raise_for_status()
    return response.json()

# List recent paid orders
orders = fetch_api('orders', {
    'status': 'paid',
    'limit': 50,
    'date_from': '2026-01-14'
})
print(f"Found {orders['data']['total']} orders")

# Get revenue for last 30 days
revenue = fetch_api('revenue', {'period': '30d'})
print(f"Total revenue: ${revenue['data']['total']}")

# Get analytics overview
analytics = fetch_api('analytics/overview')
print(f"Total products: {analytics['data']['total_products']}")

# List all customers
customers = fetch_api('customers', {'limit': 100})
for customer in customers['data']['items']:
    print(f"  {customer['name']} - {customer['email']}")

Error Codes

The API uses standard HTTP status codes. Here are the most common ones you may encounter:

Status Meaning Description
200 OK Request succeeded
400 Bad Request Invalid parameters or malformed request
401 Unauthorized Missing or invalid API key
403 Forbidden API key does not have access to this resource
404 Not Found The requested resource does not exist
429 Too Many Requests Rate limit exceeded (100 requests/minute)
500 Server Error Something went wrong on our end
Error Response Example 
{
  "success": false,
  "error": "Invalid or expired API key"
}