Inventory adjustments

Adjustments correct a SKU's stock at a location, with an auditable business reason (shrinkage, damage, count correction, etc.). All endpoints for this resource require the inventory:adjust permission.

List adjustments

{
  "adjustments": [
    {
      "_id": "670a1b2c3d4e5f6a7b8c9d0e",
      "locationId": "loc_abc123",
      "sku": "CAM-ROJO-M",
      "oldQuantity": 42,
      "newQuantity": 40,
      "adjustmentQuantity": -2,
      "reason": "damage",
      "status": "pending_review"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 6, "pages": 1 }
}

Query an adjustment

{ "_id": "670a1b2c3d4e5f6a7b8c9d0e", "sku": "CAM-ROJO-M", "status": "pending_review" }

{ "code": "not-found" }

Adjustments summary

{
  "totalAdjustments": 34,
  "positiveAdjustments": 12,
  "negativeAdjustments": 22,
  "totalQuantityAdjusted": -187,
  "totalCostImpact": 0
}

Create an adjustment

{
  "locationId": "loc_abc123",
  "sku": "CAM-ROJO-M",
  "newQuantity": 40,
  "reason": "damage",
  "notes": "2 piezas dañadas en almacén"
}

{
  "_id": "670a1b2c3d4e5f6a7b8c9d0e",
  "locationId": "loc_abc123",
  "sku": "CAM-ROJO-M",
  "oldQuantity": 42,
  "newQuantity": 40,
  "adjustmentQuantity": -2,
  "reason": "damage",
  "status": "pending_review"
}

{ "code": "bad-request/invalid-reason" }

Required permission: inventory:adjust

Key points about creation:

• You do not set oldQuantity yourself. The server always reads the current stock from the inventory record at the moment the adjustment is created, ignoring any oldQuantity you send in the body.
• adjustmentQuantity is calculated server-side as newQuantity − oldQuantity.
• If you omit productSku, the server resolves it in this order: (1) the productSku already present on the inventory record for that SKU/location, (2) a lookup in the product catalog, (3) falls back to using the sku itself as a last resort.

Write semantics — "apply first, review later"

This is the most important business pattern of this resource:

1. Creation (POST /inventory/adjustments) applies the stock change immediately. The record is born with status: 'pending_review', but the stock has already been modified at that point — not when someone approves it. This POST does trigger the Inventory Updated event (and a possible Low Stock Alert), because internally it uses the same write path as PUT for stock.
2. approve on a pending_review adjustment (today's normal flow) does not touch stock again. It only changes status → approved and stamps the audit fields (approvedBy, approvedAt). The stock already moved in step 1.
3. reject does have an effect on stock: it reverts it to oldQuantity (triggering another Inventory Updated event for the reversal), and it also automatically creates a second adjustment record: reason: 'count_correction', sourceType: 'reversal', sourceId pointing to the original adjustment, adjustedBy: 'system', already in approved status.

Approve

{}

{ "_id": "670a1b2c3d4e5f6a7b8c9d0e", "status": "approved" }

{ "code": "not-found" }

Reject (reverts the stock)

{ "rejectionReason": "Conteo físico no coincide con el reporte" }

{ "_id": "670a1b2c3d4e5f6a7b8c9d0e", "status": "rejected" }

{ "code": "bad-request/missing-reason" }

{ "code": "not-found" }

Example — create and check the impact

curl -X POST 'https://api.fenicia.io/inventory/adjustments' \
  -H 'Authorization: Bearer fkapi_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "locationId": "loc_abc123",
    "sku": "CAM-ROJO-M",
    "newQuantity": 40,
    "reason": "damage",
    "notes": "2 piezas dañadas en almacén"
  }'

Errors

Next steps

• Inventory overview
• Query and update stock
• Transfers
• Counts