Documentation Content: Docstatus Field in Frappe v15

What is the Docstatus field?

The docstatus field is an integer attribute in every DocType table in Frappe. It indicates the state of a document — whether it’s still a draft, submitted (locked for editing), or cancelled. Frappe Documentation

Key values:

• 0 = Draft
• 1 = Submitted
• 2 = Cancelled Frappe Documentation

Documents that are not marked “Is Submittable” will always remain in state 0 (Draft).

Why use docstatus?

• Enforces business workflows: only submitted documents are finalized.
• Ensures data integrity: after submission or cancellation, modifications are restricted.
• Simplifies state handling: you have three defined states for many transaction DocTypes.

How docstatus works in Frappe v15

When you define a DocType as submittable (Is Submittable = 1), Frappe handles transitions:

• From Draft (0) a document can be submitted → becomes docstatus = 1.
• From Submitted (1) a document can be cancelled → becomes docstatus = 2.
• Documents in state 1 or 2 are locked for “normal” editing unless special field-level edit rights are permitted. Frappe Documentation 

Using DocStatus helper class

Example from docs:

import frappe
from frappe.model.docstatus import DocStatus
draft_invoice_names = frappe.get_list(
"Sales Invoice",
filters={"docstatus": DocStatus.draft()},
pluck="name"
)
invoice_doc = frappe.get_doc("Sales Invoice", draft_invoice_names[0])
invoice_doc.docstatus == DocStatus.draft() # True
invoice_doc.docstatus.is_draft() # True
invoice_doc.docstatus.is_submitted() # False
invoice_doc.docstatus.is_cancelled() # False
invoice_doc.submit()
invoice_doc.docstatus == DocStatus.submitted() # True
invoice_doc.docstatus.is_submitted() # True
invoice_doc.cancel()
invoice_doc.docstatus == DocStatus.cancelled() # True
``` :contentReference[oaicite:5]{index=5}
---
## Where docstatus is stored
The field `docstatus` is stored in the database table for the DocType (e.g., `tabSales Invoice`). It is an integer column. :contentReference[oaicite:6]{index=6}
---
## Common workflows and docstatus transitions
### 1. Draft → Submitted
Used for submittable documents (e.g., Sales Invoice, Purchase Order).
Developers call `doc.submit()` or the UI “Submit” button to move a document.
### 2. Submitted → Cancelled
Used when you need to reverse a transaction.
`doc.cancel()` is called.
After cancellation, the document cannot be edited normally.
### 3. Non-submittable documents
If the DocType is not marked as “Is Submittable”, its `docstatus` remains 0. It behaves like a normal record (editable) with no submission workflow.
---
## Developer usage & API
### Checking docstatus in code
```python
from frappe.model.docstatus import DocStatus
if doc.docstatus == DocStatus.submitted():
# do something for submitted documents

Filtering by docstatus

frappe.get_all(
"Sales Invoice",
filters={"docstatus": DocStatus.cancelled()},
fields=["name", "posting_date"]
)

Preventing edits on Submitted docs

In controller (.py) you can override methods:

def validate(self):
if self.docstatus == DocStatus.submitted():
frappe.throw("Cannot edit a submitted document")

This ensures that business logic is respected.

Best Practices & Tips

• Use Is Submittable only when you need locked states (e.g., financial documents).
• Always check docstatus when implementing custom logic for workflows.
• Customize field-level editability: Some fields may still be editable even if docstatus = 1. Use permission levels and permlevel.
• Use DocStatus.draft()/submitted()/cancelled() for readable code.
• Avoid hard-coding integer values like 1 or 2; use helper class for clarity.

Troubleshooting Common Issues

Related Topics for Further Reading

• DocTypes and Metadata
• Workflow in Frappe Framework
• Role & Permission Management
• Document Lifecycle & Audit-trail

Conclusion

The docstatus field is a key part of Frappe’s model for transaction control and workflow management. Understanding and using it correctly is essential for building robust business applications using Frappe v15. Keep your logic aligned with the helper class (DocStatus), set DocTypes correctly, and enforce transitions to ensure data integrity and workflow compliance.