diff --git a/api-reference/billing/credits.mdx b/api-reference/billing/credits.mdx
new file mode 100644
index 0000000..279d78d
--- /dev/null
+++ b/api-reference/billing/credits.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Get Credits'
+openapi: '/api-reference/openapi/billing.json GET /api/credits'
+---
diff --git a/api-reference/billing/subscription-status.mdx b/api-reference/billing/subscription-status.mdx
new file mode 100644
index 0000000..7943367
--- /dev/null
+++ b/api-reference/billing/subscription-status.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Subscription Status'
+openapi: '/api-reference/openapi/billing.json GET /api/subscription'
+---
diff --git a/api-reference/openapi/billing.json b/api-reference/openapi/billing.json
new file mode 100644
index 0000000..2172a03
--- /dev/null
+++ b/api-reference/openapi/billing.json
@@ -0,0 +1,192 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Recoup API - Billing",
+    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
+    "license": {
+      "name": "MIT"
+    },
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://recoup-api.vercel.app"
+    }
+  ],
+  "paths": {
+    "/api/credits": {
+      "get": {
+        "description": "Returns the credit balance for the authenticated account, automatically resetting the balance when the account is on a refill cycle (monthly cadence or just-activated subscription). Honors both account-level and organization-level Stripe subscriptions when deciding whether the refill should use the pro tier.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Credits retrieved (and refilled if eligible).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CreditsGetResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required or invalid.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BillingErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BillingErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/subscription": {
+      "get": {
+        "description": "Returns whether the authenticated account is on a pro subscription. An account is considered pro if it has an active Stripe subscription itself, or if any of its organizations does.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Pro status retrieved.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubscriptionStatusResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Authentication required or invalid.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BillingErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BillingErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer"
+      },
+      "apiKeyAuth": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "x-api-key",
+        "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
+      }
+    },
+    "schemas": {
+      "CreditsGetResponse": {
+        "type": "object",
+        "required": [
+          "data"
+        ],
+        "properties": {
+          "data": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/CreditsUsage"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "The authenticated account's credits usage row, or null when the account has no credits row yet."
+          }
+        }
+      },
+      "CreditsUsage": {
+        "type": "object",
+        "required": [
+          "account_id",
+          "remaining_credits"
+        ],
+        "properties": {
+          "account_id": {
+            "type": "string",
+            "description": "The Recoup account ID."
+          },
+          "remaining_credits": {
+            "type": "number",
+            "description": "Remaining credits for the account."
+          },
+          "timestamp": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date-time",
+            "description": "ISO timestamp of the last credits refill."
+          }
+        }
+      },
+      "SubscriptionStatusResponse": {
+        "type": "object",
+        "required": [
+          "isPro"
+        ],
+        "properties": {
+          "isPro": {
+            "type": "boolean",
+            "description": "True when the account or any of its organizations has an active Stripe subscription."
+          }
+        }
+      },
+      "BillingErrorResponse": {
+        "type": "object",
+        "required": [
+          "message"
+        ],
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message."
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/docs.json b/docs.json
index 0ea3137..05573ed 100644
--- a/docs.json
+++ b/docs.json
@@ -322,6 +322,13 @@
               "api-reference/subscriptions/sessions-create"
             ]
           },
+          {
+            "group": "Billing",
+            "pages": [
+              "api-reference/billing/credits",
+              "api-reference/billing/subscription-status"
+            ]
+          },
           {
             "group": "Admins",
             "pages": [