API v2.4 · Last updated Apr 2026

Sales Metrix Documentation

Everything you need to build on Sales Metrix — REST API, webhooks, SDKs, and integration guides.

Quick Start

Make your first API call in 5 min

API Reference

Full endpoint & schema docs

Integrations

Connect platforms & ERPs

Webhooks

Real-time event subscriptions

Quick Start

Up and running in 5 minutes

Four steps from zero to your first live API response.

Get your API key

Navigate to Settings → API Keys in your Sales Metrix dashboard and create a new secret key. Keep it safe — it won't be shown again.

Install the SDK

Choose your language below. The SDK handles authentication, retries, rate limiting, and type safety automatically.

Make your first call

Use the example to list your orders. Swap in your API key and you'll see live data from your connected channels.

Subscribe to webhooks

Base URL

https://api.salesmetrix.com/v2

Content-Typeapplication/json

AuthorizationBearer {API_KEY}

SM-Version2026-04-01

import SalesMetrix from "@salesmetrix/sdk";

const client = new SalesMetrix({
  apiKey: process.env.SM_API_KEY,
});

// List orders from all channels
const orders = await client.orders.list({
  status: "pending",
  limit: 20,
});

console.log(orders.data);

Response200 OK

{
  "data": [
    {
      "id": "ord_01HXYZ8821",
      "status": "pending",
      "channel": "shopify",
      "customer": { "name": "Acme Corp", "email": "ops@acme.com" },
      "total": 4200.00,
      "currency": "USD",
      "created_at": "2026-04-30T09:12:44Z"
    }
  ],
  "meta": { "total": 142, "limit": 20, "next_cursor": "cur_..." }
}

API Reference

REST API endpoints

All resources follow REST conventions. JSON in, JSON out. Paginated lists use cursor-based pagination.

AUTH

Bearer token authentication

All endpoints require an Authorization: Bearer {API_KEY} header. Keys are scoped — read-only keys cannot write data. Generate keys in Settings → API Keys.

OrdersFull reference

GET/ordersList all orders with filters and pagination GET/orders/:idRetrieve a single order by ID POST/ordersCreate a new order manually PATCH/orders/:idUpdate order status or metadata DELETE/orders/:idCancel an order and release inventory POST/orders/:id/fulfilTrigger fulfilment for a specific order

InventoryFull reference

GET/inventoryList inventory levels across all locations GET/inventory/:skuGet stock for a specific SKU PATCH/inventory/:skuAdjust stock quantity manually POST/inventory/reserveReserve stock for a pending order POST/inventory/transferMove stock between warehouses

ShipmentsFull reference

GET/shipmentsList shipments with carrier and tracking info GET/shipments/:idGet a shipment and its current tracking status POST/shipments/ratesGet rate-shopped carrier quotes for an order POST/shipments/labelPurchase a label and return the PDF URL

ReturnsFull reference

GET/returnsList all return requests POST/returnsInitiate a return and issue a label PATCH/returns/:idApprove, reject, or mark return received POST/returns/:id/refundIssue a full or partial refund

ChannelsFull reference

GET/channelsList all connected sales channels POST/channelsConnect a new channel via OAuth or API key GET/channels/:id/syncTrigger a manual sync for a channel DELETE/channels/:idDisconnect and remove a channel

WebhooksFull reference

GET/webhooksList all registered webhook endpoints POST/webhooksRegister a new webhook with event filters GET/webhooks/:id/eventsView recent delivery attempts and payloads DELETE/webhooks/:idRemove a webhook endpoint

1,000 req/min

Rate limit

Per API key — burst up to 2,000

Cursor-based

Pagination

Use next_cursor from meta object

Header-pinned

API versioning

SM-Version: YYYY-MM-DD

Webhooks

Real-time event subscriptions

Subscribe to any combination of 40+ events. We deliver to your endpoint with automatic retries and signature verification.

16 events

Orders

order.created

A new order was placed on any connected channel

Orders

order.updated

Order status, metadata, or line items changed

Orders

order.fulfilled

All items in the order have been picked and packed

Orders

order.cancelled

Order was cancelled and inventory released

Shipments

shipment.created

A shipping label was purchased for an order

Shipments

shipment.in_transit

Carrier scanned the package at a facility

Shipments

shipment.delivered

Carrier confirmed delivery at the destination

Shipments

shipment.exception

Carrier reported a delay, hold, or failed delivery

Returns

return.initiated

Customer submitted a return request

Returns

return.received

Warehouse scanned the returned item

Returns

return.refunded

Refund posted to the original payment method

Inventory

inventory.low

SKU stock dropped below the configured threshold

Inventory

inventory.stockout

SKU reached zero stock across all locations

Inventory

inventory.restocked

Stock was added or transferred to a location

Payments

payment.failed

Payment gateway declined or returned an error

Payments

fraud.flagged

Order scored above the fraud risk threshold

Example payload

{
  "id": "evt_01HXYZ99KM",
  "type": "order.created",
  "created_at": "2026-04-30T09:12:44Z",
  "api_version": "2026-04-01",
  "data": {
    "id": "ord_01HXYZ8821",
    "status": "pending",
    "channel": "shopify",
    "customer": {
      "name": "Acme Corp",
      "email": "ops@acme.com"
    },
    "items": [
      { "sku": "ENT-KIT-003", "qty": 3, "price": 1400.00 }
    ],
    "total": 4200.00,
    "currency": "USD"
  }
}

Signature verification

Each request includes an SM-Signature header. Verify it with your webhook secret to ensure the payload is authentic.

import crypto from "crypto";

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

5×

Retry attempts

With exponential back-off

30s

Timeout

Per delivery attempt

At-least-once

Ordering

Use idempotency keys

JSON

Format

UTF-8, no gzip