API Endpoints

This page documents all available StockrHub API endpoints, organized by resource. All endpoints require authentication via Shopify session tokens (see Authentication).

---

Dashboard

Get Dashboard Data

Retrieves dashboard statistics, recent purchase orders, and active alerts.

GET /api/dashboard

Response:

{
  "success": true,
  "data": {
    "stats": {
      "totalProducts": 245,
      "lowStockItems": 12,
      "openPurchaseOrders": 3,
      "pendingReceives": 1
    },
    "recentPOs": [
      {
        "id": 42,
        "poNumber": "PO-00042",
        "supplier": "Acme Supplies",
        "status": "sent",
        "total": 1250.00,
        "createdAt": "2026-02-25T10:30:00Z"
      }
    ],
    "alerts": [
      {
        "id": 1,
        "type": "low_stock",
        "message": "Widget Blue SM is below reorder point",
        "productId": "gid://shopify/Product/123",
        "createdAt": "2026-02-27T08:00:00Z"
      }
    ]
  }
}

---

Suppliers

List Suppliers

GET /api/suppliers

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Acme Supplies",
      "email": "[email protected]",
      "phone": "+1-555-0100",
      "leadTimeDays": 7,
      "paymentTerms": "Net 30",
      "createdAt": "2026-01-15T09:00:00Z"
    }
  ]
}

Create Supplier

POST /api/suppliers

Request:

{
  "name": "Acme Supplies",
  "email": "[email protected]",
  "phone": "+1-555-0100",
  "address": "123 Supply St, Commerce City, CO 80022",
  "leadTimeDays": 7,
  "paymentTerms": "Net 30",
  "notes": "Preferred supplier for widgets"
}

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Acme Supplies",
    "email": "[email protected]",
    "createdAt": "2026-02-28T12:00:00Z"
  }
}

Get Supplier

GET /api/suppliers/:id

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Acme Supplies",
    "email": "[email protected]",
    "phone": "+1-555-0100",
    "address": "123 Supply St, Commerce City, CO 80022",
    "leadTimeDays": 7,
    "paymentTerms": "Net 30",
    "notes": "Preferred supplier for widgets",
    "contacts": [],
    "createdAt": "2026-01-15T09:00:00Z",
    "updatedAt": "2026-02-20T14:30:00Z"
  }
}

Update Supplier

PUT /api/suppliers/:id

Request:

{
  "name": "Acme Supplies Inc.",
  "leadTimeDays": 5,
  "paymentTerms": "Net 15"
}

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Acme Supplies Inc.",
    "updatedAt": "2026-02-28T12:00:00Z"
  }
}

Delete Supplier

DELETE /api/suppliers/:id

Response:

{
  "success": true,
  "data": {
    "message": "Supplier deleted successfully"
  }
}

Caution

Deleting a supplier will not delete associated purchase orders. Existing POs will retain the supplier information at the time they were created.

Add Supplier Contact

POST /api/suppliers/:id/contacts

Request:

{
  "name": "Jane Smith",
  "email": "[email protected]",
  "phone": "+1-555-0101",
  "role": "Sales Representative"
}

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "supplierId": 1,
    "name": "Jane Smith",
    "email": "[email protected]",
    "phone": "+1-555-0101",
    "role": "Sales Representative"
  }
}

---

Purchase Orders

List Purchase Orders

GET /api/purchase-orders

Query parameters:

Parameter	Type	Description
status	string	Filter by status: draft, sent, partial, received, cancelled
supplierId	number	Filter by supplier ID

Response:

{
  "success": true,
  "data": [
    {
      "id": 42,
      "poNumber": "PO-00042",
      "supplierId": 1,
      "supplierName": "Acme Supplies",
      "status": "sent",
      "subtotal": 1150.00,
      "tax": 100.00,
      "total": 1250.00,
      "lineItemCount": 5,
      "createdAt": "2026-02-25T10:30:00Z",
      "sentAt": "2026-02-25T11:00:00Z"
    }
  ]
}

Create Purchase Order

POST /api/purchase-orders

Request:

{
  "supplierId": 1,
  "notes": "Rush order for weekend sale",
  "supplierNotes": "Please ship via express",
  "lineItems": [
    {
      "productId": "gid://shopify/Product/123",
      "variantId": "gid://shopify/ProductVariant/456",
      "sku": "WIDGET-BLU-SM",
      "title": "Widget Blue - Small",
      "quantity": 50,
      "costPrice": 12.50
    },
    {
      "productId": "gid://shopify/Product/124",
      "variantId": "gid://shopify/ProductVariant/789",
      "sku": "WIDGET-RED-MD",
      "title": "Widget Red - Medium",
      "quantity": 30,
      "costPrice": 14.00
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "id": 43,
    "poNumber": "PO-00043",
    "status": "draft",
    "supplierId": 1,
    "total": 1045.00,
    "createdAt": "2026-02-28T12:00:00Z"
  }
}

Get Purchase Order

GET /api/purchase-orders/:id

Response:

{
  "success": true,
  "data": {
    "id": 42,
    "poNumber": "PO-00042",
    "supplierId": 1,
    "supplierName": "Acme Supplies",
    "status": "sent",
    "notes": "Rush order for weekend sale",
    "supplierNotes": "Please ship via express",
    "subtotal": 1150.00,
    "tax": 100.00,
    "total": 1250.00,
    "lineItems": [
      {
        "id": 1,
        "sku": "WIDGET-BLU-SM",
        "title": "Widget Blue - Small",
        "quantity": 50,
        "costPrice": 12.50,
        "receivedQuantity": 0,
        "lineTotal": 625.00
      }
    ],
    "createdAt": "2026-02-25T10:30:00Z",
    "sentAt": "2026-02-25T11:00:00Z"
  }
}

Update Purchase Order

PUT /api/purchase-orders/:id

Note

Only purchase orders in draft status can be updated. Sent, partial, and received POs are immutable.

Request:

{
  "notes": "Updated internal notes",
  "lineItems": [
    {
      "sku": "WIDGET-BLU-SM",
      "quantity": 75,
      "costPrice": 12.00
    }
  ]
}

Delete Purchase Order

DELETE /api/purchase-orders/:id

Caution

Only draft purchase orders can be deleted. Sent or received POs must be cancelled instead.

Send Purchase Order

Sends the PO as a PDF to the supplier’s email address and changes the status to sent.

POST /api/purchase-orders/:id/send

Response:

{
  "success": true,
  "data": {
    "id": 42,
    "status": "sent",
    "sentAt": "2026-02-28T12:00:00Z"
  }
}

Receive Against Purchase Order

Records received quantities for a purchase order.

POST /api/purchase-orders/:id/receive

Request:

{
  "lineItems": [
    {
      "lineItemId": 1,
      "quantityReceived": 50
    },
    {
      "lineItemId": 2,
      "quantityReceived": 20
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "id": 42,
    "status": "partial",
    "receivedAt": "2026-02-28T14:00:00Z"
  }
}

---

Reorder Rules

List Reorder Rules

GET /api/reorder/rules

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "productId": "gid://shopify/Product/123",
      "variantId": "gid://shopify/ProductVariant/456",
      "sku": "WIDGET-BLU-SM",
      "title": "Widget Blue - Small",
      "reorderPoint": 20,
      "reorderQuantity": 50,
      "supplierId": 1,
      "supplierName": "Acme Supplies"
    }
  ]
}

Create Reorder Rule

POST /api/reorder/rules

Request:

{
  "variantId": "gid://shopify/ProductVariant/456",
  "reorderPoint": 20,
  "reorderQuantity": 50,
  "supplierId": 1
}

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "variantId": "gid://shopify/ProductVariant/456",
    "reorderPoint": 20,
    "reorderQuantity": 50,
    "supplierId": 1
  }
}

Update Reorder Rule

PUT /api/reorder/rules/:id

Request:

{
  "reorderPoint": 25,
  "reorderQuantity": 60
}

Delete Reorder Rule

DELETE /api/reorder/rules/:id

Get Reorder Suggestions

Returns products that are currently at or below their reorder point.

GET /api/reorder/suggestions

Response:

{
  "success": true,
  "data": [
    {
      "variantId": "gid://shopify/ProductVariant/456",
      "sku": "WIDGET-BLU-SM",
      "title": "Widget Blue - Small",
      "currentStock": 15,
      "reorderPoint": 20,
      "reorderQuantity": 50,
      "supplierId": 1,
      "supplierName": "Acme Supplies"
    }
  ]
}

---

Stock Levels

Get Stock Levels

GET /api/stock-levels

Query parameters:

Parameter	Type	Description
locationId	string	Filter by Shopify location ID
search	string	Search by product title or SKU

Response:

{
  "success": true,
  "data": [
    {
      "variantId": "gid://shopify/ProductVariant/456",
      "sku": "WIDGET-BLU-SM",
      "title": "Widget Blue - Small",
      "currentStock": 45,
      "locationId": "gid://shopify/Location/1",
      "locationName": "Warehouse"
    }
  ]
}

Bulk Update Stock Levels

PUT /api/stock-levels/bulk

Request:

{
  "adjustments": [
    {
      "variantId": "gid://shopify/ProductVariant/456",
      "locationId": "gid://shopify/Location/1",
      "quantity": 100,
      "reason": "Stock count adjustment"
    },
    {
      "variantId": "gid://shopify/ProductVariant/789",
      "locationId": "gid://shopify/Location/1",
      "quantity": 50,
      "reason": "Stock count adjustment"
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "adjusted": 2,
    "message": "Stock levels updated successfully"
  }
}

Caution

Bulk stock level updates directly modify inventory in Shopify. Ensure the quantities are correct before submitting, as these changes take effect immediately.

---

Stock Transfers

List Stock Transfers

GET /api/stock-transfers

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "sourceLocationId": "gid://shopify/Location/1",
      "sourceLocationName": "Warehouse",
      "destinationLocationId": "gid://shopify/Location/2",
      "destinationLocationName": "Retail Store",
      "status": "pending",
      "itemCount": 3,
      "createdAt": "2026-02-27T09:00:00Z"
    }
  ]
}

Create Stock Transfer

POST /api/stock-transfers

Request:

{
  "sourceLocationId": "gid://shopify/Location/1",
  "destinationLocationId": "gid://shopify/Location/2",
  "items": [
    {
      "variantId": "gid://shopify/ProductVariant/456",
      "quantity": 10
    },
    {
      "variantId": "gid://shopify/ProductVariant/789",
      "quantity": 5
    }
  ],
  "notes": "Restocking retail store for weekend"
}

Response:

{
  "success": true,
  "data": {
    "id": 2,
    "status": "pending",
    "createdAt": "2026-02-28T12:00:00Z"
  }
}

Get Stock Transfer

GET /api/stock-transfers/:id

Update Stock Transfer

PUT /api/stock-transfers/:id

Updates the status of a stock transfer (e.g., mark as completed).

Request:

{
  "status": "completed"
}

---

Stock Counts

List Stock Counts

GET /api/stock-counts

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "locationId": "gid://shopify/Location/1",
      "locationName": "Warehouse",
      "status": "draft",
      "itemCount": 15,
      "createdAt": "2026-02-26T08:00:00Z"
    }
  ]
}

Create Stock Count

POST /api/stock-counts

Request:

{
  "locationId": "gid://shopify/Location/1",
  "items": [
    {
      "variantId": "gid://shopify/ProductVariant/456",
      "countedQuantity": 48
    },
    {
      "variantId": "gid://shopify/ProductVariant/789",
      "countedQuantity": 22
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "id": 2,
    "status": "draft",
    "locationId": "gid://shopify/Location/1",
    "createdAt": "2026-02-28T12:00:00Z"
  }
}

Get Stock Count

GET /api/stock-counts/:id

Update Stock Count

Submit or modify a stock count.

PUT /api/stock-counts/:id

Request:

{
  "status": "submitted",
  "items": [
    {
      "variantId": "gid://shopify/ProductVariant/456",
      "countedQuantity": 47
    }
  ]
}

Note

When a stock count is submitted, StockrHub compares counted quantities to expected quantities and creates inventory adjustments in Shopify for any discrepancies.

---

Reports

Procurement Spend Report

GET /api/reports/procurement-spend

Query parameters:

Parameter	Type	Description
startDate	string	Start date (ISO 8601)
endDate	string	End date (ISO 8601)
supplierId	number	Filter by supplier

Response:

{
  "success": true,
  "data": {
    "totalSpend": 15420.00,
    "orderCount": 12,
    "bySupplier": [
      {
        "supplierId": 1,
        "supplierName": "Acme Supplies",
        "spend": 8500.00,
        "orderCount": 7
      }
    ],
    "byMonth": [
      {
        "month": "2026-01",
        "spend": 6200.00
      },
      {
        "month": "2026-02",
        "spend": 9220.00
      }
    ]
  }
}

Sales Velocity Report

GET /api/reports/sales-velocity

Query parameters:

Parameter	Type	Description
period	string	Time period: 7d, 30d, 90d

Response:

{
  "success": true,
  "data": [
    {
      "variantId": "gid://shopify/ProductVariant/456",
      "sku": "WIDGET-BLU-SM",
      "title": "Widget Blue - Small",
      "unitsSold": 120,
      "avgDailySales": 4.0,
      "currentStock": 45,
      "daysOfStockRemaining": 11
    }
  ]
}

Adjustments Report

GET /api/reports/adjustments

Query parameters:

Parameter	Type	Description
startDate	string	Start date (ISO 8601)
endDate	string	End date (ISO 8601)

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "variantId": "gid://shopify/ProductVariant/456",
      "sku": "WIDGET-BLU-SM",
      "previousQuantity": 50,
      "newQuantity": 48,
      "adjustment": -2,
      "reason": "Stock count adjustment",
      "createdAt": "2026-02-27T10:00:00Z"
    }
  ]
}

---

Alerts

Get Alerts

GET /api/alerts

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "type": "low_stock",
      "message": "Widget Blue SM is below reorder point (15 / 20)",
      "productId": "gid://shopify/Product/123",
      "read": false,
      "createdAt": "2026-02-27T08:00:00Z"
    },
    {
      "id": 2,
      "type": "po_overdue",
      "message": "PO-00038 from Acme Supplies is overdue by 3 days",
      "purchaseOrderId": 38,
      "read": false,
      "createdAt": "2026-02-26T00:00:00Z"
    }
  ]
}

Configure Alerts

POST /api/alerts/configure

Request:

{
  "lowStockAlerts": true,
  "overduePoAlerts": true,
  "alertThresholdPercent": 10
}

Response:

{
  "success": true,
  "data": {
    "message": "Alert configuration updated"
  }
}