Reason
Configurable reasons used across business flows
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 /reason/create
Create a new reason. Reasons are configurable reference data used in business flows such as supplier returns, customer returns, purchase requests, order cancellations, transfers, write-offs, and more. name is required; type should be provided (model requires it — omitting type produces a validation error). is_active defaults to false.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Reason display name (required) |
type | string | No | Reason type — determines which business flow this reason applies to. Note: the model requires a type; omitting it will produce a Mongoose validation error.. One of: supplier_return, customer_return, purchase_request, contract_cancel, order_cancel, transfer, transfer_cancel, write_off, visit_reject, delivery_order_cancel, task |
description | string | No | Optional description |
is_active | boolean | No | Whether this reason is active. Defaults to false. |
is_trash | boolean | No | Whether this reason is for trash/disposal flows. |
code | string | No | Optional short code identifier for the reason. |
order_number | number | No | Sort order (ascending). Used to control display order. |
color | string | No | Hex color code, format #RRGGBB (e.g. #FF5733) |
{
"name": "string",
"type": "supplier_return",
"description": "string",
"is_active": false,
"is_trash": false,
"code": "string",
"order_number": 0,
"color": "string"
}Response
| Field | Type | Description |
|---|---|---|
_id | string | Reason ObjectId |
name | string | Reason display name |
type | string | Reason type — determines which business flow this reason applies to. One of: supplier_return, customer_return, purchase_request, contract_cancel, order_cancel, transfer, transfer_cancel, write_off, visit_reject, delivery_order_cancel, task |
description | string | Optional description |
is_active | boolean | Whether this reason is active |
is_trash | boolean | Whether this reason is for trash/disposal flows |
code | string | Short code identifier |
order_number | number | Sort order (ascending) |
color | string | Hex color code, format #RRGGBB |
created_at | string (date-time) | Creation timestamp |
updated_at | string (date-time) | Last update timestamp |
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": {
"_id": "string",
"name": "string",
"type": "supplier_return",
"description": "string",
"is_active": false,
"is_trash": false,
"code": "string",
"order_number": 0,
"color": "string",
"created_at": "2025-05-01T12:00:00Z",
"updated_at": "2025-05-01T12:00:00Z"
},
"time": "2025-05-01T12:00:00Z"
}GET /reason/get-by-id/{id}
Fetch a single reason by its ObjectId.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Reason ObjectId |
Request body
No request body.
Response
Same response shape as POST /reason/create.
POST /reason/get-paging
Paginated list of reasons. Filter by type (supplier_return, customer_return, purchase_request, contract_cancel, order_cancel, transfer, transfer_cancel, write_off, visit_reject, delivery_order_cancel, task) and/or is_active. Results sorted by order_number asc, _id desc (or sort_by override).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
page | number | Yes | Default: 1 |
limit | number | Yes | Default: 20 |
type | string | No | Filter by reason type. Omit to return reasons of all types.. One of: supplier_return, customer_return, purchase_request, contract_cancel, order_cancel, transfer, transfer_cancel, write_off, visit_reject, delivery_order_cancel, task |
is_active | boolean | No | Filter by active state. Omit to return both active and inactive reasons. |
{
"page": 1,
"limit": 20,
"type": "supplier_return",
"is_active": false
}Response
| Field | Type | Description |
|---|---|---|
total | number | |
list | object[] | |
list[]._id | string | Reason ObjectId |
list[].name | string | Reason display name |
list[].type | string | Reason type — determines which business flow this reason applies to. One of: supplier_return, customer_return, purchase_request, contract_cancel, order_cancel, transfer, transfer_cancel, write_off, visit_reject, delivery_order_cancel, task |
list[].description | string | Optional description |
list[].is_active | boolean | Whether this reason is active |
list[].is_trash | boolean | Whether this reason is for trash/disposal flows |
list[].code | string | Short code identifier |
list[].order_number | number | Sort order (ascending) |
list[].color | string | Hex color code, format #RRGGBB |
list[].created_at | string (date-time) | Creation timestamp |
list[].updated_at | string (date-time) | Last update timestamp |
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": {
"total": 0,
"list": [
{
"_id": "string",
"name": "string",
"type": "supplier_return",
"description": "string",
"is_active": false,
"is_trash": false,
"code": "string",
"order_number": 0,
"color": "string",
"created_at": "2025-05-01T12:00:00Z",
"updated_at": "2025-05-01T12:00:00Z"
}
]
},
"time": "2025-05-01T12:00:00Z"
}PUT /reason/update/{id}
Update an existing reason by ObjectId. All fields are optional; only provided fields are updated. name must be non-empty if provided.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Reason ObjectId to update |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Updated reason display name |
type | string | No | Updated reason type. One of: supplier_return, customer_return, purchase_request, contract_cancel, order_cancel, transfer, transfer_cancel, write_off, visit_reject, delivery_order_cancel, task |
description | string | No | Updated description |
is_active | boolean | No | Toggle active state |
is_trash | boolean | No | Toggle trash/disposal flag |
code | string | No | Updated short code identifier |
order_number | number | No | Updated sort order |
color | string | No | Updated hex color code, format #RRGGBB |
{
"name": "string",
"type": "supplier_return",
"description": "string",
"is_active": false,
"is_trash": false,
"code": "string",
"order_number": 0,
"color": "string"
}Response
Same response shape as POST /reason/create.
DELETE /reason/delete/{id}
Soft-delete a reason by ObjectId (sets is_deleted=true). Returns 400 if the reason is not found.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Reason ObjectId to delete |
Request body
No request body.
Response
{
"code": 0,
"message": "Success",
"status_code": 200,
"data": "ok",
"time": "2025-05-01T12:00:00Z"
}This page is generated from the OpenAPI spec.