diff --git a/src/content/docs/browser-rendering/rest-api/pdf-endpoint.mdx b/src/content/docs/browser-rendering/rest-api/pdf-endpoint.mdx
index 8261c23b3a3bf3..e1377b336c7b70 100644
--- a/src/content/docs/browser-rendering/rest-api/pdf-endpoint.mdx
+++ b/src/content/docs/browser-rendering/rest-api/pdf-endpoint.mdx
@@ -138,7 +138,62 @@ curl -X POST https://api.cloudflare.com/client/v4/accounts/<acccountID>/browser-
   --output "cloudflare.pdf"
 ```
 
+### Customize page headers and footers
+
+You can customize page headers and footers with HTML templates using the `headerTemplate` and `footerTemplate` options. Enable `displayHeaderFooter` to include them in your output. This example generates an A5 PDF with a branded header, a footer message, and page numbering.
+
+```bash
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
+  -H 'Authorization: Bearer <apiToken>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "url": "https://example.com",
+    "pdfOptions": {
+      "format": "a5",
+      "headerTemplate": "<div style=\"font-size: 10px; text-align: center; width: 100%; padding: 5px;\"><span>brand name</span></div>",
+      "displayHeaderFooter": true,
+      "footerTemplate": "<div style=\"color: lightgray; border-top: solid lightgray 1px; font-size: 10px; padding-top: 5px; text-align: center; width: 100%;\"><span>This is a test message</span> - <span class=\"pageNumber\"></span></div>",
+      "margin": {
+        "top": "70px",
+        "bottom": "70px"
+      }
+    }
+  }' \
+  --output "header-footer.pdf"
+```
+
+### Include dynamic placeholders from page metadata
+
+You can include dynamic placeholders such as title, date, pageNumber, and totalPages in the header or footer to display metadata on each page. This example produces an A4 PDF with a company-branded header, current date and title, and page numbering in the footer.
+
+```bash
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
+  -H 'Authorization: Bearer <apiToken>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "url": "https://news.ycombinator.com",
+    "pdfOptions": {
+      "format": "a4",
+      "landscape": false,
+      "printBackground": true,
+      "preferCSSPageSize": true,
+      "displayHeaderFooter": true,
+      "scale": 1.0,
+      "headerTemplate": "<div style=\"width: 100%; font-size: 10px; padding: 10px; text-align: center;\"><div style=\"border-bottom: 1px solid #ddd;\"><span style=\"color: #666;\">Company Name</span> | <span class=\"date\"></span> | <span class=\"title\"></span></div></div>",
+      "footerTemplate": "<div style=\"width: 100%; font-size: 10px; padding: 10px; text-align: center;\"><div style=\"border-top: 1px solid #ddd;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div></div>",
+      "margin": {
+        "top": "100px",
+        "bottom": "80px",
+        "right": "30px",
+        "left": "30px"
+      },
+      "timeout": 30000
+    }
+
 <Render
   file="setting-custom-user-agent"
   product="browser-rendering"
 />
+  }' \
+  --output "paginated.pdf"
+```