Products API

Manage product catalog including items, SKUs, pricing, and metadata. Public catalog endpoints are available without admin auth via API key.

GET /catalog/products

Public catalog — list products for storefront display

API Key (X-API-Key header)
GET /catalog/products/{product_id}

Public catalog — get product detail for storefront

API Key (X-API-Key header)
GET /admin/products

List all products with pagination and filtering (admin)

Query Parameters

?limit=50&offset=0&category=apparel&status=active&search=shirt

Response

{
  "success": true,
  "data": [
    {
      "id": "prod_123",
      "name": "Custom T-Shirt",
      "sku": "TSHIRT-01",
      "price": 29.99,
      "quantity": 150,
      "category": "apparel",
      "created_at": "2026-03-20T10:30:00Z"
    }
  ],
  "pagination": { "total": 342, "offset": 0, "limit": 50 }
}
Bearer Token Required
POST /admin/products

Create a new product

Request Body

{
  "name": "Custom Hoodie",
  "sku": "HOODIE-01",
  "price": 49.99,
  "quantity": 100,
  "category": "apparel",
  "description": "Premium custom hoodie"
}

Response

{
  "success": true,
  "data": {
    "id": "prod_456",
    "name": "Custom Hoodie",
    "sku": "HOODIE-01",
    "created_at": "2026-03-20T14:00:00Z"
  }
}
Bearer Token Required
GET/admin/products/{product_id}

Get full details of a single product

Bearer Token Required
PUT/admin/products/{product_id}

Update an existing product's details

Bearer Token Required
DEL/admin/products/{product_id}

Delete a product

Bearer Token Required

Product Variants API

Manage product variants (size, color, material) with independent stock tracking.

GET/admin/products/{product_id}/variants

List all variants for a product

Response

{
  "success": true,
  "data": [
    { "id": "var_01", "sku": "TSHIRT-01-BLK-M", "attributes": { "color": "Black", "size": "M" }, "price": 29.99, "quantity": 45 },
    { "id": "var_02", "sku": "TSHIRT-01-BLK-L", "attributes": { "color": "Black", "size": "L" }, "price": 29.99, "quantity": 32 }
  ]
}
Bearer Token Required
POST/admin/products/{product_id}/variants

Create a new variant for a product

Request Body

{
  "sku": "TSHIRT-01-WHT-S",
  "attributes": { "color": "White", "size": "S" },
  "price": 29.99,
  "quantity": 60
}
Bearer Token Required

Categories API

Organize products into categories with custom ordering.

GET/admin/categories

List all product categories with sort order

Response

{
  "success": true,
  "data": [
    { "id": "cat_01", "name": "Apparel", "slug": "apparel", "sort_order": 1, "product_count": 86 },
    { "id": "cat_02", "name": "Accessories", "slug": "accessories", "sort_order": 2, "product_count": 42 }
  ]
}
Bearer Token Required
POST/admin/categories

Create a new category

Request Body

{ "name": "Goalkeeper", "slug": "goalkeeper", "sort_order": 3 }
Bearer Token Required

Images API

Upload, manage, and delete product images stored on Cloudflare R2.

POST/admin/images/upload-product/{product_id}

Upload an image and attach it to a product (multipart/form-data)

Request

Content-Type: multipart/form-data
file: (binary image data)

Response

{
  "success": true,
  "data": { "key": "products/prod_123/image_001.jpg", "url": "https://images.marcsinventory.com/products/prod_123/image_001.jpg" }
}
Bearer Token Required

Inventory / Stock API

Track and manage inventory levels, stock adjustments, and availability.

GET /admin/inventory

Get current inventory levels and stock status

Query Parameters

?product_id=prod_123&location_id=loc_456&low_stock=true

Response

{
  "success": true,
  "data": {
    "product_id": "prod_123",
    "quantity_available": 145,
    "quantity_reserved": 5,
    "quantity_allocated": 0,
    "reorder_level": 20,
    "status": "in_stock"
  }
}
Bearer Token Required
POST /admin/inventory/adjust

Adjust inventory quantity for a product

Request Body

{
  "product_id": "prod_123",
  "quantity_change": 50,
  "reason": "stock_received",
  "reference": "PO-2026-001"
}

Response

{
  "success": true,
  "data": {
    "product_id": "prod_123",
    "new_quantity": 195,
    "adjusted_at": "2026-03-20T10:30:00Z"
  }
}
Bearer Token Required

Inventory Adjustments API

Record and audit stock adjustments with reason codes for shrinkage, damage, corrections, and more.

GET/admin/adjustments

List inventory adjustments with filters

Query Parameters

?product_id=prod_123&reason_code=damaged&date_from=2026-03-01&date_to=2026-03-22&page=1&page_size=50

Response

{
  "success": true,
  "data": [
    { "id": "adj_01", "product_id": "prod_123", "quantity_change": -3, "reason_code": "damaged", "notes": "Water damage in warehouse", "user_email": "marc@example.com", "created_at": "2026-03-22T08:00:00Z" }
  ]
}
Bearer Token Required
GET/admin/adjustments/reason-codes/list

List all available reason codes for adjustments

Response

{
  "success": true,
  "data": [
    {"code": "damaged", "label": "Damaged"},
    {"code": "shrinkage", "label": "Shrinkage"}
  ]
}
Bearer Token Required
GET/admin/adjustments/summary/stats

Get summary statistics for adjustments over a time period

Response

{
  "success": true,
  "data": {
    "total_adjustments": 127,
    "total_quantity_change": -342
  }
}
Bearer Token Required

Auto-Reorder API

Automatically generate purchase orders when inventory drops below reorder thresholds.

GET/admin/auto-reorder/preview

Preview which products would be reordered based on current stock levels and thresholds

Response

{
  "success": true,
  "data": {
    "products_to_reorder": [{"product_id": "prod_123", "current_stock": 15}]
  }
}
Bearer Token Required
POST/admin/auto-reorder/generate

Generate purchase orders for items below reorder point

Response

{
  "success": true,
  "data": {"purchase_orders_created": 3, "total_cost": 2500.00}
}
Bearer Token Required
POST/admin/auto-reorder/run

Execute a full auto-reorder cycle (generate + submit POs)

Response

{
  "success": true,
  "data": {"cycle_id": "cycle_01", "po_count": 3}
}
Bearer Token Required
GET/admin/auto-reorder/history

View history of past auto-reorder runs

Response

{
  "success": true,
  "data": [{"cycle_id": "cycle_01", "status": "completed", "po_count": 3}]
}
Bearer Token Required

Stock Alerts API

Configure and manage low stock and inventory alerts.

POST /admin/stock-alerts

Create a stock alert for a product

Request Body

{
  "product_id": "prod_123",
  "threshold": 20,
  "alert_type": "low_stock",
  "notify_emails": ["manager@example.com"]
}

Response

{
  "success": true,
  "data": {
    "alert_id": "alert_001",
    "product_id": "prod_123",
    "threshold": 20,
    "active": true,
    "created_at": "2026-03-20T10:00:00Z"
  }
}
Bearer Token Required

Back in Stock API

Manage back-in-stock subscriptions and automatic notifications.

POST /admin/back-in-stock/subscribe

Subscribe customer to back-in-stock notifications

Request Body

{
  "customer_email": "john@example.com",
  "product_id": "prod_123",
  "notification_method": "email"
}

Response

{
  "success": true,
  "data": {
    "subscription_id": "sub_001",
    "customer_email": "john@example.com",
    "product_id": "prod_123",
    "subscribed_at": "2026-03-20T10:00:00Z"
  }
}
Bearer Token Required
POST /admin/back-in-stock/notify

Trigger notifications for back-in-stock product

Request Body

{
  "product_id": "prod_123"
}

Response

{
  "success": true,
  "data": {
    "product_id": "prod_123",
    "notifications_sent": 42,
    "sent_at": "2026-03-20T11:00:00Z"
  }
}
Bearer Token Required

Barcodes API

Generate, print, and manage barcodes for products and inventory.

POST /admin/barcodes/generate

Generate a barcode for a product

Request Body

{
  "product_id": "prod_123",
  "format": "code128",
  "quantity": 100
}

Response

{
  "success": true,
  "data": {
    "barcode_id": "bc_001",
    "product_id": "prod_123",
    "barcode_code": "123456789012",
    "image_url": "https://api.marcsinventory.com/barcodes/bc_001.png"
  }
}
Bearer Token Required

Seasons API

Organize team orders by season with teams, players, rosters, and uniforms.

GET/admin/seasons

List all seasons

Response

{
  "success": true,
  "data": [
    { "id": "season_01", "name": "Spring 2026", "start_date": "2026-03-01", "end_date": "2026-06-30", "team_count": 12, "status": "active" }
  ]
}
Bearer Token Required
GET/admin/seasons/{season_id}/teams/{team_id}/roster

Get the full roster for a team with player details and uniform assignments

Response

{
  "success": true,
  "data": {
    "team_id": "team_01",
    "team_name": "Riverside High",
    "player_count": 18
  }
}
Bearer Token Required