Write off

Stock write-offs

INFO

Every response arrives in the shared envelope — code, message, messages, status_code, time — with the payload in data. The tables below describe what is inside data.

POST /write-off/create

Create a new write-off (stock loss). The document is immediately persisted in DONE state; stock is decremented and a linked invoice is created inside the same transaction.

Request body

Field	Type	Required	Description
`organization_id`	`string`	No	Organization ObjectId. Required when the tenant has multiple organizations.
`code`	`string`	No	Optional external reference code for the write-off
`write_date`	`string (date-time)`	Yes	Date the write-off occurred
`source_warehouse_id`	`string`	No	Source warehouse ObjectId — the warehouse stock is deducted from
`responsible_id`	`string`	Yes	Employee ObjectId responsible for this write-off
`reason_id`	`string`	Yes	Reason ObjectId explaining why the stock is being written off
`currency_id`	`string`	No	Currency ObjectId used for cost values. Defaults to the organization's base currency.
`action`	`string`	Yes	Write-off action type. `remove` — permanent stock removal; `defect` — defective goods moved to a destination warehouse.. One of: `remove`, `defect`
`destination_warehouse_id`	`string`	No	Destination warehouse ObjectId. Required when `action` is `defect`.
`note`	`string`	No	Optional free-text note
`products`	`object[]`	Yes	List of products to write off. At least one item is required.
`products[].product_id`	`string`	Yes	Product ObjectId
`products[].amount`	`number`	Yes	Quantity to write off (must be positive)
`products[].box_count`	`number`	No	Number of boxes (integer; defaults to 0)
`products[].marks`	`string[]`	No	Mark/serial codes for marked goods. Each mark must be unique within the request.
`products[].expiration_date`	`string (date-time)`	No	Expiration date — required for perishable products that have `has_expiration: true`

json

{
  "organization_id": "string",
  "code": "string",
  "write_date": "2025-05-01T12:00:00Z",
  "source_warehouse_id": "string",
  "responsible_id": "string",
  "reason_id": "string",
  "currency_id": "string",
  "action": "remove",
  "destination_warehouse_id": "string",
  "note": "string",
  "products": [
    {
      "product_id": "string",
      "amount": 0,
      "box_count": 0,
      "marks": [],
      "expiration_date": "2025-05-01T12:00:00Z"
    }
  ]
}

Response

Field	Type	Description
`_id`	`string`
`number`	`string`	Auto-generated write-off document number
`code`	`string`	Optional external reference code
`write_date`	`string (date-time)`
`action`	`string`	One of: `remove`, `defect`
`state`	`string`	One of: `done`, `canceled`
`note`	`string`
`total_cost`	`number`
`organization`	`object`
`organization._id`	`string`
`organization.name`	`string`
`responsible_employee`	`object`
`responsible_employee._id`	`string`
`responsible_employee.full_name`	`string`
`reason`	`object`
`reason._id`	`string`
`reason.name`	`string`
`currency`	`object`
`currency._id`	`string`
`currency.name`	`string`
`source_warehouse`	`object`
`source_warehouse._id`	`string`
`source_warehouse.name`	`string`
`destination_warehouse`	`object`	Populated only when action is `defect`
`destination_warehouse._id`	`string`
`destination_warehouse.name`	`string`
`products`	`object[]`
`products[]._id`	`string`
`products[].product_id`	`string`
`products[].name`	`string`
`products[].barcode`	`string`
`products[].amount`	`number`
`products[].box_count`	`number`
`products[].cost`	`number`
`products[].total_cost`	`number`
`products[].marks`	`string[]`
`products[].expiration_date`	`string (date-time)`
`created_at`	`string (date-time)`
`updated_at`	`string (date-time)`

json

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "_id": "string",
    "number": "string",
    "code": "string",
    "write_date": "2025-05-01T12:00:00Z",
    "action": "remove",
    "state": "done",
    "note": "string",
    "total_cost": 0,
    "organization": {
      "_id": "string",
      "name": "string"
    },
    "responsible_employee": {
      "_id": "string",
      "full_name": "string"
    },
    "reason": {
      "_id": "string",
      "name": "string"
    },
    "currency": {
      "_id": "string",
      "name": "string"
    },
    "source_warehouse": {
      "_id": "string",
      "name": "string"
    },
    "destination_warehouse": {
      "_id": "string",
      "name": "string"
    },
    "products": [
      {
        "_id": "string",
        "product_id": "string",
        "name": "string",
        "barcode": "string",
        "amount": 0,
        "box_count": 0,
        "cost": 0,
        "total_cost": 0,
        "marks": [],
        "expiration_date": "2025-05-01T12:00:00Z"
      }
    ],
    "created_at": "2025-05-01T12:00:00Z",
    "updated_at": "2025-05-01T12:00:00Z"
  },
  "time": "2025-05-01T12:00:00Z"
}

PUT /write-off/set-status/{id}

Transition a write-off to CANCELED state. This is the only valid state transition — it reverses stock, cancels the linked invoice, and posts a CREDIT reconciliation act. Only status: "canceled" is accepted; write-offs are created directly in DONE state.

Path parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Write-off ObjectId

Request body

Field	Type	Required	Description
`status`	`string`	Yes	Target status. Only `canceled` is accepted — write-offs are created directly in DONE state and the only permitted transition is DONE → canceled.. One of: `canceled`
`reason`	`string`	No	Optional free-text reason for the cancellation

json

{
  "status": "canceled",
  "reason": "string"
}

Response

Same response shape as POST /write-off/create.

GET /write-off/get-by-id/{id}

Fetch a single write-off by ObjectId with full detail (products, organization, responsible employee, reason, currency, warehouses, attachments).

Path parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Write-off ObjectId

Request body

No request body.

Response

Same response shape as POST /write-off/create.

POST /write-off/get-paging

Paginated list of write-offs. Filterable by organization, warehouse, responsible employee, action type, and date range.

Request body

Field	Type	Required	Description
`page`	`number`	Yes	Default: `1`
`limit`	`number`	Yes	Default: `20`
`organization_id`	`string`	No	Filter by organization ObjectId
`warehouse_id`	`string`	No	Filter by source warehouse ObjectId
`responsible_id`	`string`	No	Filter by responsible employee ObjectId
`action`	`string`	No	Filter by write-off action type. One of: `remove`, `defect`

json

{
  "page": 1,
  "limit": 20,
  "organization_id": "string",
  "warehouse_id": "string",
  "responsible_id": "string",
  "action": "remove"
}

Response

Field	Type	Description
`total`	`number`
`list`	`object[]`
`list[]._id`	`string`
`list[].number`	`string`
`list[].code`	`string`
`list[].write_date`	`string (date-time)`
`list[].action`	`string`	One of: `remove`, `defect`
`list[].state`	`string`	One of: `done`, `canceled`
`list[].total_cost`	`number`
`list[].organization`	`object`
`list[].organization._id`	`string`
`list[].organization.name`	`string`
`list[].responsible_employee`	`object`
`list[].responsible_employee._id`	`string`
`list[].responsible_employee.full_name`	`string`
`list[].reason`	`object`
`list[].reason._id`	`string`
`list[].reason.name`	`string`
`list[].source_warehouse`	`object`
`list[].source_warehouse._id`	`string`
`list[].source_warehouse.name`	`string`
`list[].created_at`	`string (date-time)`

json

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "total": 0,
    "list": [
      {
        "_id": "string",
        "number": "string",
        "code": "string",
        "write_date": "2025-05-01T12:00:00Z",
        "action": "remove",
        "state": "done",
        "total_cost": 0,
        "organization": {
          "_id": null,
          "name": null
        },
        "responsible_employee": {
          "_id": null,
          "full_name": null
        },
        "reason": {
          "_id": null,
          "name": null
        },
        "source_warehouse": {
          "_id": null,
          "name": null
        },
        "created_at": "2025-05-01T12:00:00Z"
      }
    ]
  },
  "time": "2025-05-01T12:00:00Z"
}

This page is generated from the OpenAPI spec.

Write off ​

POST /write-off/create ​

PUT /write-off/set-status/{id} ​

GET /write-off/get-by-id/{id} ​

POST /write-off/get-paging ​

Write off

POST /write-off/create

PUT /write-off/set-status/{id}

GET /write-off/get-by-id/{id}

POST /write-off/get-paging