diff --git a/openapi/api-docs.yaml b/openapi/api-docs.yaml
index a736d98853..5670a10943 100644
--- a/openapi/api-docs.yaml
+++ b/openapi/api-docs.yaml
@@ -21989,6 +21989,7 @@ tags:
       description: "Find out more"
       url: "https://invoiceninja.github.io"
   - name: clients
+    x-tag-expanded: true
     description: |
       Endpoint definitions for interacting with clients.
   - name: products
@@ -21996,7 +21997,43 @@ tags:
       Endpoint definitions for interacting with products.
   - name: invoices
     description: |
-      Endpoint definitions for interacting with invoices.
+
+      ## Invoice Statuses
+      <ul>
+        <li>
+          <p>STATUS_DRAFT = 1</p>
+          <p>Draft invoices are not visible in the client portal, are not active and they do not impact the client balance</p>
+        </li>
+        <li>
+          <p>STATUS_SENT = 2</p>
+          <p>Send invoices are visible in the client portal, are active and impact the client balance</p>
+        </li>
+        <li>
+          <p>STATUS_PARTIAL = 3</p>
+          <p>An invoice which has been partially paid</p>
+        </li>
+        <li>
+          <p>STATUS_PAID = 4</p>
+          <p>An invoice which has been fully paid</p>
+        </li>
+        <li>
+          <p>STATUS_CANCELLED = 5</p>
+          <p>When a invoice is cancelled the invoice balance is set to zero and the status updated to Cancelled, the client balance is also adjusted down. If payments have been applied to the invoice these will remain linked to the invoice.</p>
+        </li>
+        <li>
+          <p>STATUS_REVERSED = 6</p>
+          <p>When a invoice has been reversed, the previous payments relationships are unlinked and cannot be restored.</p>
+        </li>
+        <li>
+          <p>STATUS_OVERDUE = -1</p>
+          <p>An invoice which is still payable past its due date</p>
+        </li>
+        <li>
+          <p>STATUS_UNPAID = -2</p>
+          <p>An invoice which is not yet due, but also, not paid.</p>
+        </li>
+      </ul>
+      
   - name: Recurring Invoices
     description: |
       Endpoint definitions for interacting with recurring_invoices.
diff --git a/openapi/misc/misc.yaml b/openapi/misc/misc.yaml
index 6d7f3194ba..d9a8e39965 100644
--- a/openapi/misc/misc.yaml
+++ b/openapi/misc/misc.yaml
@@ -6,6 +6,7 @@ tags:
       description: "Find out more"
       url: "https://invoiceninja.github.io"
   - name: clients
+    x-tag-expanded: true
     description: |
       Endpoint definitions for interacting with clients.
   - name: products
@@ -13,7 +14,43 @@ tags:
       Endpoint definitions for interacting with products.
   - name: invoices
     description: |
-      Endpoint definitions for interacting with invoices.
+
+      ## Invoice Statuses
+      <ul>
+        <li>
+          <p>STATUS_DRAFT = 1</p>
+          <p>Draft invoices are not visible in the client portal, are not active and they do not impact the client balance</p>
+        </li>
+        <li>
+          <p>STATUS_SENT = 2</p>
+          <p>Send invoices are visible in the client portal, are active and impact the client balance</p>
+        </li>
+        <li>
+          <p>STATUS_PARTIAL = 3</p>
+          <p>An invoice which has been partially paid</p>
+        </li>
+        <li>
+          <p>STATUS_PAID = 4</p>
+          <p>An invoice which has been fully paid</p>
+        </li>
+        <li>
+          <p>STATUS_CANCELLED = 5</p>
+          <p>When a invoice is cancelled the invoice balance is set to zero and the status updated to Cancelled, the client balance is also adjusted down. If payments have been applied to the invoice these will remain linked to the invoice.</p>
+        </li>
+        <li>
+          <p>STATUS_REVERSED = 6</p>
+          <p>When a invoice has been reversed, the previous payments relationships are unlinked and cannot be restored.</p>
+        </li>
+        <li>
+          <p>STATUS_OVERDUE = -1</p>
+          <p>An invoice which is still payable past its due date</p>
+        </li>
+        <li>
+          <p>STATUS_UNPAID = -2</p>
+          <p>An invoice which is not yet due, but also, not paid.</p>
+        </li>
+      </ul>
+      
   - name: Recurring Invoices
     description: |
       Endpoint definitions for interacting with recurring_invoices.