Stock

Server

Stock overview

GET

https://api.wocart.store

/api/stock/overview

X-API-Key (header)

Returns aggregated inventory health metrics across all tracked SKUs. Includes counters, total inventory value, and segmented lists of out-of-stock and low-stock items.

Stock overview › Responses

200

Stock health overview

success

boolean · required

StockOverview · required

GET/api/stock/overview

curl https://api.wocart.store/api/stock/overview \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": {
    "totalSkus": 42,
    "outOfStockCount": 3,
    "lowStockCount": 7,
    "totalInventoryValue": 1250000,
    "currency": "DZD",
    "outOfStockItems": [
      {
        "productId": "prod_abc123",
        "variantId": null,
        "productName": "Samsung Galaxy A54",
        "variantLabel": "أحمر / M",
        "sku": "TSHIRT-RED-M",
        "inventory": 2,
        "lowStockThreshold": 5,
        "isOutOfStock": false,
        "updatedAt": "2025-01-15T10:30:00.000Z"
      }
    ],
    "lowStockItems": [
      {
        "productId": "prod_abc123",
        "variantId": null,
        "productName": "Samsung Galaxy A54",
        "variantLabel": "أحمر / M",
        "sku": "TSHIRT-RED-M",
        "inventory": 2,
        "lowStockThreshold": 5,
        "isOutOfStock": false,
        "updatedAt": "2025-01-15T10:30:00.000Z"
      }
    ],
    "allItems": [
      {
        "productId": "prod_abc123",
        "variantId": null,
        "productName": "Samsung Galaxy A54",
        "variantLabel": "أحمر / M",
        "sku": "TSHIRT-RED-M",
        "inventory": 2,
        "lowStockThreshold": 5,
        "isOutOfStock": false,
        "updatedAt": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

json

application/json

Low stock and out-of-stock alerts

GET

https://api.wocart.store

/api/stock/alerts

X-API-Key (header)

Paginated list of all SKUs at or below their low stock threshold (includes out-of-stock). Sorted: out-of-stock first, then by inventory ascending.

Low stock and out-of-stock alerts › query Parameters

limit

integer · max: 100

Default: 50

offset

integer | null · min: 0

Default: 0

Low stock and out-of-stock alerts › Responses

200

Paginated alert items

success

boolean · required

object · required

Adjust stock for a simple product

POST

https://api.wocart.store

/api/products/{id}/stock/adjust

X-API-Key (header)

Applies a signed integer delta to a simple product's inventory and appends a movement log entry.

reason is required for types: ADJUSTMENT_ADD, ADJUSTMENT_REMOVE, OFFLINE_SALE.

Delta sign convention: positive = stock arriving, negative = stock leaving. The server rejects adjustments that would result in negative inventory (HTTP 422).

Adjust stock for a simple product › path Parameters

id

string · required

Product ID

Adjust stock for a simple product › Request Body

type

string · enum · required

Enum values:

PURCHASE

ADJUSTMENT_ADD

ADJUSTMENT_REMOVE

ORDER_DEDUCTED

ORDER_CANCELLED

ORDER_RETURNED

OFFLINE_SALE

delta

integer · required

reason

string · minLength: 1 · maxLength: 500

Adjust stock for a simple product › Responses

Stock adjusted successfully

success

boolean · required

object · required

POST/api/products/{id}/stock/adjust

curl https://api.wocart.store/api/products/:id/stock/adjust \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "type": "PURCHASE",
  "delta": 0,
  "reason": "reason"
}'

Example Request Body

{
  "type": "PURCHASE",
  "delta": 0,
  "reason": "reason"
}

json

Example Responses

{
  "success": true,
  "data": {
    "movement": {
      "id": "mov_abc123",
      "productId": "prod_abc123",
      "variantId": null,
      "type": "PURCHASE",
      "delta": 10,
      "qtyBefore": 5,
      "qtyAfter": 15,
      "reason": "Restocked from supplier",
      "reference": null,
      "createdBy": "createdBy",
      "createdByName": "Ahmed Benali",
      "createdAt": "2024-08-25T15:00:00Z"
    },
    "currentInventory": 15
  }
}

json

application/json

Stock movement history for a product

GET

https://api.wocart.store

/api/products/{id}/stock/history

X-API-Key (header)

Paginated movement log for a product. Use variantId to narrow to a specific variant's history. Results are ordered newest-first.

Stock movement history for a product › path Parameters

id

string · required

Product ID

Stock movement history for a product › query Parameters

variantId

string

limit

integer · max: 100

Default: 20

offset

integer | null · min: 0

Default: 0

Stock movement history for a product › Responses

200

Paginated movement history

success

boolean · required

object · required

Update low stock threshold for a simple product

PATCH

https://api.wocart.store

/api/products/{id}/stock/threshold

X-API-Key (header)

Sets the lowStockThreshold for a simple (non-variant) product. When inventory drops at or below this value, the product appears in stock alerts.

Update low stock threshold for a simple product › path Parameters

id

string · required

Product ID

Update low stock threshold for a simple product › Request Body

lowStockThreshold

integer · min: 0 · max: 9999 · required

Update low stock threshold for a simple product › Responses

200

Threshold updated

success

boolean · required

Adjust stock for a product variant

POST

https://api.wocart.store

/api/products/{productId}/variants/{variantId}/stock/adjust

X-API-Key (header)

Same semantics as the simple-product adjust endpoint but targets a specific variant. The variantId must belong to productId.

Adjust stock for a product variant › path Parameters

productId

string · required

Product ID

variantId

string · required

Variant ID

Adjust stock for a product variant › Request Body

type

string · enum · required

Enum values:

PURCHASE

ADJUSTMENT_ADD

ADJUSTMENT_REMOVE

ORDER_DEDUCTED

ORDER_CANCELLED

ORDER_RETURNED

OFFLINE_SALE

delta

integer · required

reason

string · minLength: 1 · maxLength: 500

Adjust stock for a product variant › Responses

Variant stock adjusted

success

boolean · required

object · required

POST/api/products/{productId}/variants/{variantId}/stock/adjust

curl https://api.wocart.store/api/products/:productId/variants/:variantId/stock/adjust \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "type": "PURCHASE",
  "delta": 0,
  "reason": "reason"
}'

Example Request Body

{
  "type": "PURCHASE",
  "delta": 0,
  "reason": "reason"
}

json

Example Responses

{
  "success": true,
  "data": {
    "movement": {
      "id": "mov_abc123",
      "productId": "prod_abc123",
      "variantId": null,
      "type": "PURCHASE",
      "delta": 10,
      "qtyBefore": 5,
      "qtyAfter": 15,
      "reason": "Restocked from supplier",
      "reference": null,
      "createdBy": "createdBy",
      "createdByName": "Ahmed Benali",
      "createdAt": "2024-08-25T15:00:00Z"
    },
    "currentInventory": 15
  }
}

json

application/json

Update low stock threshold for a variant

PATCH

https://api.wocart.store

/api/products/{productId}/variants/{variantId}/stock/threshold

X-API-Key (header)

Sets the lowStockThreshold for a specific product variant. The variant must belong to the specified product.

Update low stock threshold for a variant › path Parameters

productId

string · required

Product ID

variantId

string · required

Variant ID

Update low stock threshold for a variant › Request Body

lowStockThreshold

integer · min: 0 · max: 9999 · required

Update low stock threshold for a variant › Responses

200

Threshold updated

success

boolean · required

Collections Offers