Merchant API

Merchant API Reference

Manage your store programmatically with our comprehensive Merchant API. Perfect for inventory management, order processing, and business system integrations.

Authentication

API Key authentication with scoped permissions

Rate Limits

5000 requests per hour per API key

Webhooks

Real-time notifications for store events

Product Management

Create, update, and manage your product catalog

POST
/products

Create a new product in your catalog

Request Body 
{
  "name": "Premium Wireless Headphones",
  "description": "High-quality wireless headphones with noise cancellation",
  "price": 199.99,
  "compareAtPrice": 249.99,
  "sku": "WH-PREM-001",
  "category": "electronics",
  "tags": ["wireless", "headphones", "premium"],
  "images": [
    {
      "url": "https://cdn.example.com/headphones-1.jpg",
      "alt": "Premium Wireless Headphones - Front View"
    }
  ],
  "variants": [
    {
      "name": "Color",
      "options": [
        {
          "name": "Black",
          "price": 199.99,
          "sku": "WH-PREM-001-BLK",
          "inventory": 50
        },
        {
          "name": "White",
          "price": 199.99,
          "sku": "WH-PREM-001-WHT",
          "inventory": 30
        }
      ]
    }
  ],
  "specifications": {
    "brand": "AudioTech",
    "model": "AT-WH200",
    "batteryLife": "30 hours",
    "connectivity": "Bluetooth 5.0"
  },
  "seo": {
    "title": "Premium Wireless Headphones - AudioTech AT-WH200",
    "description": "Experience superior sound quality with our premium wireless headphones featuring active noise cancellation and 30-hour battery life.",
    "keywords": ["wireless headphones", "noise cancellation", "premium audio"]
  },
  "status": "active",
  "weight": 0.5,
  "dimensions": {
    "length": 20,
    "width": 18,
    "height": 8
  }
}
Response (201 Created) 
{
  "success": true,
  "data": {
    "id": "prod_987654321",
    "name": "Premium Wireless Headphones",
    "description": "High-quality wireless headphones with noise cancellation",
    "price": 199.99,
    "compareAtPrice": 249.99,
    "sku": "WH-PREM-001",
    "status": "active",
    "category": "electronics",
    "variants": [
      {
        "id": "var_123",
        "name": "Color",
        "options": [...]
      }
    ],
    "totalInventory": 80,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
PUT
/products/{id}

Update an existing product

Request Body 
{
  "name": "Premium Wireless Headphones Pro",
  "price": 229.99,
  "compareAtPrice": 279.99,
  "description": "Updated description with new features",
  "status": "active"
}
Response (200 OK) 
{
  "success": true,
  "data": {
    "id": "prod_987654321",
    "name": "Premium Wireless Headphones Pro",
    "price": 229.99,
    "compareAtPrice": 279.99,
    "updatedAt": "2024-01-15T14:30:00Z"
  }
}
PATCH
/products/bulk

Update multiple products at once

Request Body 
{
  "products": [
    {
      "id": "prod_987654321",
      "price": 199.99,
      "status": "active"
    },
    {
      "id": "prod_987654322",
      "price": 149.99,
      "status": "draft"
    }
  ]
}

Webhooks

Real-time notifications for store events

Available Events

Order Events
  • • order.created - New order placed
  • • order.updated - Order status changed
  • • order.paid - Payment completed
  • • order.shipped - Order shipped
  • • order.delivered - Order delivered
  • • order.cancelled - Order cancelled
Product Events
  • • product.created - New product added
  • • product.updated - Product modified
  • • product.deleted - Product removed
  • • inventory.low - Low stock alert
  • • inventory.out - Out of stock
Customer Events
  • • customer.created - New customer registered
  • • customer.updated - Customer profile changed
  • • customer.deleted - Customer account deleted
Payment Events
  • • payment.succeeded - Payment successful
  • • payment.failed - Payment failed
  • • refund.created - Refund processed
Webhook Payload Example 
{
  "id": "evt_123456789",
  "event": "order.created",
  "createdAt": "2024-01-15T10:30:00Z",
  "data": {
    "id": "order_123456789",
    "orderNumber": "CF-2024-001234",
    "status": "confirmed",
    "total": 199.99,
    "currency": "USD",
    "customer": {
      "id": "cust_123456789",
      "email": "[email protected]"
    },
    "items": [...]
  },
  "previousData": null
}

Authentication

API key management and security

API Key Authentication

All Merchant API requests require authentication using an API key. Include your API key in the request header:

X-API-Key: your_api_key_here
Content-Type: application/json

API Key Scopes

Read Permissions
  • • products:read - View products
  • • orders:read - View orders
  • • customers:read - View customers
  • • analytics:read - View analytics
Write Permissions
  • • products:write - Manage products
  • • orders:write - Manage orders
  • • customers:write - Manage customers
  • • settings:write - Update settings

SDK Examples

Quick examples using our JavaScript SDK

JavaScript SDK Usage 
import { CommerceFull } from '@commercefull/merchant-sdk';

const client = new CommerceFull({
  apiKey: 'your-merchant-api-key',
  environment: 'production' // or 'sandbox'
});

// Create a new product
const product = await client.products.create({
  name: 'Premium Wireless Headphones',
  description: 'High-quality wireless headphones',
  price: 199.99,
  sku: 'WH-PREM-001',
  category: 'electronics'
});

// Get orders with filtering
const orders = await client.orders.list({
  status: 'confirmed',
  dateFrom: '2024-01-01',
  dateTo: '2024-01-31',
  limit: 50
});

// Update inventory
await client.inventory.update('var_123', {
  quantity: 25,
  adjustment: 'restock',
  reason: 'New shipment received'
});

// Get sales analytics
const analytics = await client.analytics.sales({
  period: 'month',
  groupBy: 'day'
});

// Update store settings
await client.settings.updateStore({
  general: {
    storeName: 'My Updated Store Name',
    contactEmail: '[email protected]'
  }
});