Tag

Tags attachable to business entities

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 /tag/create

Create a new tag. Tags can be scoped to one or more entity types (customer, supplier, product, employee, crm_order). is_active defaults to true.

Request body

Field	Type	Required	Description
name	string	Yes	Tag display name
entity_scopes	string[]	Yes	Entity types this tag can be applied to — at least one required
color	string	No	Hex color code, format #RRGGBB (e.g. #FF5733)
is_active	boolean	No	Whether this tag is active. Defaults to true.

{
  "name": "string",
  "entity_scopes": [
    "customer"
  ],
  "color": "string",
  "is_active": false
}

Response

Field	Type	Description
_id	string	Tag ObjectId
name	string	Tag display name
color	string	Hex color code, format #RRGGBB (e.g. #FF5733)
entity_scopes	string[]	Entity types this tag can be applied to
is_system	boolean	System tags are created by Bito and cannot be deleted
is_active	boolean	Whether this tag is active and available for use

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "_id": "string",
    "name": "string",
    "color": "string",
    "entity_scopes": [
      "customer"
    ],
    "is_system": false,
    "is_active": false
  },
  "time": "2025-05-01T12:00:00Z"
}

GET /tag/get-by-id/{id}

Fetch a single tag by its ObjectId.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Tag ObjectId

Request body

No request body.

Response

Same response shape as POST /tag/create.

POST /tag/get-paging

Paginated list of tags. Filter by entity_scopes and/or is_active.

Request body

Field	Type	Required	Description
page	number	Yes	Default: 1
limit	number	Yes	Default: 20
entity_scopes	string[]	No	Filter by entity type(s)
is_active	boolean	No	Filter by active state. Omit to return all tags.

{
  "page": 1,
  "limit": 20,
  "entity_scopes": [
    "customer"
  ],
  "is_active": false
}

Response

Field	Type	Description
total	number
list	object[]
list[]._id	string	Tag ObjectId
list[].name	string	Tag display name
list[].color	string	Hex color code, format #RRGGBB (e.g. #FF5733)
list[].entity_scopes	string[]	Entity types this tag can be applied to
list[].is_system	boolean	System tags are created by Bito and cannot be deleted
list[].is_active	boolean	Whether this tag is active and available for use

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "total": 0,
    "list": [
      {
        "_id": "string",
        "name": "string",
        "color": "string",
        "entity_scopes": [],
        "is_system": false,
        "is_active": false
      }
    ]
  },
  "time": "2025-05-01T12:00:00Z"
}

PUT /tag/update/{id}

Update an existing tag by ObjectId. All fields are optional; only provided fields are updated. entity_scopes must have at least one value if provided.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Tag ObjectId to update

Request body

Field	Type	Required	Description
name	string	No	Updated tag display name
entity_scopes	string[]	No	Updated entity scopes — at least one required if provided
color	string	No	Updated hex color code, format #RRGGBB
is_active	boolean	No	Toggle tag active state

{
  "name": "string",
  "entity_scopes": [
    "customer"
  ],
  "color": "string",
  "is_active": false
}

Response

Same response shape as POST /tag/create.

DELETE /tag/delete/{id}

Soft-delete a tag by ObjectId (sets is_deleted=true). Returns 400 if the tag is a system tag (is_system=true) — system tags cannot be deleted.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Tag 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.