Commit 6369d6e148 for woocommerce
commit 6369d6e148d7badfec8206900c257a6df9246c6b
Author: Adrian <adrian.labos@automattic.com>
Date: Sun Feb 22 11:36:10 2026 +0200
Docs: Add Woo Marketplace guidelines (#63174)
* Docs: Add Woo Marketplace billing API documentation and improve styling
- Add comprehensive Billing API for SaaS products documentation with diagrams
- Add custom Proxima Vara font for headings
- Implement GitHub-style circled numbers for ordered lists
- Create custom index page for Settings and config category
- Improve layout consistency across category index pages
- Add sticky table of contents positioning
- Fix footer logo image paths
- Add expandable FAQ sections using HTML details/summary elements
- Hide self-referencing category cards on index pages
- Center footer content and set max-width constraints
* Update docs/woo-marketplace/support-guidelines.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/billing-api-saas.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/product-update-guidelines.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/support-guidelines.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/billing-api-saas.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/billing-api-saas.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/managing-products.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* removes local proxima vara font
* fixes unexpected char error
* fixes marketplace sidebar
* cleans up markdown lint errors
* use mdx for docs containing html
* Update docs/woo-marketplace/content-style-guide.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/content-style-guide.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* removes duplicate h1
* replaces custom css changing document layouts and details
* remove info css override
* Removed the lightbox + coderabbit suggested fixes.
* Update docs/woo-marketplace/index.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/product-page-content-and-assets.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Fix MDX build error and invalid JSON comments
* Remove build-temp directory and revert markdownlint changes
* Update docs/woo-marketplace/billing-api-saas.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/billing-api-saas.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/product-page-content-and-assets.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/product-page-content-and-assets.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/support-guidelines.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/support-guidelines.md
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Fix unclosed JSON code fence in billing-api-saas.mdx
* Update docs/woo-marketplace/billing-api-saas.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update docs/woo-marketplace/billing-api-saas.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Brian Coords <bacoords@gmail.com>
diff --git a/docs/_docu-tools/.gitignore b/docs/_docu-tools/.gitignore
new file mode 100644
index 0000000000..ea6b700d52
--- /dev/null
+++ b/docs/_docu-tools/.gitignore
@@ -0,0 +1 @@
+build-temp/
diff --git a/docs/_docu-tools/docusaurus.config.ts b/docs/_docu-tools/docusaurus.config.ts
index 938164684c..7e5b7a7eeb 100644
--- a/docs/_docu-tools/docusaurus.config.ts
+++ b/docs/_docu-tools/docusaurus.config.ts
@@ -21,6 +21,7 @@ const config: Config = {
projectName: 'woocommerce', // Usually your repo name.
onBrokenLinks: 'throw',
+ onBrokenAnchors: 'warn',
markdown: {
hooks: {
onBrokenMarkdownLinks: 'warn',
@@ -104,6 +105,11 @@ const config: Config = {
sidebarId: 'cliSidebar',
label: 'CLI',
},
+ {
+ type: 'docSidebar',
+ sidebarId: 'marketplaceSidebar',
+ label: 'Marketplace',
+ },
{
href: 'https://developer.woocommerce.com/',
label: 'Blog',
@@ -198,8 +204,8 @@ const config: Config = {
<div class="docusaurus-footer-for-automattic">
<a href="https://automattic.com/">
An
- <img src="img/automattic.svg" alt="Automattic" class="automattic-logo automattic-logo-light" />
- <img src="img/automattic_dark.svg" alt="Automattic" class="automattic-logo automattic-logo-dark" />
+ <img src="/docs/img/automattic.svg" alt="Automattic" class="automattic-logo automattic-logo-light" />
+ <img src="/docs/img/automattic_dark.svg" alt="Automattic" class="automattic-logo automattic-logo-dark" />
Creation</a>
</div>`,
},
diff --git a/docs/_docu-tools/sidebars.ts b/docs/_docu-tools/sidebars.ts
index 88bbf4c7e1..c521225ad6 100644
--- a/docs/_docu-tools/sidebars.ts
+++ b/docs/_docu-tools/sidebars.ts
@@ -28,6 +28,7 @@ const sidebars: SidebarsConfig = {
apiSidebar: [{type: 'autogenerated', dirName: 'apis'}],
extensionsSidebar: [{type: 'autogenerated', dirName: 'extensions'}],
cliSidebar: [{type: 'autogenerated', dirName: 'wc-cli'}],
+ marketplaceSidebar: [{type: 'autogenerated', dirName: 'woo-marketplace'}],
// But you can create a sidebar manually
/*
diff --git a/docs/_docu-tools/src/css/custom.css b/docs/_docu-tools/src/css/custom.css
index 964efdc225..0e62eeb8fe 100644
--- a/docs/_docu-tools/src/css/custom.css
+++ b/docs/_docu-tools/src/css/custom.css
@@ -9,6 +9,12 @@
src: url('/fonts/Inter-VariableFont_slnt,wght.woff2');
}
+@font-face {
+ font-family: 'Proxima Vara';
+ src: url('https://developer.woocommerce.com/wp-content/uploads/sites/2/fonts/Proxima-Nova-Bold.otf') format('opentype');
+ font-display: swap;
+}
+
/* You can override the default Infima variables here. */
:root {
--ifm-color-primary: #720eec; /* WooCommerce Purple 50 */
@@ -22,6 +28,13 @@
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
--ifm-font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif,
'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+ --ifm-heading-font-family: 'Proxima Vara', var(--ifm-font-family-base);
+}
+
+:root details{
+ --ifm-alert-border-color: var(--ifm-color-emphasis-100);
+ --ifm-alert-background-color: var(--ifm-color-emphasis-100);
+ --docusaurus-details-decoration-color: var(--ifm-color-primary-darkest);
}
/* For readability concerns, you should choose a lighter palette in dark mode. */
@@ -78,3 +91,66 @@ html[class*=docs-doc-id-getting-started] .pagination-nav {
html.docs-doc-id-getting-started\/version-control-deployment .pagination-nav .pagination-nav__link--next {
display: none;
}
+
+
+/* ===== FAQ Details/Summary Styling ===== */
+.markdown details summary {
+ font-weight: 700;
+}
+
+/* Hide the self-referencing Woo Marketplace card on the category index page */
+article .col:has(> a[href="/docs/woo-marketplace/"]) {
+ display: none !important;
+}
+
+/* Hide self-referencing Settings and config card on its own index page */
+article .col:has(> a[href="/docs/category/settings-and-config/"]),
+article .col:has(> a[href="/docs/extensions/settings-and-config/"]) {
+ display: none !important;
+}
+
+/* Apply Proxima Vara to all headings */
+h1, h2, h3, h4, h5, h6,
+.markdown h1, .markdown h2, .markdown h3, .markdown h4, .markdown h5, .markdown h6 {
+ font-family: var(--ifm-heading-font-family);
+ font-weight: 600;
+ letter-spacing: -0.025em;
+}
+
+/* GitHub-style ordered list with circled numbers */
+.markdown ol {
+ list-style: none;
+ counter-reset: item;
+ padding-left: 0;
+}
+
+.markdown ol > li {
+ counter-increment: item;
+ position: relative;
+ padding-left: 2.5rem;
+ margin-bottom: 1rem;
+}
+
+.markdown ol > li::before {
+ content: counter(item);
+ position: absolute;
+ left: 0;
+ top: 0.125rem;
+ width: 1.5rem;
+ height: 1.5rem;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ background-color: #eaeef2;
+ color: #1f2328;
+ border-radius: 50%;
+ font-weight: 600;
+ font-size: 0.75rem;
+ flex-shrink: 0;
+}
+
+/* Dark mode colors for ordered list circles */
+html[data-theme='dark'] .markdown ol > li::before {
+ background-color: #343942;
+ color: #e6edf3;
+}
diff --git a/docs/_docu-tools/src/js/sidebar-filters.js b/docs/_docu-tools/src/js/sidebar-filters.js
index f20aad086b..8763dd796c 100644
--- a/docs/_docu-tools/src/js/sidebar-filters.js
+++ b/docs/_docu-tools/src/js/sidebar-filters.js
@@ -1,16 +1,19 @@
const HIDDEN_DOC_IDS = [
- 'apis', // doc id or slug, relative to docs root
- 'cli',
- 'extensions',
+ 'apis', // doc id or slug, relative to docs root
+ 'cli',
+ 'extensions',
+ 'woo-marketplace',
];
-export function filterSidebarItems(items) {
- return items
- .filter(item => {
- // Hide by doc id
- if (item.type === 'category' && HIDDEN_DOC_IDS.includes(item.customProps?.id)) {
- return false;
- }
- return true;
- });
-}
\ No newline at end of file
+export function filterSidebarItems( items ) {
+ return items.filter( ( item ) => {
+ // Hide by doc id
+ if (
+ item.type === 'category' &&
+ HIDDEN_DOC_IDS.includes( item.customProps?.id )
+ ) {
+ return false;
+ }
+ return true;
+ } );
+}
diff --git a/docs/extensions/settings-and-config/_category_.json b/docs/extensions/settings-and-config/_category_.json
index 5577745ba3..ea92b575a9 100644
--- a/docs/extensions/settings-and-config/_category_.json
+++ b/docs/extensions/settings-and-config/_category_.json
@@ -1,8 +1,4 @@
{
"label": "Settings and config",
- "position": 3,
- "link": {
- "type": "generated-index",
- "title": "Settings and config"
- }
+ "position": 3
}
diff --git a/docs/extensions/settings-and-config/index.mdx b/docs/extensions/settings-and-config/index.mdx
new file mode 100644
index 0000000000..8f3bed460d
--- /dev/null
+++ b/docs/extensions/settings-and-config/index.mdx
@@ -0,0 +1,9 @@
+---
+title: Settings and config
+sidebar_position: 0
+sidebar_class_name: category-index
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
diff --git a/docs/woo-marketplace/_category_.json b/docs/woo-marketplace/_category_.json
new file mode 100644
index 0000000000..f9d3c741a9
--- /dev/null
+++ b/docs/woo-marketplace/_category_.json
@@ -0,0 +1,11 @@
+{
+ "label": "Woo Marketplace",
+ "customProps" : {
+ "id" : "woo-marketplace"
+ },
+ "link": {
+ "type": "generated-index",
+ "title": "Woo Marketplace",
+ "description": "Documentation for developers publishing extensions, themes, and integrations on the Woo Marketplace."
+ }
+}
diff --git a/docs/woo-marketplace/_media/Screenshot20on202022-04-2920at2014-15-53.png b/docs/woo-marketplace/_media/Screenshot20on202022-04-2920at2014-15-53.png
new file mode 100644
index 0000000000..3e3df93f92
Binary files /dev/null and b/docs/woo-marketplace/_media/Screenshot20on202022-04-2920at2014-15-53.png differ
diff --git a/docs/woo-marketplace/_media/feature-requests.png b/docs/woo-marketplace/_media/feature-requests.png
new file mode 100644
index 0000000000..9d83f5c76b
Binary files /dev/null and b/docs/woo-marketplace/_media/feature-requests.png differ
diff --git a/docs/woo-marketplace/_media/highlight-card-example.png b/docs/woo-marketplace/_media/highlight-card-example.png
new file mode 100644
index 0000000000..8616aae596
Binary files /dev/null and b/docs/woo-marketplace/_media/highlight-card-example.png differ
diff --git a/docs/woo-marketplace/_media/image-1.png b/docs/woo-marketplace/_media/image-1.png
new file mode 100644
index 0000000000..0cf0bc216c
Binary files /dev/null and b/docs/woo-marketplace/_media/image-1.png differ
diff --git a/docs/woo-marketplace/_media/image-85.png b/docs/woo-marketplace/_media/image-85.png
new file mode 100644
index 0000000000..fd22f57c05
Binary files /dev/null and b/docs/woo-marketplace/_media/image-85.png differ
diff --git a/docs/woo-marketplace/_media/image-86.png b/docs/woo-marketplace/_media/image-86.png
new file mode 100644
index 0000000000..159607daf9
Binary files /dev/null and b/docs/woo-marketplace/_media/image-86.png differ
diff --git a/docs/woo-marketplace/_media/image-87.png b/docs/woo-marketplace/_media/image-87.png
new file mode 100644
index 0000000000..9e7c2e85b6
Binary files /dev/null and b/docs/woo-marketplace/_media/image-87.png differ
diff --git a/docs/woo-marketplace/_media/image.png b/docs/woo-marketplace/_media/image.png
new file mode 100644
index 0000000000..f7a5e56b64
Binary files /dev/null and b/docs/woo-marketplace/_media/image.png differ
diff --git a/docs/woo-marketplace/_media/image_1d1a86.png b/docs/woo-marketplace/_media/image_1d1a86.png
new file mode 100644
index 0000000000..cd741b23c8
Binary files /dev/null and b/docs/woo-marketplace/_media/image_1d1a86.png differ
diff --git a/docs/woo-marketplace/_media/image_2a07b1.png b/docs/woo-marketplace/_media/image_2a07b1.png
new file mode 100644
index 0000000000..d6b588b6d4
Binary files /dev/null and b/docs/woo-marketplace/_media/image_2a07b1.png differ
diff --git a/docs/woo-marketplace/_media/image_35074a.png b/docs/woo-marketplace/_media/image_35074a.png
new file mode 100644
index 0000000000..6e1162dac9
Binary files /dev/null and b/docs/woo-marketplace/_media/image_35074a.png differ
diff --git a/docs/woo-marketplace/_media/image_5fb815.png b/docs/woo-marketplace/_media/image_5fb815.png
new file mode 100644
index 0000000000..0263016f49
Binary files /dev/null and b/docs/woo-marketplace/_media/image_5fb815.png differ
diff --git a/docs/woo-marketplace/_media/image_6326de.png b/docs/woo-marketplace/_media/image_6326de.png
new file mode 100644
index 0000000000..f194925ba2
Binary files /dev/null and b/docs/woo-marketplace/_media/image_6326de.png differ
diff --git a/docs/woo-marketplace/_media/image_65ae27.png b/docs/woo-marketplace/_media/image_65ae27.png
new file mode 100644
index 0000000000..958b94126b
Binary files /dev/null and b/docs/woo-marketplace/_media/image_65ae27.png differ
diff --git a/docs/woo-marketplace/_media/image_85894c.png b/docs/woo-marketplace/_media/image_85894c.png
new file mode 100644
index 0000000000..5757506515
Binary files /dev/null and b/docs/woo-marketplace/_media/image_85894c.png differ
diff --git a/docs/woo-marketplace/_media/image_937e91.png b/docs/woo-marketplace/_media/image_937e91.png
new file mode 100644
index 0000000000..6847d25ad5
Binary files /dev/null and b/docs/woo-marketplace/_media/image_937e91.png differ
diff --git a/docs/woo-marketplace/_media/image_a97955.png b/docs/woo-marketplace/_media/image_a97955.png
new file mode 100644
index 0000000000..082bdfde46
Binary files /dev/null and b/docs/woo-marketplace/_media/image_a97955.png differ
diff --git a/docs/woo-marketplace/_media/image_b42b52.png b/docs/woo-marketplace/_media/image_b42b52.png
new file mode 100644
index 0000000000..02d778a9c9
Binary files /dev/null and b/docs/woo-marketplace/_media/image_b42b52.png differ
diff --git a/docs/woo-marketplace/_media/image_b46eda.png b/docs/woo-marketplace/_media/image_b46eda.png
new file mode 100644
index 0000000000..6e1162dac9
Binary files /dev/null and b/docs/woo-marketplace/_media/image_b46eda.png differ
diff --git a/docs/woo-marketplace/_media/image_f55706.png b/docs/woo-marketplace/_media/image_f55706.png
new file mode 100644
index 0000000000..fb8eb0e279
Binary files /dev/null and b/docs/woo-marketplace/_media/image_f55706.png differ
diff --git a/docs/woo-marketplace/_media/manage-products-analytics.png b/docs/woo-marketplace/_media/manage-products-analytics.png
new file mode 100644
index 0000000000..e4ed546f7a
Binary files /dev/null and b/docs/woo-marketplace/_media/manage-products-analytics.png differ
diff --git a/docs/woo-marketplace/_media/manage-products-documentation.png b/docs/woo-marketplace/_media/manage-products-documentation.png
new file mode 100644
index 0000000000..a538645316
Binary files /dev/null and b/docs/woo-marketplace/_media/manage-products-documentation.png differ
diff --git a/docs/woo-marketplace/_media/manage-products-overview.png b/docs/woo-marketplace/_media/manage-products-overview.png
new file mode 100644
index 0000000000..bacbec0d48
Binary files /dev/null and b/docs/woo-marketplace/_media/manage-products-overview.png differ
diff --git a/docs/woo-marketplace/_media/product-gallery-upload.png b/docs/woo-marketplace/_media/product-gallery-upload.png
new file mode 100644
index 0000000000..3e1a43ae8b
Binary files /dev/null and b/docs/woo-marketplace/_media/product-gallery-upload.png differ
diff --git a/docs/woo-marketplace/_media/product-icon-guidelines.png b/docs/woo-marketplace/_media/product-icon-guidelines.png
new file mode 100644
index 0000000000..7966aabcef
Binary files /dev/null and b/docs/woo-marketplace/_media/product-icon-guidelines.png differ
diff --git a/docs/woo-marketplace/_media/product-page-edit.png b/docs/woo-marketplace/_media/product-page-edit.png
new file mode 100644
index 0000000000..20e0fa9729
Binary files /dev/null and b/docs/woo-marketplace/_media/product-page-edit.png differ
diff --git a/docs/woo-marketplace/_media/product-update-filename.png b/docs/woo-marketplace/_media/product-update-filename.png
new file mode 100644
index 0000000000..07aa27773b
Binary files /dev/null and b/docs/woo-marketplace/_media/product-update-filename.png differ
diff --git a/docs/woo-marketplace/_media/product-update-test-results.png b/docs/woo-marketplace/_media/product-update-test-results.png
new file mode 100644
index 0000000000..a1ab679440
Binary files /dev/null and b/docs/woo-marketplace/_media/product-update-test-results.png differ
diff --git a/docs/woo-marketplace/_media/product-update-versions.png b/docs/woo-marketplace/_media/product-update-versions.png
new file mode 100644
index 0000000000..c796638925
Binary files /dev/null and b/docs/woo-marketplace/_media/product-update-versions.png differ
diff --git a/docs/woo-marketplace/_media/replace-zip-file.png b/docs/woo-marketplace/_media/replace-zip-file.png
new file mode 100644
index 0000000000..a4eb492af3
Binary files /dev/null and b/docs/woo-marketplace/_media/replace-zip-file.png differ
diff --git a/docs/woo-marketplace/_media/reviews-ratings.png b/docs/woo-marketplace/_media/reviews-ratings.png
new file mode 100644
index 0000000000..6925309f93
Binary files /dev/null and b/docs/woo-marketplace/_media/reviews-ratings.png differ
diff --git a/docs/woo-marketplace/_media/saas-billing-contract-flow.png b/docs/woo-marketplace/_media/saas-billing-contract-flow.png
new file mode 100644
index 0000000000..39d4e351d9
Binary files /dev/null and b/docs/woo-marketplace/_media/saas-billing-contract-flow.png differ
diff --git a/docs/woo-marketplace/_media/submission-form.png b/docs/woo-marketplace/_media/submission-form.png
new file mode 100644
index 0000000000..00c791c1de
Binary files /dev/null and b/docs/woo-marketplace/_media/submission-form.png differ
diff --git a/docs/woo-marketplace/_media/submission-support.png b/docs/woo-marketplace/_media/submission-support.png
new file mode 100644
index 0000000000..7b00b6f0f5
Binary files /dev/null and b/docs/woo-marketplace/_media/submission-support.png differ
diff --git a/docs/woo-marketplace/_media/submission-test-failures.png b/docs/woo-marketplace/_media/submission-test-failures.png
new file mode 100644
index 0000000000..0e70f42f53
Binary files /dev/null and b/docs/woo-marketplace/_media/submission-test-failures.png differ
diff --git a/docs/woo-marketplace/_media/submit-product-type.png b/docs/woo-marketplace/_media/submit-product-type.png
new file mode 100644
index 0000000000..660ec10b7a
Binary files /dev/null and b/docs/woo-marketplace/_media/submit-product-type.png differ
diff --git a/docs/woo-marketplace/_media/subscription-details.png b/docs/woo-marketplace/_media/subscription-details.png
new file mode 100644
index 0000000000..be14d062ad
Binary files /dev/null and b/docs/woo-marketplace/_media/subscription-details.png differ
diff --git a/docs/woo-marketplace/_media/support-email-field.png b/docs/woo-marketplace/_media/support-email-field.png
new file mode 100644
index 0000000000..9da5677d24
Binary files /dev/null and b/docs/woo-marketplace/_media/support-email-field.png differ
diff --git a/docs/woo-marketplace/_media/vendor-logo-profile.png b/docs/woo-marketplace/_media/vendor-logo-profile.png
new file mode 100644
index 0000000000..4e6be20769
Binary files /dev/null and b/docs/woo-marketplace/_media/vendor-logo-profile.png differ
diff --git a/docs/woo-marketplace/_media/vendor-more-settings.png b/docs/woo-marketplace/_media/vendor-more-settings.png
new file mode 100644
index 0000000000..f250a769a9
Binary files /dev/null and b/docs/woo-marketplace/_media/vendor-more-settings.png differ
diff --git a/docs/woo-marketplace/_media/vendor-store-settings-1.png b/docs/woo-marketplace/_media/vendor-store-settings-1.png
new file mode 100644
index 0000000000..382a2498ad
Binary files /dev/null and b/docs/woo-marketplace/_media/vendor-store-settings-1.png differ
diff --git a/docs/woo-marketplace/_media/vendor-tools-analytics.png b/docs/woo-marketplace/_media/vendor-tools-analytics.png
new file mode 100644
index 0000000000..7a3b3c6471
Binary files /dev/null and b/docs/woo-marketplace/_media/vendor-tools-analytics.png differ
diff --git a/docs/woo-marketplace/_media/webhook.png b/docs/woo-marketplace/_media/webhook.png
new file mode 100644
index 0000000000..8724e7faed
Binary files /dev/null and b/docs/woo-marketplace/_media/webhook.png differ
diff --git a/docs/woo-marketplace/billing-api-saas.mdx b/docs/woo-marketplace/billing-api-saas.mdx
new file mode 100644
index 0000000000..e5f4bb39dc
--- /dev/null
+++ b/docs/woo-marketplace/billing-api-saas.mdx
@@ -0,0 +1,438 @@
+---
+sidebar_position: 10
+sidebar_label: 'Billing API for SaaS products'
+---
+
+# Billing API for SaaS products
+
+## Introduction
+
+Woo Marketplace's Billing API enables you to sell subscriptions for your SaaS app on the Woo Marketplace, via our in-house billing and subscription system. Woo Marketplace's Billing API supports recurring payments, free trials, upgrades, downgrades, and one-time payments.
+
+Follow this guide to get your billing powered by WooCommerce's world-class billing system, and listed on the Woo Marketplace. You can integrate the Billing API with your existing sign-up and purchase flows, or create a different experience specifically for customers coming from WooCommerce.com.
+
+[View API Documentation on Apiary](https://woocommercecomsaasbillingapi.docs.apiary.io/)
+
+## Set up your SaaS App
+
+To complete integrating WooCommerce Billing into your SaaS app, you'll need a sandbox and the API reference. The various API flows are described below.
+
+To get started, please [submit your product](https://woocommerce.com/document/submitting-your-product-to-the-woo-marketplace/) to the WooCommerce Marketplace. Include details about your product and upload a zip file to test whether your product utilizes a WordPress plugin to connect to your app. We will review your product to determine if it is a good fit before granting sandbox access.
+
+### Sandbox for testing
+
+The integration with the SaaS Billing API should be implemented and tested inside the sandbox, before being opened up for production usage. The differences between production and sandbox are the domain (sandbox.woocommerce.com) and the API credentials. Switching from sandbox to production should just be a matter of changing the domain name, API key and secret.
+
+**Sandbox domain:** `https://sandbox.woocommerce.com/`
+**Base URL for API on the sandbox:** `https://sandbox.woocommerce.com/wp-json/wccom/billing/1.0/`
+
+### Local Development
+
+There are a couple of things to consider when developing locally:
+
+1. The `return_url` API parameter doesn't accept `localhost` as a value. You can map the localhost IP to a domain in your `hosts` file and use that instead. Example: `127.0.0.1 app.local`
+
+2. Your app must be publicly accessible for webhook calls to reach it. One option is to use a service such as ngrok.com to expose it to the internet. You don't need the `hosts` file mapping in this case. You'll use the generated public URL instead.
+
+### SaaS application settings
+
+Once your submission is advanced from Business Review, we will create an app for you on our sandbox to complete the integration. From this sandbox vendor account, you can view and edit your SaaS application settings. After setup, you'll be able to log in to your vendor dashboard and access your SaaS application settings.
+
+Navigate to **SaaS Apps** to view the list of applications. You'll likely have only one.
+
+
+
+To access the application's settings, click on the API key. On the settings page, you can view and copy your API key and secret, generate a new API key & secret pair, and add/edit/remove the webhook URL associated with your application.
+
+
+
+### API reference
+
+**API reference documentation:** [https://woocommercecomsaasbillingapi.docs.apiary.io/](https://woocommercecomsaasbillingapi.docs.apiary.io/)
+
+You can download the OpenAPI specification file from the documentation link above and use it with any tool that supports this standard. For example, you can import it into Postman to get a ready-to-use collection of requests.
+
+Please note that all paths in the reference documentation are relative to the base URL. For example, the `/subscriptions` endpoint will be resolved into the full URL `https://woocommerce.com/wp-json/wccom/billing/1.0/subscriptions`.
+
+### Authentication
+
+Each vendor application is issued a set of credentials (API key and secret) during onboarding. To authenticate API requests, you need to use the [Basic](https://tools.ietf.org/html/rfc7617) authentication method and pass the following HTTP header with your request:
+
+`Authorization: Basic base64encode(api_key:api_secret)`
+
+Here's an example of a POST request to the /subscriptions endpoint to initiate a plan purchase (please replace ENCODED_KEY_SECRET_STRING with your own secret key):
+
+```bash
+curl --request POST \
+ --url https://sandbox.woocommerce.com/wp-json/wccom/billing/1.0/subscriptions \
+ --header 'Authorization: Basic ENCODED_KEY_SECRET_STRING' \
+ --header 'Content-Type: application/json' \
+ --data '{"name": "test plan", "price": 199.99, "billing_period": "year", "billing_interval": 1, "return_url": "https://example.com"}'
+```
+
+### Technical review
+
+Your integration with the WooCommerce.com billing system goes through a technical review before the SaaS product can be listed in the marketplace. Once your integration with the WooCommerce.com sandbox is ready, please send us a link where we can test it so we can confirm everything's working great. It doesn't need to be your live environment, but it should be a working example that can be accessed by our technical team for review.
+
+## Creating a Subscription
+
+
+
+Merchants need to go through the contract sign-up flow to acquire an active subscription to your SaaS plan.
+
+### 1. Merchant clicks a link to purchase a plan
+
+Either via a link on your website, or from the Woo Marketplace, merchants follow a link to purchase your paid SaaS plan.
+
+The customer is then directed to WooCommerce.com to pay for their purchase.
+
+Before purchasing, it is useful to have the customer sign up for an account. This account can then be linked in your SaaS app to the paid purchase, once confirmed.
+
+Please ensure that customers coming from WooCommerce.com are distinguished from others: the only available payment method for them is WooCommerce.com's billing system.
+
+If there are several plans available in your application, you can have the merchant choose one before initiating the purchase.
+
+You may also decide to not show the merchant anything and initiate the purchase immediately, as described in the next step.
+
+### 2. Initiate the purchase
+
+Make an **API call to WooCommerce.com's Billing API** with the subscription plan information. You'll receive a **confirmation URL** in the response.
+
+Typical [subscription plan information](https://woocommercecomsaasbillingapi.docs.apiary.io/#reference/0/subscriptions/post) includes:
+
+- the plan name
+- price
+- billing period
+- billing interval
+- trial period (optional)
+- trial length (optional)
+- Return URL
+
+The return URL is a URL in your application where we'll redirect the merchant after they complete the purchase on WooCommerce.com.
+
+The confirmation URL is unique on WooCommerce.com. Your application needs to redirect the merchant to it to confirm and pay for the subscription.
+
+The response also contains a unique subscription contract ID in the form of a UUID, which you can use to associate the subscription in our systems with your application's internal customer ID.
+
+If you initiate the purchase immediately when the customer lands on the application, and then redirect to WooCommerce.com confirmation URL during the same request, the operation will take less than a few seconds to complete. The experience for the merchant is seamless, as if they never left WooCommerce.com.
+
+### 3. Merchant confirms the purchase
+
+The application redirects the merchant to the confirmation URL on WooCommerce.com, where they'll confirm and pay for the subscription. The merchant goes through a familiar checkout experience, with all the necessary payment information pre-filled if they've purchased from WooCommerce.com before.
+
+Note: The application must associate a successful purchase with a user only after the user has given "consent" and completed the entire checkout flow on WooCommerce.com. The application must account for interruptions during the purchase flow, e.g app crashes, connection drops, power outages, etc. This also includes if the user is redirected to WooCommerce.com checkout and then navigates back to your application instead of confirming the purchase. The application should not update with the plan information until the user confirms their purchase on WooCommerce.com.
+
+### 4. Merchant is redirected to your application
+
+After the merchant confirms and completes the purchase, they are redirected to the return URL you provided in the initiation step. If you haven't already signed up the merchant, you can do it in this phase. The return URL passes the contract ID in a GET parameter, so you can associate it with your internal customer ID.
+
+WooCommerce.com also makes a webhook call to your webhook URL with the saas_billing_contract.activated topic. This signals that the contract was confirmed and the payment was successful.
+
+## Free Trials
+
+Our billing system optionally supports free trials. Free trials help reduce the number of refunds and cancelations by allowing merchants to see if the service is a good fit for them before purchasing. You can specify the trial period during the subscription signup initiation phase. Pass the trial_period and trial_length parameters during the initial API call.
+
+We automatically charge the subscription price when the trial period ends if the merchant didn't cancel the subscription. You will get a webhook call with the saas_billing_contract.renewed topic and the contract details. Please review the webhook section for more information.
+
+## Switching between subscriptions
+
+The Billing API supports subscription upgrades, downgrades, and crossgrades. Use this feature to change the billing interval (ex. monthly to yearly) or switch to a subscription with a higher, lower, or equal price per day.
+
+### The typical flow
+
+1. **Initiate the switch**
+ Initiate a subscription switch using the POST /subscriptions/\{contractID\} endpoint. Provide all of the necessary information, as described in the API documentation. There will be a confirmation_url parameter in the response. Redirect the merchant to this URL so they can confirm the switch and pay any prorated amount. Please see the API documentation for more details.
+
+2. **Merchant confirms the switch**
+ The merchant lands on WooCommerce.com to confirm the switch. If a prorated amount is due, or if one was passed in the previous step, they'll need to pay to complete the switch. If the new subscription is cheaper (a downgrade) they'll be credited for the difference by having their subscription extended.
+
+3. **Merchant is redirected to your application**
+ Once the merchant confirms the switch, the subscription is updated on WooCommerce.com and they are redirected to the return URL you provided in the initiation phase. The contract id is appended to this URL as a GET parameter. This is a good time to update their subscription in your systems. WooCommerce.com also makes a server-to-server call to your webhook URL with the saas_billing_contract.updated topic. The webhook request body contains the contract object. Check out the webhook section for more details.
+
+### How proration works
+
+The Billing API automatically adjusts the next payment date and charges any prorated fee by looking at the cost per day of the old and new subscriptions.
+
+#### Downgrade
+
+The system compensates the merchant for the prepaid amount by pushing the next payment date into the future. It multiplies the price per day of the old subscription with the number of days left in the current billing cycle. It uses this amount to cover as many days as possible at the new subscription price per day. The merchant doesn't pay a prorated fee when they downgrade their subscription.
+
+#### Example: Downgrade proration
+
+A merchant purchased a $100/year subscription on the 1st of January. They downgrade to a $6/month subscription two months into the billing cycle. As a result, the system pushes the next payment date to the 19th of April of the following year.
+
+- Price/day of the old subscription → $0.27/day ( $100 / 365 days )
+- Price/day of the new subscription → $0.2/day ( $6 / 30 days )
+- Total days spent on old plan → 59 days ( 31 in Jan + 28 in Feb )
+- Days remaining on old plan → 306 ( 365 – 59 )
+- Total prepaid credit remaining → $82.62 ( 306 days left * $0.27/day )
+- The number of days the credit can cover for the new plan → 414 days ( $82.62 / $0.2 = 413.1 rounded up to 414 )
+- Next payment date → April 19th, 2023 ( March 1st + 414 days )
+
+#### Crossgrade
+
+It's the simplest type of switch to understand. The price per day doesn't change in this case. The system doesn't change the next payment date or charge a prorated fee.
+
+#### Example: Crossgrade equal price/day
+
+A merchant switches from a $10/month subscription to a $120/year one (or vice versa). The price per day is the same, $0.33. The subscription will renew after the prepaid month is up at $120 for the following year.
+
+### Upgrade
+
+#### Upgrading to a subscription with a shorter billing cycle
+
+The system doesn't charge the merchant a prorated fee when they upgrade to a subscription with a shorter billing cycle. It brings the next payment date closer to the upgrade date, depending on the nr. of days spent in the old billing cycle. The next payment date can be as early as the upgrade date.
+
+#### Example: Upgrade to shorter billing cycle
+
+A merchant subscribes to a $10/month subscription. Twelve days into the billing cycle, they upgrade to a $7/week subscription. Notice the billing cycle of the new subscription is shorter, so no prorated fee is charged.
+
+The system adjusts the next payment date. It multiplies the days spent in the old billing cycle, 12, with the new subscription price per day of $1. The resulting amount, $12, is higher than the new subscription price of $7. So it charges the merchant $7 for renewal and sets the next payment date a week into the future. The same applies when the amount is equal to the new subscription price.
+
+When the amount is lower, it compensates for the difference by extending the renewal date with the number of days covered by the resulting amount, counting from the upgrade date.
+
+#### Upgrading to a subscription with an equal or longer billing cycle
+
+The system charges a prorated fee when the merchant upgrades to a subscription with a billing cycle equal to or longer than the old one. It calculates the prorated fee by multiplying the nr. of days remaining in the current subscription's billing cycle with the price per day difference between the two subscriptions. The next payment date doesn't change in this case.
+
+#### Example: Upgrade to equal or longer billing cycle
+
+The merchant subscribes to a $10/month subscription. Fifteen days into the billing cycle, they upgrade to a $150/year subscription. Note that the billing cycle is longer in this case, so a prorated fee is due. The cost per day for the old and new subscriptions is approximately $0.33 and $0.41, respectively. The price difference between the two is $0.08 per day. There are 15 days left in the current billing cycle, so the system charges a proration fee of $0.08 x 15 days, resulting in a $1.20 upgrade cost. The subscription will renew after those 15 days at $150/year.
+
+## One-time charges
+
+The Billing API also supports one-time charges. This feature can be used to charge merchants for things that are not renewable. For example, say you're offering email delivery services and you want to offer credit packs to your customers to use during promotions, or whenever they need an extra boost. These don't incur recurring charges and can be purchased as needed. The typical one-time charge flow is very similar to the subscription signup flow and is described below.
+
+### 1. Initiate the charge
+
+Initiate a charge by calling the POST /charges endpoint. Provide the necessary information as described in the API documentation. The response will have a confirmation_url. Redirect the merchant to this URL. See the API documentation for more details.
+
+### 2. Merchant confirms the charge
+
+The merchant lands on WooCommerce.com and confirms the charge details. Once they complete the payment, they're redirected to the return URL you provided in the initiation phase.
+
+### 3. Merchant is redirected to your application
+
+The merchant is redirected back to you via the return URL. The charge contract id is appended to this URL as a GET parameter. This is a good time to add the product they paid for to their account. WooCommerce.com also makes a server-to-server call to your webhook URL with the saas_billing_contract.activated topic. The webhook request body will have the charge object. Please review the webhook section for more details.
+
+## Renewals
+
+WooCommerce.com handles renewals automatically. It provides a hands-off experience for merchants, like all other products sold through the Marketplace.
+
+Your application needs to support automatic renewals. Please make sure the merchant doesn't have to take any manual action on your end for the renewal to occur.
+
+Use the webhook system to get notifications about renewals. We'll notify you about successful and failed renewals alike. If a renewal fails, we'll place the subscription in the paused state and notify you. We'll make further attempts to renew the subscription in the following days and notify you if we succeed. We don't delete expired subscriptions. Feel free to cancel an expired subscription at your discretion.
+
+WooCommerce.com will email merchants before and on the day of the renewal. Feel free to send any renewal-related communication of your own to them as well.
+
+## Refunds
+
+Merchants can request a refund for all of the following types of SaaS billing orders. There is no limit on the number of days after payment during which the refund can be requested:
+
+- Subscription contract sign-up
+- Subscription plan upgrade
+- Subscription renewal
+- One-time charge
+
+As a vendor, you will receive an email notification when a refund is requested for any of your SaaS products. You can review all the pending refund requests in your vendor dashboard by going to the "SaaS Apps -> Pending Refunds" page.
+
+
+
+You can review each request, contact the merchant if you want to discuss the reasons for their refund request, and finally decide to either Approve or Reject the request. You need to provide a reason if you are rejecting a refund request.
+
+If you approve a refund request for a SaaS billing order, the underlying SaaS contract will also be canceled.
+
+WooCommerce.com also makes server-to-server calls to your webhook URL with the saas_billing_contract.refunded and saas_billing_contract.canceled topics. The webhook request body contains the contract object. Check out the webhook section for more details.
+
+## Subscription cancelations
+
+Merchants must be able to cancel a subscription from your application, so please make sure that feature is implemented. There is a dedicated endpoint in the HTTP API to cancel contracts. Please review our API documentation for the DELETE endpoints.
+
+If the merchant cancels the subscription, the expectation is that they'll benefit from their current plan until the end of the prepaid period.
+
+For example, if a yearly subscription is canceled after 3 months the merchant will benefit from your service for the remaining 9 months. What you do with the merchant account in your application after they cancel their subscription is up to you.
+
+## Webhooks
+
+We send notifications to your application about important events in the lifecycle of your subscriptions. The events are listed below and always include a snapshot of the contract in the request's body and reflects the state of the contract at the time of the call.
+
+
+
+Webhook calls expect a successful HTTP code in response. Otherwise, the delivery is considered to have failed. A retry system will attempt to call your webhook endpoint again, up to five times, increasing the pause between each retry. Be sure to have monitoring in place for your webhook endpoint. There's no other way to get updates on some of the contract events. A typical request body payload looks like this:
+
+**Example: Subscription contract payload**
+
+```json
+{
+ "subscription":{
+ "id":"4733be9c-8d6c-4a78-a4f8-268a64770985",
+ "status":"active",
+ "next_payment_date":"2022-08-24 14:13:42",
+ "end_date":null,
+ "billing_intents":[
+ {
+ "id":1,
+ "status":"completed",
+ "payload":{},
+ "created_at":"2022-06-24 14:13:35",
+ "updated_at":"2022-06-24 14:14:06"
+ }
+ ],
+ "transactions":[
+ {
+ "id":1,
+ "billing_intent_id":1,
+ "created_at":"2022-06-24 14:13:42",
+ "completed_at":"2022-06-24 14:14:03",
+ "amount":89.5,
+ "amount_refunded":0,
+ "url":"https://woocommerce.com/my-account/view-order/172"
+ },
+ {
+ "id":2,
+ "billing_intent_id":1,
+ "created_at":"2022-07-24 14:13:42",
+ "completed_at":"2022-07-24 14:14:23",
+ "amount":89.5,
+ "amount_refunded":0,
+ "url":"https://woocommerce.com/my-account/view-order/179"
+ }
+ ]
+ }
+}
+```
+
+**Example: One-time charge contract payload**
+
+```json
+{
+ "charge":{
+ "id":"68f28fbe-8510-4369-8f80-c5a5380c85db",
+ "status":"active",
+ "billing_intents":[
+ {
+ "id":1,
+ "status":"completed",
+ "payload":{},
+ "created_at":"2022-07-01 10:21:24",
+ "updated_at":"2022-07-01 10:22:39"
+ }
+ ],
+ "transactions":[
+ {
+ "id":1,
+ "billing_intent_id":1,
+ "created_at":"2022-07-01 10:21:31",
+ "completed_at":"2022-07-01 10:22:39",
+ "amount":89.5,
+ "amount_refunded":0,
+ "url":"https://woocommerce.com/my-account/view-order/199"
+ }
+ ]
+ }
+}
+```
+
+As you can see, we don't share merchant information via webhooks. They are primarily used to notify you, the vendor, about various changes in the lifetime of a contract. The request payload includes the contract ID, status, and any billing intents. The event that triggers the webhook call is delivered as a topic and can be found in the x-wc-webhook-topic request header.
+
+The topics that are currently available are:
+
+- **saas_billing_contract.activated** – This event signals a merchant successfully checked out with a subscription or one-time charge. This indicates the contract is paid for and active. You can use this event to activate their plan or feature.
+- **saas_billing_contract.updated** – This event is specific to subscriptions. It's fired when a merchant successfully confirms a plan upgrade or downgrade and pays the prorated amount (if any). The contract status is active. You can use this event to update their plan in your system.
+- **saas_billing_contract.renewed** – This event is specific to subscriptions and is fired when a successful subscription renewal occurs. This event indicates that the merchant was successfully charged the renewal amount. The contract status is active.
+- **saas_billing_contract.paused** – This event is specific to subscriptions and is fired when a subscription contract status becomes paused. This happens when a renewal is due, but for whatever reason, we couldn't process it. Issues with the payment method usually cause this, but we have systems to retry renewals. The subscription will eventually be paid for and trigger a renewed event or expire, in which case a canceled event will be triggered. You can use this event to reach out to the customer if you wish.
+- **saas_billing_contract.canceled** – This one is fired when a subscription or one-time charge is canceled. Use this to deactivate a merchant's plan or feature based on the end of the prepaid term date. Please note that charges can only be canceled before the merchant confirms them. As the vendor, you can cancel contracts using the corresponding DELETE call described in the API documentation. Please note that when you cancel the contract, the customer is entitled to continue using the plan until the prepaid period ends. The date is included in the contract payload in the body of the webhook call. Don't worry. We'll send a follow-up event when the prepaid period ends. The contract or charge included with the webhook call will have the canceled status.
+- **saas_billing_contract.prepaid_term_ended** – This follow-up event is fired when the prepaid period for a canceled contract is reached. Use this to deactivate a merchant's plan or feature.
+- **saas_billing_contract.refunded** – This one is fired when a subscription or one-time charge is refunded. You can find the refunded amount by inspecting the amount_refunded field on the latest transaction (from the transactions property of the subscription or one-time charge).
+
+The request body payload is signed with the API secret, and the signature is included with the X-WC-Webhook-Signature request header. You can use the signature to confirm the integrity of the payload.
+
+An example of PHP code to make the validation:
+
+```php
+$api_secret = 'YOUR_SECRET';
+$payload = file_get_contents( 'php://input' );
+$provided_signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
+$valid_signature = base64_encode( hash_hmac( 'sha256', $payload, $api_secret, true ) );
+
+if (hash_equals($valid_signature, $provided_signature)) {
+ $request_origin_confirmed = true;
+} else {
+ $request_origin_confirmed = false;
+}
+```
+
+To enable webhook notifications, you need to provide a URL in your application that accepts webhook requests. The URL must be publicly accessible, with no authentication or IP whitelisting. We currently support one webhook endpoint per application. You can add, update, or remove the application's webhook URL in your SaaS application settings.
+
+### SaaS webhook testing tool
+
+This tool is only available on the sandbox to help with the integration step. This is not available in production as it has side effects for payments, user communication, subscription status, etc. This tool aims to help you, the vendor, test your webhook integration in an easy, repeatable way.
+
+To use the webhook testing tool, log into your vendor dashboard on sandbox.woocommerce.com and navigate to SaaS Apps > Webhooks.
+
+Input any contract UUID you'd like to test webhook calls against in the form and hit enter or click on Select for testing. The page will reload with the contract selected. You can trigger webhook calls for the selected contract by clicking on the appropriate event button on the page. Please note that the available events depend on the current contract status. The webhook call is triggered async, so it may take up to a minute to receive the call. You can read more about the available webhook events in the webhooks section of this documentation. Make sure you have a webhook URL set up in your SaaS Application settings.
+
+## Questions & answers
+
+<details>
+<summary>Is there support for multi-currency?</summary>
+
+Not at the moment. Only USD is currently supported. We're considering adding currencies like EUR or GBP, but there's no ETA.
+
+</details>
+
+<details>
+<summary>How are taxes handled?</summary>
+
+We add tax on top of the original price to comply with the merchant's local regulations. The tax amount will vary depending on the merchant's country of residence and will be calculated automatically. You can add a notice about this in your application to inform merchants that the total may differ due to tax.
+
+There's no reliable way to confidently calculate tax before the merchant lands on WooCommerce.com and submits their billing details. Many factors determine the tax calculation. This makes it impossible to make a correct prediction without having all the necessary data upfront (such as billing address, IP address, validated VAT ID, and others).
+
+</details>
+
+<details>
+<summary>Do my application and WooCommerce.com exchange merchant personal information?</summary>
+
+No, we don't share personal details like email, name, or address with the vendor application. And we don't expect you to either. The flows are designed to work without exchanging personal information. So, if you need any personal data from the merchant, you can request it from them during sign-up.
+
+</details>
+
+<details>
+<summary>How do I link a merchant with their subscription on WooCommerce.com?</summary>
+
+You can map them using the unique contract ID appended to the return URL the merchant is redirected to after a successful purchase. The billing API and webhooks also use this ID to identify the subscription. There's no need to use personal information to map merchants to purchases.
+
+</details>
+
+<details>
+<summary>My SaaS product allows for multi-store connections. Can I still integrate with the billing API?</summary>
+
+Yes. You can offer a multi-site plan for purchase. The billing API doesn't support setting a quantity parameter in its current iteration. However, you can factor the multisite aspect into the contract and offer a multisite subscription. You can then track the usage internally using a combination of the contract ID and a store identifier.
+
+</details>
+
+<details>
+<summary>Do I need to apply billing requirements to all customers?</summary>
+
+Getting listed on the WooCommerce.com Marketplace enables software vendors to offer their products to a broad audience of millions of registered users. As with any other marketplace, you must follow some guidelines and requirements to get your product listed. This improves customers' overall quality and experience, so they choose to purchase through us rather than from software vendors directly.
+
+These requirements don't apply to all your customers, only those from WooCommerce.com. You can use your current billing system and flows for your existing customer base or customers from sources other than our marketplace.
+
+</details>
+
+<details>
+<summary>How do I apply a discount to a subscription?</summary>
+
+When initiating a contract sign-up via the API, you can set a price by specifying the lower amount in the price param when submitting the POST /subscriptions request.
+
+</details>
+
+## Glossary
+
+- **Vendor** – SaaS service provider partnering with WooCommerce.com to sell their solution via the WooCommerce.com marketplace.
+- **Vendor application (application)** – The Vendor's application integrates with the Billing API to communicate with WooCommerce.com.
+- **Merchant** – WooCommerce.com user, purchasing the SaaS product.
+- **Subscription plan (plan)** – A subscription product.
+- **Subscription contract (contract)** – Agreement in which merchant consents to have their payment method charged recurrently in exchange for the service the SaaS Vendor offers.
+- **One-time charge (charge)** – A one-off (non-renewable) charge.
+- **Contract sign-up** – Creating a subscription or charge contract and getting the merchant's confirmation.
diff --git a/docs/woo-marketplace/content-style-guide.md b/docs/woo-marketplace/content-style-guide.md
new file mode 100644
index 0000000000..2c0bbcc039
--- /dev/null
+++ b/docs/woo-marketplace/content-style-guide.md
@@ -0,0 +1,221 @@
+---
+sidebar_position: 8
+sidebar_label: 'Content Style Guide'
+---
+
+# Marketplace Content Style Guide
+
+This guide provides formatting and writing standards for creating product pages and documentation on the WooCommerce Marketplace. Following these guidelines ensures consistency across the Marketplace and creates a professional experience for merchants browsing and purchasing extensions.
+
+For product page structure, required elements, and asset specifications, refer to [Product Page Content and Assets](/docs/woo-marketplace/product-page-content-and-assets/).
+
+## Writing Standards
+
+### Product Naming Convention
+
+Use the format "Product Name for WooCommerce" rather than "WooCommerce Product Name" throughout the product copy.
+
+This format ensures your product name complies with [trademark rules](https://automattic.com/trademark-policy/) and leads with its unique identifier, improving discoverability and clarity.
+
+### Grammar and Punctuation
+
+Follow the [WooCommerce Grammar, Punctuation, and Capitalization Guide](https://woocommerce.com/document/woocommerce-grammar-punctuation-and-capitalization-guide/) for comprehensive guidance. Key points include:
+
+**Use the Oxford comma** when listing three or more items:
+
+- ✓ "Track orders, manage inventory, and process refunds."
+- ✗ "Track orders, manage inventory and process refunds."
+
+**Use active voice** instead of passive voice whenever possible:
+
+- ✓ "The extension sends email notifications when orders ship."
+- ✗ "Email notifications are sent by the extension when orders are shipped."
+
+**Capitalization:**
+
+- Use sentence case for headings (capitalize only the first word and proper nouns)
+- Do not use ALL CAPS for emphasis
+- Capitalize product names, features, and WooCommerce terminology correctly
+
+**Spelling and terminology:**
+
+- Use American English spelling
+- Use "ecommerce" (lowercase, no hyphen)
+- Use "WooCommerce" (not "Woocommerce" or "wooCommerce")
+
+## Formatting Guidelines
+
+Maintain clean, consistent formatting by following these standards. Custom styling interferes with the Marketplace design system and creates an inconsistent experience.
+
+### Text Formatting
+
+**Do not:**
+
+- Center headings or body text
+- Alter the default text color
+- Add custom font sizes or font families
+- Use bold or italic formatting excessively
+
+**Do:**
+
+- Use left-aligned text throughout
+- Allow headings and paragraphs to inherit default styles
+- Use bold sparingly for key terms only
+
+### Headings
+
+**Do not:**
+
+- Include more than one H1 tag per page (the product title serves as the H1)
+- Center-align headings
+- Apply custom colors or styles to headings
+
+**Do:**
+
+- Use H2 for main sections
+- Use H3 for subsections within an H2 section
+- Maintain a logical heading hierarchy (do not skip levels)
+
+### Sections and Layout
+
+**Do not:**
+
+- Create custom-styled sections or containers
+- Add borders around sections
+- Apply background colors to content areas
+- Add custom spacing between sections
+- Add additional styles to columns
+
+**Do:**
+
+- Use standard paragraph and heading blocks
+- Let the Marketplace template handle section spacing
+- Use the default column block without style modifications
+
+### Lists
+
+**Do not:**
+
+- Customize bullet or number designs with custom CSS
+- Add custom spacing between list items
+- Create nested lists more than two levels deep
+
+**Do:**
+
+- Use the standard unordered or ordered list blocks
+- Apply the approved list classes for styled checkmarks (see Formatting Tools below)
+
+## Content Restrictions
+
+### Emojis
+
+Do not use emojis in product pages or documentation. Emojis can cause accessibility issues, display inconsistently across devices, and create an unprofessional appearance.
+
+- ✗ "🚀 Boost your sales!"
+- ✓ "Boost your sales"
+
+### External Links
+
+Do not include links to external websites. All support and documentation links should point to Marketplace URLs:
+
+- Link to your product documentation hosted on WooCommerce.com
+- Link to Marketplace support resources
+- Do not link to external support portals, documentation sites, or landing pages
+
+## Formatting Tools
+
+The WooCommerce Marketplace provides several formatting tools to create visually appealing content while maintaining consistency.
+
+### Styled List Classes
+
+Use these CSS classes to create professional checkmark lists:
+
+#### Primary checkmark list (wccom-tick-list-primary)
+
+Creates bold checkmarks in green circles. Use for main benefit lists at the top of your product description.
+
+```html
+<ul class="wccom-tick-list-primary">
+ <li>Accept payments globally</li>
+ <li>Automatic tax calculation</li>
+ <li>Real-time shipping rates</li>
+</ul>
+```
+
+#### Secondary checkmark list (wccom-tick-list-secondary)
+
+Creates lightweight green checkmarks. Use for feature lists and secondary content throughout the page.
+
+```html
+<ul class="wccom-tick-list-secondary">
+ <li>Supports 100+ currencies</li>
+ <li>PCI compliant</li>
+ <li>Automatic updates</li>
+</ul>
+```
+
+### Callout Boxes
+
+Use the box shortcode to highlight important information. Available styles:
+
+#### Info box
+
+For general tips and helpful information:
+
+```plain
+[box]This extension requires WooCommerce 8.0 or higher.[/box]
+```
+
+This component can be used with or without `style="info"`.
+
+#### Alert box (style="alert")
+
+For warnings or important notices:
+
+```plain
+[box style="alert"]Backup your site before updating to the latest version.[/box]
+```
+
+#### Error box (style="error")
+
+For critical warnings or known limitations:
+
+```plain
+[box style="error"]This extension is not compatible with multisite installations.[/box]
+```
+
+#### Success box (style="success")
+
+For positive confirmations or best practices:
+
+```plain
+[box style="success"]Your API credentials are securely encrypted and stored.[/box]
+```
+
+:::info
+Use callout boxes sparingly. Overuse reduces their impact and creates visual clutter.
+:::
+
+## Documentation Standards
+
+When creating documentation for your product, follow these additional guidelines:
+
+### Structure
+
+- Begin with a clear introduction explaining what the extension does
+- Please use the synced pattern titled "Docs – Installation." This explains how our mutual customers should install purchases from WooCommerce.com.
+- Document all your product's features and settings
+- Provide troubleshooting guidance for common issues
+
+For detailed documentation frameworks, refer to [Support and Documentation Best Practices](https://woocommerce.com/document/extension-development-best-practices/#support-and-documentation).
+
+### Images and Screenshots
+
+When adding visual content:
+
+- Use the modern WordPress admin color scheme
+- Use a recent core WordPress theme unless documenting a different theme
+- Ensure screenshots are clear and legible
+- Optimize file size
+- Do not include sensitive or personal information in screenshots
+- Add alt text to all images for accessibility
diff --git a/docs/woo-marketplace/getting-started.md b/docs/woo-marketplace/getting-started.md
new file mode 100644
index 0000000000..064c9fcd4e
--- /dev/null
+++ b/docs/woo-marketplace/getting-started.md
@@ -0,0 +1,69 @@
+---
+sidebar_position: 1
+---
+
+# Getting started
+
+We are excited to have you here! The WooCommerce.com Marketplace connects trusted developers and merchants worldwide to create powerful and flexible online stores.
+
+## Why you should sell in the Woo Marketplace
+
+- **Access to a global network** of WooCommerce merchants
+- **Built-in brand recognition and trust** by listing your product in the official WooCommerce Marketplace
+- **Revenue sharing** designed to support your business growth
+- **Opportunities** to be featured in WooCommerce marketing campaigns
+- **Insights and feedback** from a community of active merchants and developers
+
+## Are you a good fit?
+
+We are looking for products that:
+
+- Solve real merchant problems
+- Are secure, well-documented, and well-maintained
+- Follow [security](https://developer.wordpress.org/apis/security/), [development](https://developer.woocommerce.com/docs/extensions/best-practices-extensions/extension-development-best-practices/), and [user experience](https://developer.woocommerce.com/docs/extensions/ux-guidelines-extensions/best-practices/) best practices
+- Offer high-quality merchant support
+- Include a clear and sustainable monetization model, whether through direct sales, subscriptions, or another approach
+
+## The agreement
+
+To join the WooCommerce Marketplace, vendors must offer high-quality, secure products, provide strong customer support, and follow WooCommerce's guidelines around listings, updates, pricing, and communication. The commercial terms are based on a revenue share model, with 70% of sales going to the vendor.
+
+[Read the full Marketplace Vendor Agreement](https://woocommerce.com/woo-vendor-agreement/).
+
+## The submission journey
+
+### Step 1: Prepare your product
+
+1. Build and thoroughly test your extension or theme.
+2. Ensure it meets our [technical](https://developer.woocommerce.com/docs/extensions/best-practices-extensions/extension-development-best-practices/), [user experience](https://developer.woocommerce.com/docs/extensions/ux-guidelines-extensions/best-practices/) (UX), and [security standards](https://developer.wordpress.org/apis/security/).
+3. Write clear and comprehensive [documentation](https://developer.woocommerce.com/docs/extensions/best-practices-extensions/support-and-documentation/).
+
+### Step 2: Apply to the Marketplace
+
+Submit detailed product information, demo links, and test instructions for review.
+
+### Step 3: Product review
+
+1. Our team reviews your submission for functionality, security, compatibility, and UX.
+2. You may receive feedback and revision requests.
+
+### Step 4: Launch and sell
+
+1. Once approved, your product is listed in the WooCommerce.com Marketplace.
+2. After launch, maintain and update your product, and provide ongoing merchant support.
+
+## Helpful resources
+
+- [Submission guidelines](https://woocommerce.com/document/submitting-your-product-to-the-woo-marketplace/)
+- [Extension developer handbook](https://developer.woocommerce.com/docs/extensions/getting-started-extensions/)
+- [Block theme developer handbook](https://developer.woocommerce.com/docs/theming/block-theme-development/theming-woo-blocks)
+- [SaaS Billing API](https://woocommerce.com/document/billing-api-for-saas-products/)
+- [Marketplace Vendor Agreement](https://woocommerce.com/woo-vendor-agreement/)
+
+## Ready to apply?
+
+1. [Become a Marketplace partner](https://woocommerce.com/partners/).
+2. Before you submit, we recommend reviewing the full [submission guidelines](https://woocommerce.com/document/submitting-your-product-to-the-woo-marketplace/#section-1) for detailed steps.
+3. When you're ready, [submit your product](https://woocommerce.com/document/submitting-your-product-to-the-woo-marketplace/).
+
+We look forward to helping you succeed in the WooCommerce Marketplace!
diff --git a/docs/woo-marketplace/index.mdx b/docs/woo-marketplace/index.mdx
new file mode 100644
index 0000000000..887631e89e
--- /dev/null
+++ b/docs/woo-marketplace/index.mdx
@@ -0,0 +1,11 @@
+---
+title: Woo Marketplace
+slug: /woo-marketplace
+sidebar_position: 0
+---
+
+import DocCardList from '@theme/DocCardList';
+
+Documentation for developers publishing extensions, themes, and integrations on the Woo Marketplace.
+
+<DocCardList />
diff --git a/docs/woo-marketplace/managing-products.md b/docs/woo-marketplace/managing-products.md
new file mode 100644
index 0000000000..c9f9001b25
--- /dev/null
+++ b/docs/woo-marketplace/managing-products.md
@@ -0,0 +1,43 @@
+---
+sidebar_position: 5
+sidebar_label: 'Managing products'
+---
+
+# Managing products in the Woo Marketplace
+
+Developers selling in the WooCommerce.com Marketplace can edit their product pages, access information like usage data and sales, and manage reviews.
+
+## Editing a product page
+
+Most of the work for managing products can be done via the [vendor dashboard](https://woocommerce.com/wp-admin/).
+
+- From your vendor dashboard, navigate to _Products > All Products_.
+- Select the product you want to work on.
+
+From there, you can see information about usage, upload a new version, or edit the product page. [Review our product page guidelines](https://woocommerce.com/document/marketing-product-pages-writing/).
+
+
+
+### Uploading new versions
+
+To maintain a high-quality and competitive Marketplace, we encourage all vendors to regularly update their products. Consistent updates ensure compatibility with the latest versions of WooCommerce and WordPress, improve security and performance, and deliver ongoing value to customers.
+
+[Review our product update guidelines and best practices](https://woocommerce.com/document/product-update-guidelines/).
+
+### Adding or editing documentation
+
+To review, edit, or add documentation, navigate to _Documentation_ in your vendor dashboard. [Review our guidelines for creating effective documentation](https://woocommerce.com/document/writing-documentation/).
+
+
+
+## Understanding product sales
+
+Vendors have access to reports on how their products are performing, including:
+
+- **Earnings**: New sales, renewal sales, and refund amount.
+- **Commissions**: The amount the vendor earns from **net** product sales. Net revenue is defined as **revenue received from extension purchases minus refunds, chargebacks, disputes, discounts, and affiliate fees**.
+- **Subscriptions**: Total active subscriptions, including new and renewing this month, as well as refund and renewal rates.
+
+To view this information, log in to your vendor dashboard and navigate to _Analytics > Overview_.
+
+
diff --git a/docs/woo-marketplace/managing-your-account.mdx b/docs/woo-marketplace/managing-your-account.mdx
new file mode 100644
index 0000000000..5051c33a0e
--- /dev/null
+++ b/docs/woo-marketplace/managing-your-account.mdx
@@ -0,0 +1,82 @@
+---
+sidebar_position: 4
+sidebar_label: 'Managing your account'
+---
+
+# Manage your Woo Marketplace partner account
+
+Partners selling on the Woo Marketplace can edit their store profile and update their support email from the Partner dashboard. For some changes, we ask that you contact the Marketplace team for help.
+
+To access store settings, click the **Store** menu under **_Settings_** in your [partner dashboard](https://woocommerce.com/wp-admin/).
+
+## Business legal name and contact address
+
+When you first join the WooCommerce Marketplace, we'll ask you to complete the **_Business Legal Name_** and **_Business Contact Address_** fields. These allow us to set up an account for you on our accounting platform so you can get paid for your extension sales.
+
+
+
+If you make changes to the business name, you'll see a prompt to resign the **Partner Agreement**. Please click on **Partner Agreement** in the left menu, scroll down and tick the box to agree, then save. If the business name changes to a new entity after you have started selling, we will reach out about setting up a new accounting profile.
+
+To change your vendor name, [please contact us](https://woocommerce.com/wp-admin/admin.php?page=wcpv-vendor-support).
+
+## Vendor logo and profile
+
+Your vendor logo and profile are a great way to tell more about yourself and your company to prospective customers! This will appear at the public profile for your brand along with your extensions.
+
+
+
+- **Do:** Upload a logo for your company that **does not include** the [WooCommerce brand or trademark](https://woocommerce.com/trademark-guidelines/).
+- **Do:** Tell your brand story. Why are you a great WooCommerce partner?
+- **Do:** Link to your website homepage (optional). Use the same URL listed in your vendor profile if you opt to include it.
+- **Don't:** Link to other products you sell outside of WooCommerce.com.
+- **Don't:** Link to another contact form other than the **[WooCommerce.com contact page](https://woocommerce.com/my-account/contact-support/).**
+
+## Other settings
+
+**Required settings:**
+
+- **Vendor email:** Where we send updates about orders and any other communication.
+- **Support email:** The address that will receive support and presales requests.
+- **Website:** Your company's website. This will not be displayed on your vendor profile.
+
+**Optional settings:**
+
+- **Average response time:** List in hours, not currently shown on profiles.
+- **Privacy policy URL:** A link to the privacy policy on your website.
+- **Support Languages:** Languages in which you offer support.
+- **TOS URL:** A link to the terms of service on your website.
+- **Timezone:** Timezone setting, not displayed.
+
+
+
+## Tools
+
+Additional tools to help you with vendor information are available in **[Settings > Tools](https://woocommerce.com/wp-admin/admin.php?page=partner-dashboard-tools)** in the vendor dashboard.
+
+### Google Analytics
+
+Add your own Google Analytics tag to your vendor dashboard to get insights on the pages for your products and profile. [Follow these steps](https://wordpress.com/support/google-analytics/#step-1-sign-up-to-google-analytics) for information on how to sign up and get your Tag ID.
+
+
+
+### Customer subscription details
+
+Type in a customer email and press **enter** to verify their account owns your product and qualifies for support.
+
+### Vendor details
+
+Need to know how to reach another vendor? Type the vendor name and hit Enter to see their support email address.
+
+### Changelog validator
+
+Test your `changelog.txt` file to ensure that it meets [Woo Marketplace standards](https://woocommerce.com/document/create-a-plugin/#section-9) by copying the text of the file and pasting it into the text box. You can also use our ChatGPT [Changelog Formatter](https://chatgpt.com/g/g-9b3SlOWTF-woocommerce-com-changelog-formatter) to automatically revise your existing changelog to use in your extension.
+
+## FAQs
+
+<details>
+<summary>How can I add someone to help me manage my products?</summary>
+
+- We can add additional Vendor Admins to your profile at your request. Vendor Admins can assist with updating products and documentation as well as view sales reports, reviews, and feature requests.
+- To request another admin, [contact us via the link in your dashboard](https://woocommerce.com/wp-admin/admin.php?page=wcpv-vendor-support) or email [partners@woocommerce.com](mailto:partners@woocommerce.com) using your current partner account email. Please first ensure that they have [created a WooCommerce.com account](https://woocommerce.com/sso?new=1&next=%2Fwoocommerce%2F) with [two-step authentication enabled](https://wordpress.com/support/security/two-step-authentication/).
+
+</details>
diff --git a/docs/woo-marketplace/monetization-expectations.md b/docs/woo-marketplace/monetization-expectations.md
new file mode 100644
index 0000000000..5fe201b0d1
--- /dev/null
+++ b/docs/woo-marketplace/monetization-expectations.md
@@ -0,0 +1,89 @@
+---
+sidebar_position: 2
+sidebar_label: 'Monetization expectations'
+---
+
+# Monetization expectations for Marketplace plugins
+
+When listing a plugin on the Woo Marketplace, it's important to understand how we approach monetization. Our goal is to ensure alignment between how your plugin generates value and how that value is captured, creating a transparent experience for merchants and sustainable partnerships for developers.
+
+:::note
+We do not currently accept free plugins that have no path to monetization. There should be a path to monetization either within the plugin itself or through connection to other paid products or services that then fall into one of the monetization models listed below.
+:::
+
+## Matching monetization models
+
+The monetization model for your Marketplace listing should reflect the way your solution generates revenue:
+
+- **Standalone functionality plugins**: Plugins that extend WooCommerce with features not tied to an external system can be sold through the standard Marketplace license model, with billing handled directly through Woo.
+- **Integration plugins**: Plugins that connect WooCommerce to an external service or platform require a monetization approach that matches how the integrated system bills merchants.
+
+## Standalone plugin licensing
+
+For plugins that add functionality to WooCommerce without connecting to an external service, we offer two listing options:
+
+### Paid license
+
+The Marketplace supports a single-site license model. If you sell your plugin elsewhere with multi-site licenses or tiered packages, your Marketplace listing should use a price that closely matches your existing single-site license fee.
+
+### Freemium
+
+If your plugin offers both free and paid tiers, you can list it using our Freemium model. This allows merchants to install a free version of your plugin with the option to upgrade to a paid tier for additional features. Freemium listings help merchants try before they buy while giving you an opportunity to demonstrate value and drive upgrades.
+
+Freemium is ideal for plugins where:
+
+- An additional plugin is needed to provide the upgraded features
+- Core functionality works well as a free offering
+- Premium features provide clear, demonstrable value worth upgrading for
+- You want to build a user base before converting to paid
+
+## Integration plugin requirements
+
+For plugins that integrate WooCommerce with an external system, we have specific expectations:
+
+### First-party development preferred
+
+We strongly prefer that integration plugins are built and maintained by the company that owns or operates the external system being integrated. This ensures:
+
+- Merchants have a direct relationship with the company billing them
+- Technical support comes from the team with deepest product knowledge
+- Long-term maintenance aligns with the external system's roadmap
+
+If you're a third-party developer building an integration for a system you don't operate, we encourage you to connect with that company directly or [contact our Marketplace team](#questions-about-your-billing-structure) to discuss your specific situation.
+
+### Appropriate billing structure
+
+Plugins that connect to externally-billed services cannot use the standard paid Marketplace license model. Instead, you must use one of the following options:
+
+| Billing Model | Description | Best For |
+| --- | --- | --- |
+| **Billing API** (recommended) | Our API handles subscription billing on behalf of your service, with validation endpoints to confirm payment status and active subscriptions. Billing shifts to Woo, and you receive payouts based on the revenue share model. [View Billing API documentation →](https://woocommerce.com/document/billing-api-for-saas-products/) | SaaS providers who want Woo to manage the billing relationship with merchants. |
+| **Partnership Agreement** | An agreement that extends our [Marketplace Vendor Agreement](https://woocommerce.com/woo-vendor-agreement/) to accommodate solutions where billing occurs outside of WooCommerce. The plugin is listed free on the Marketplace. | Companies with existing billing relationships and infrastructure. |
+
+### About the Partnership Agreement
+
+The Partnership Agreement is available as an alternative when the Billing API is not suitable for your business model. However, this option requires formal agreement to our partnership conditions and is subject to approval at our discretion. We assess each application to ensure alignment with Marketplace standards and merchant experience expectations.
+
+If you're considering this option, we recommend [contacting our Marketplace team](#questions-about-your-billing-structure) early in your planning process to discuss eligibility and requirements before investing development effort.
+
+## Theme licensing
+
+Themes listed on the Woo Marketplace use the standard paid license model only. Billing is handled directly through Woo using a single-site license fee.
+
+If you sell your theme elsewhere with multi-site licenses or tiered packages, your Marketplace listing should use a price that closely matches your existing single-site license fee.
+
+## Business services
+
+Business services (such as consulting, development, or managed services) require a formal agreement and prior approval from the Marketplace team before listing.
+
+If you offer business services that complement WooCommerce and would like to explore listing on the Marketplace, please [contact the Marketplace team](#questions-about-your-billing-structure) to discuss your offering and eligibility requirements.
+
+## Questions about your billing structure?
+
+If you're unsure which monetization model applies to your plugin, theme, or service, or if you'd like to discuss partnership options before submitting for review, please [contact the Marketplace team](https://woocommerce.com/partnerships-contact/). We recommend reaching out early in your planning process to ensure alignment before you invest significant development effort.
+
+## Related resources
+
+- [Marketplace Vendor Agreement](https://woocommerce.com/woo-vendor-agreement/) — Standard terms for all Marketplace vendors
+- [Billing API for SaaS Products](https://woocommerce.com/document/billing-api-for-saas-products/) — Technical documentation for integrating with our billing system
+- [Submitting Your Product](https://woocommerce.com/document/submitting-your-product-to-the-woo-marketplace/) — Complete submission guidelines
diff --git a/docs/woo-marketplace/product-page-content-and-assets.mdx b/docs/woo-marketplace/product-page-content-and-assets.mdx
new file mode 100644
index 0000000000..53f0008cd7
--- /dev/null
+++ b/docs/woo-marketplace/product-page-content-and-assets.mdx
@@ -0,0 +1,221 @@
+---
+sidebar_position: 7
+sidebar_label: 'Product page content and assets'
+---
+
+# Product page content and assets
+
+This document is designed to walk you through each step of editing your product page, detailing the assets you'll need and offering a few recommendations to maximize its effectiveness. Whether you're introducing a new product or refining an existing listing, the success of your page hinges on a clear, engaging, and user-friendly presentation.
+
+## Editing the product page
+
+1. Log in to your [Vendor Dashboard](https://woocommerce.com/wp-admin/).
+2. Navigate to _Products > [All Products](https://woocommerce.com/wp-admin/edit.php?post_type=product)_.
+3. Select the product you want to work on.
+
+From there, you can see information about usage, upload a new version, or edit the product page.
+
+
+
+## Product icon
+
+The product icon is the key visual element in all occurrences of your product in the Woo Marketplace. The image should be:
+
+- **The logo of your product, not your brand.** For example, a Gmail extension would display a Gmail logo icon, not the Google logo.
+- A **160×160px** image file in JPG or PNG format.
+- The image is displayed at 80x80px, so please mind legibility. We recommend logos/symbols rather than text that would be too small to read.
+- Please keep the icon content inside the **112×112px** area. This region of the image is unlikely to be hidden from view.
+- We use the `border-radius` property to define the radius of the icon's corners, so please don't add rounded corners to your image.
+
+
+
+
+
+- Upload it under _Product Data > Woo Product Data > Product Icon_.
+
+
+
+- If a non-transparent image is used, please be sure to update the background color accordingly.
+
+## Highlight card
+
+The highlight card background color sits behind the product icon and is applied to special placements across WooCommerce.com (see the example below from the Marketplace homepage):
+
+
+
+Provide a hex color code under _Product Data > Woo Product Data > Highlight card background color_.
+
+
+
+## Product thumb
+
+Product thumbs are used for themes and business services. It is not necessary to add one for extensions.
+
+- The minimum image size is 555x416px.
+- Reusing the featured image is acceptable.
+
+## Short description
+
+Keep it short and powerful. Besides the product page, the short description is also used in the product card, or the excerpt Google uses in the search results page.
+
+
+
+To add/edit the short descriptions, when editing a product, scroll down to the bottom of the screen.
+
+
+
+## Gallery
+
+The media gallery gives you the opportunity to put your product in its best light. We recommend using it for as much as possible.
+
+
+
+### Images
+
+Images should be:
+
+- 896×550 px or larger
+
+To upload images, use the native WooCommerce gallery in the product editor, as described in the image above, and always start with the Featured Image.
+
+### Video
+
+The gallery supports one embeddable video per product (e.g. YouTube, Vimeo). If there's a video attached, it will always show as the first item in the gallery.
+
+To embed a video, when editing a product, scroll down to the _Product Data_ section and click the _Featured Video_ tab. Paste in your video's embed code and click _Update_.
+
+
+
+## Product description
+
+
+
+When creating product pages, it's essential to communicate effectively, ensuring the content is accessible and engaging for everyone. The description gives you the most opportunity to highlight what's valuable about your product from a customer's perspective. Here are a few recommendations to help you get the best of it:
+
+- **Optimize for AI** ― By using a direct, factual tone and clear headings that answer "what is" and "how-to." This helps generative engines cite your content as the definitive answer to a user's question.
+- **Focus on Sales, Not Specs** ― Design your description to highlight key benefits, keeping technical details for documentation. This approach helps customers understand the value of your product without getting bogged down by complexity.
+- **Start With Top Benefits** ― Lists are not only easy to scan but also make your most compelling selling points stand out, ensuring they're memorable and immediately accessible. A 3-5 points list format allows users to quickly understand the unique advantages your product delivers.
+- **Explain Like I'm 5** ― Aim to present your products in a way that anyone, even a beginner, can understand. Simplify your explanations without compromising the message, making sure concepts are broken down into fundamental, easy-to-grasp ideas.
+- **Sell the Hole, Not the Drill** ― Remember, customers are looking for solutions, not specifications. Start with the benefits your product offers, then mention the features. For instance, instead of leading with "This phone case is made of carbon fibers," highlight "Protect your phone from any fall with our ultra-durable case." It's about solving problems, not listing specifications.
+- **Simple and Clear Language** ― Use plain, straightforward language that avoids industry jargon and complex terms. Break down elaborate concepts into simple explanations. This approach makes your content accessible to beginners and experts alike, ensuring everyone understands the value of your products.
+- **Visual Aids and Examples** ― Leverage diagrams, screenshots, and examples to illustrate your points. Visual aids can turn abstract concepts into tangible ideas, making them easier to grasp. Leave the screenshots showcasing the settings screens or other technical parts for the documentation.
+- **Empathy and Understanding** ― Acknowledge the challenges users might face, offering reassurance and support to boost their confidence in using your products.
+
+Please do not use/paste in emojis.
+
+See more about formatting in our [Marketplace Content Style Guide](/docs/woo-marketplace/content-style-guide/).
+
+## FAQs
+
+Frequently asked questions (FAQs) are incredibly valuable for potential customers, helping to clarify common pre-purchase questions and boosting customer confidence in your extensions. A well-crafted FAQ section can effectively address buyer hesitations, reduce pre-sale inquiries, and ultimately translate into revenue.
+
+We strongly encourage you to update your existing FAQs to take advantage of this new dedicated section.
+
+
+
+<details>
+<summary>What to include in your FAQs</summary>
+
+- **Usage highlights**: Think about what would appear on your product's packaging — describe how your product enhances user experience or solves common issues, but keep it brief. Add links to the documentation if longer text is needed.
+- **Specific use cases**: Provide clear examples or scenarios demonstrating how customers can practically use your product.
+- **Compatibility and prerequisites**: Clearly state any compatibility requirements or prerequisites. Does your product integrate seamlessly with other WooCommerce extensions or plugins?
+- **Performance impact**: Address concerns customers might have about your extension's impact on their site's loading speed or overall performance.
+- **Customer support encouragement**: Use the FAQ as an opportunity to reassure customers that they can always reach out to support if they have additional questions.
+- **Troubleshooting and support access**: Include direct links or guidance for easily accessing troubleshooting guides and support resources.
+
+</details>
+
+<details>
+<summary>What to avoid</summary>
+
+- Highly technical instructions or step-by-step installation guides (these belong in your detailed documentation).
+- Overly long or complicated answers: keep it concise and non-technical.
+- Marketing language without substance — promotional phrases like "the best plugin ever!" FAQs should directly answer practical customer questions.
+- Broad questions like "Why choose our extension?" Instead, provide specific details that users commonly inquire about.
+- Lengthy explanations. Provide concise answers and link to documentation for detailed instructions.
+- Excess formatting: For best legibility results, keep the styling and formatting of your paragraph down to a minimum. Writing everything in bold, CAPS, or italics doesn't help.
+
+</details>
+
+<details>
+<summary>How to add FAQs to your product page</summary>
+
+Go to the [Vendor Dashboard](https://woocommerce.com/wp-admin/edit.php?post_type=product) and edit the product page for one of your products.
+
+
+
+</details>
+
+## Product data features
+
+To lay a stronger foundation for search and category filters, we've added new product data fields. The new data points are used for product features, search keywords, and product compatibility.
+
+While we're still exploring how they'll shape the broader search and categorization experience over time, these attributes will provide more control over how products appear in search results and which filters they match, leading to a more accurate and intuitive experience for customers.
+
+
+
+### What you need to know
+
+- These data points have been auto-populated using AI as a first step. This helps streamline the process and gives you a starting point.
+- We encourage you to review the AI-generated content to ensure it accurately reflects your product and make any updates needed.
+- You'll see these fields in your product back-end when editing any of your products.
+- These attributes are used in the In-app product previews (starting with WooCommerce 9.9). This means your shoppers benefit from richer, more informative previews of your products.
+
+
+
+### Why this matters
+
+- Customers will enjoy a cleaner, more relevant, and smoother shopping experience.
+- Vendors will gain greater visibility and control over how their products are discovered.
+
+## Listing requirements
+
+**Requirements:** Product requirements can be added under the _Woo Product Data_ tab.
+
+
+
+## Product name
+
+### Naming guidelines
+
+The product name is the first thing customers see when searching for products, so choosing an appropriate name is an important step. Choose a name that explains what your product does or why it's useful.
+
+Tips for how to craft a good product name:
+
+- **Brief** – Aim for 1 to 5 words, the fewer the better
+- **Scannable** – Easy to understand
+- **Unique** – Drives clicks to read more and makes it easier to find the listing via search
+- **Customer focused** – Use your customers' words rather than your own
+
+The name should NOT:
+
+- Violate trademark guidelines of WooCommerce or any other brand name.
+- Be a description of your product; use the short description to highlight the main benefits.
+- Use adjectives like "best" or "amazing"
+- Closely copy an existing listing name.
+
+### Changing a product's name
+
+To have the name of a product changed, please get in touch with the Woo Marketplace team via your Vendor Dashboard.
+
+
+
+## Product price
+
+To have the price of a product changed, please get in touch with the Woo Marketplace team via your Vendor Dashboard.
+
+
+
+## Demo
+
+Providing product demos of your WooCommerce extension is important — it helps potential customers quickly understand how your product works, what features it offers, and how it can benefit their store. A demo builds trust, reduces hesitation, and can significantly increase conversions by showing the value of your extension in action.
+
+Here are 3 things to make sure you include in your demo setup:
+
+- **Show both front-end and back-end views** – Give users a complete picture of how the extension works from a store owner's and a customer's perspective.
+- **Use secure (HTTPS) links** – This ensures user safety and builds trust when they visit your demo site.
+- **Link directly to relevant pages** – Let users experience the extension in action without having to click around or guess where to go.
+
+To add a link to your demo, when editing a product, go to the _Woo product data_ tab and find the _Demo URL_ field.
+
+
diff --git a/docs/woo-marketplace/product-update-guidelines.md b/docs/woo-marketplace/product-update-guidelines.md
new file mode 100644
index 0000000000..21b10f8d9d
--- /dev/null
+++ b/docs/woo-marketplace/product-update-guidelines.md
@@ -0,0 +1,189 @@
+---
+sidebar_position: 6
+sidebar_label: 'Product update guidelines'
+---
+
+# Product update guidelines and best practices
+
+To maintain a high-quality and competitive Marketplace, we encourage all vendors to regularly update their products. Consistent updates ensure compatibility with the latest versions of WooCommerce and WordPress, improve security and performance, and deliver ongoing value to customers.
+
+## Best practices
+
+### TL;DR
+
+- Update your product at minimum **every 6 months**.
+- Align with the [WooCommerce core release calendar](https://developer.woocommerce.com/release-calendar/).
+- Use tools such as the [Quality Insights Toolkit](https://qit.woo.com/) (QIT) and your **vendor dashboard**.
+- Check the [feature request portal](https://woocommerce.com/document/feature-request-portal/) for product ideas.
+- Regular updates = better customer trust and renewal rates.
+
+## Why regular updates matter
+
+- **Compatibility**: Ensures your product works seamlessly with the latest WooCommerce and WordPress releases.
+- **Security**: Patches vulnerabilities and keeps customer sites secure.
+- **Performance**: Enhances speed, reliability, and efficiency.
+- **Customer trust**: Builds confidence in your brand and product longevity. Regularly updated products often see higher renewal rates. Each update is a reminder of the value of keeping a subscription.
+- **Support load reduction**: Reduces the number of support tickets by proactively addressing issues.
+
+### Recommendations
+
+1. **Monitor the [WooCommerce release calendar](https://developer.woocommerce.com/release-calendar/)**: Anticipate changes that might impact your product.
+2. **Engage customer feedback**: Use reviews, support tickets, and feature requests to inform improvements, new features, and community-requested improvements.
+3. **Use semantic versioning**: Example: `v2.1.0` for features, `v3.0.0` for breaking changes.
+4. **Test thoroughly**: Ensure updates are stable and backward-compatible where possible. Consider integrating the [Quality Insights Tool](https://qit.woo.com/docs/) (QIT) into your workflow to automatically detect potential issues.
+5. **Document changes transparently**: Maintain clear, customer-facing changelogs, update the documentation and the product page if needed.
+
+### Marketplace expectations
+
+Products that fail to stay current with WooCommerce core and/or those that are not updated at least once every six months will be **flagged for removal** from the WooCommerce Marketplace.
+
+### Recommended update cadence
+
+- **Major releases**: At least quarterly, to align with [WooCommerce core releases](https://developer.woocommerce.com/release-calendar/).
+- **Security fixes**: As needed, with urgency.
+- **Minor improvements**: Monthly or as features and fixes are ready.
+- **Documentation**: Keep changelogs and user guides current with each release.
+
+## How to deploy updates
+
+### Uploading new versions
+
+Before uploading a new version of your extension, it is important to ensure that it passes all QIT quality standards. You can run these checks from your vendor dashboard by clicking the **_Quality Insights_** menu option.
+
+[Learn more about QIT tests and how to run them](https://qit.woo.com/docs/).
+
+You can upload the updated version after your extension passes all QIT checks.
+
+Click the **Versions** tab. You'll see all the versions you've previously uploaded, including highlights about what was in each version.
+
+
+
+Click the **Add version** button, then:
+
+1. **Select the .zip file** you want to upload from your computer.
+2. **Add the version number**.
+3. Click **Submit new version**.
+
+Once submitted, we will run the following tests on the uploaded file:
+
+- [End-to-end](https://qit.woo.com/docs/managed-tests/woo-e2e) (E2E)
+- [Activation](https://qit.woo.com/docs/managed-tests/activation)
+- [Security](https://qit.woo.com/docs/managed-tests/security)
+- [Woo API](https://qit.woo.com/docs/managed-tests/woo-api)
+- [PHPCompatibility](https://qit.woo.com/docs/managed-tests/phpcompatibility)
+- [Malware](https://qit.woo.com/docs/managed-tests/malware)
+
+All vendor admins will receive email notifications throughout the process, including:
+
+- **Confirmation:** Vendor admins will receive an email when a new version is submitted, confirming that it is in the queue. No action is needed.
+- **Rejected:** If a version fails any part of our automated testing, vendor admins will receive an email including the specific error. Developers should try to resolve the error and submit a new version when ready.
+- **Live:** If a version passes automated testing, it will be automatically deployed and made available to customers. No action is needed.
+
+Activation, security, and malware test passes are required for a new product version to be deployed.
+
+#### Formatting the changelog
+
+[Learn more about changelog formatting and entry types](https://developer.woocommerce.com/docs/extensions/core-concepts/changelog-txt/#the-changelogtxt-file).
+
+#### Common errors
+
+If an upload fails, there are a few common errors you should check first:
+
+- **The name of the file:** WooCommerce.com looks for a specific name for your .zip file and the main folder within it. You will see the expected name when you try to upload a product:
+
+
+
+- **A changelog is present**: A file named `changelog.txt` must be present to serve as a record of what's changed from version to version.
+- **Invalid changelog:** The `changelog.txt` file provided does not match the expected format.
+- **Mismatched version header**: The version in the extension header does not match the version provided during the upload process.
+- **Mismatched version numbers:** The version in the extension header and the `changelog.txt` do not match.
+
+#### Viewing test results
+
+The results from the automated tests will be in the **Submission Tests** table, which can be viewed by clicking the associated **View** link as shown in the image below:
+
+
+
+### Programmatically uploading new versions
+
+To deploy an extension programmatically, it must be an extension update and **not** a new submission. This method serves as an alternative to logging into the vendor dashboard and using the user interface (UI) to perform the same action.
+
+#### Generating an application password
+
+1. Ensure that you are logged into your WooCommerce vendor dashboard.
+2. [Create an application password](https://woocommerce.com/wp-admin/authorize-application.php?app_name=WCCOM+Product+Submissions&app_id=c08e8963-897b-46cd-91e9-e92488ac9120).
+
+:::note
+For extra security, this application password is scoped to the deploy endpoint and cannot be used to perform any other action on the user's behalf.
+:::
+
+#### Deploying your product
+
+Make a POST request to deploy your product using the following command:
+
+```bash
+curl -X POST https://woocommerce.com/wp-json/wc/submission/runner/v1/product/deploy \
+ -F "file=@/path/to/zip" \
+ -F "product_id=<product_id>" \
+ -F "username=<username>" \
+ -F "password=<app_password>" \
+ -F "version=<product_version>"
+```
+
+Replace `<product_id>`, `<username>`, `<app_password>`, and `<product_version>` with your actual product ID, username, application password, and product version, respectively.
+
+#### Checking deployment status
+
+To check the status of your deployment, use the following command:
+
+```bash
+curl -X POST https://woocommerce.com/wp-json/wc/submission/runner/v1/product/deploy/status \
+ -F "product_id=<product_id>" \
+ -F "username=<username>" \
+ -F "password=<app_password>"
+```
+
+#### Status response
+
+When you query the deployment status, the response will provide details about the progress, including the status of various test runs.
+
+Below is an example of this response:
+
+```json
+{
+ "status": "queued",
+ "version": "1.0.0",
+ "test_runs": {
+ "12345": {
+ "test_run_id": "12345",
+ "status": "success",
+ "test_type": "activation",
+ "result_url": "https://qit.woo.com/?qit_results=12345"
+ },
+ "67890": {
+ "test_run_id": "67890",
+ "status": "success",
+ "test_type": "api",
+ "result_url": "https://qit.woo.com/?qit_results=67890"
+ }
+ }
+}
+```
+
+> **Note:** Additional test run objects may be present in the response, one for each test type that was executed.
+
+### Maximize compatibility and reliability via custom E2E tests
+
+We strongly encourage contributing E2E tests for your extensions built on top of the QIT's [custom E2E testing framework](https://qit.woo.com/docs/custom-tests/introduction). By sharing these tests with us, you play a crucial role in ensuring true compatibility across different WordPress and WooCommerce versions, various PHP environments, and alongside other popular extensions.
+
+Our custom E2E testing framework — equipped with a Dockerized development environment and simple-to-use command tools — empowers you to design and execute comprehensive tests using [Playwright](https://playwright.dev/) that are tailored to your extension's unique functionalities.
+
+Not only does this initiative help mitigate potential compatibility issues before they affect users, but it also enhances the overall reliability of the products within our marketplace. Participating in this process not only contributes to a robust ecosystem but also elevates your extension's reputation for quality and reliability.
+
+Review our [QIT custom test documentation](https://qit.woo.com/docs/custom-tests/introduction) to begin leveraging the power of custom tests to guarantee your extension works seamlessly in real-world scenarios and stands out in the competitive Marketplace.
+
+## Need help?
+
+Feel free to reach out to the Marketplace team for update planning, QIT help, or deployment issues.
+
+Let's work together to keep the WooCommerce.com Marketplace innovative, secure, and reliable for everyone!
diff --git a/docs/woo-marketplace/submitting-your-product.mdx b/docs/woo-marketplace/submitting-your-product.mdx
new file mode 100644
index 0000000000..ca5ff9953e
--- /dev/null
+++ b/docs/woo-marketplace/submitting-your-product.mdx
@@ -0,0 +1,184 @@
+---
+sidebar_position: 3
+sidebar_label: 'Submitting your product'
+---
+
+# Submitting your product to the Woo Marketplace
+
+We look forward to reviewing your extension, theme, or integration for listing in the WooCommerce.com Marketplace. Before getting started, make sure you have [signed up for a vendor account](https://woocommerce.com/partners/), and are logged into your [vendor dashboard](https://woocommerce.com/wp-admin/).
+
+## Pre-submission checklist
+
+<details>
+<summary>Business review</summary>
+
+This includes an analysis of the product's business model and revenue share structure with Woo, as well as product rationale, competition, and developer/company history.
+
+- **Mutually beneficial partnership**: Products must share revenue with Woo, exclude spam links, affiliate links, or links to upsell products outside of the Woo Marketplace. See our [monetization expectations](./monetization-expectations.md).
+- **Trademark compliance**: Ensure that product names do not violate Woo's [trademark guidelines](https://woocommerce.com/trademark-guidelines/#sg-trademarks). Select a unique name that builds your brand and sets your product apart from others. [Review our product name guidelines](https://woocommerce.com/document/product-page-content-and-assets/#section-14).
+- **Competitive pricing**: Is the proposed price equal to or less than the price of the product sold in other environments? Select a suggested price that matches the price you sell elsewhere.
+
+</details>
+
+<details>
+<summary>Development guideline compliance</summary>
+
+- Products must follow [security best practices](https://developer.wordpress.org/apis/security/).
+- Products must support PHP 7.4+ as a minimum (PHP 8.3+ strongly recommended).
+
+:::warning PHP 7.4 End of Life
+PHP 7.4 reached [End of Life](https://www.php.net/supported-versions.php) (EOL) in November 2022. Using it may expose sites to security vulnerabilities.
+:::
+
+- Products must support the two latest **major releases** of both [WooCommerce](https://wordpress.org/plugins/woocommerce/) and [WordPress](https://wordpress.org/download/).
+- Products must adhere to foundational guidelines outlined in our [developer hub](https://developer.woocommerce.com/).
+- If your pricing model is based on a standard, tiered monthly subscription, we require you to implement the [SaaS Billing API](https://woocommerce.com/document/billing-api-for-saas-products/). API keys and sandbox access are granted manually after products are submitted for Marketplace consideration.
+- Products must be able to pass the following [Quality Insights Toolkit](https://qit.woo.com/docs/) (QIT) tests:
+ - [API](https://qit.woo.com/docs/managed-tests/woo-api)
+ - [End-to-end](https://qit.woo.com/docs/managed-tests/woo-e2e) (E2E)
+ - [Activation](https://qit.woo.com/docs/managed-tests/activation)
+ - [Security](https://qit.woo.com/docs/managed-tests/security)
+ - [PHPCompatibility](https://qit.woo.com/docs/managed-tests/phpcompatibility)
+ - [Malware](https://qit.woo.com/docs/managed-tests/malware)
+ - [Validation](https://qit.woo.com/docs/managed-tests/validation)
+
+</details>
+
+<details>
+<summary>User experience compliance</summary>
+
+- The product review includes a deeper analysis of the product's user experience (UX) and user interface (UI).
+- Ensure that your product's [critical flows](https://developer.woocommerce.com/testing-extensions-and-maintaining-quality-code/critical-flows/) have been thoroughly tested. See an example of [critical flows in the core WooCommerce plugin](https://developer.woocommerce.com/docs/contribution/testing/core-critical-flows/).
+- Extensions must adhere to [development best practices](https://developer.woocommerce.com/docs/extensions/best-practices-extensions/extension-development-best-practices/) and [UX guidelines](https://developer.woocommerce.com/docs/extensions/ux-guidelines-extensions/).
+- Themes must adhere to [theme development](https://developer.woocommerce.com/docs/theming/block-theme-development/theming-woo-blocks/), [design](https://developer.woocommerce.com/docs/user-experience-guidelines/ux-guidelines-themes/), and [UX guidelines](https://developer.woocommerce.com/docs/user-experience-guidelines/ux-guidelines-themes/).
+- **Accessibility**: It is important that all customers can use the stores where your extension is installed. Extension submissions must meet the [WordPress Accessibility Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/). For more information, review WordPress's [accessibility quick start guide](https://make.wordpress.org/accessibility/handbook/best-practices/quick-start-guide/).
+- Does the product have a single core purpose and use WooCommerce features as much as possible?
+- Can the product function "out of the box" without much configuration?
+
+</details>
+
+<details>
+<summary>Compatibility with top Woo extensions</summary>
+
+Products should not cause issues with widely-used Marketplace extensions. If your product is found to break any of these extensions when installed alongside them, it may be rejected or removed from the Marketplace.
+
+Popular extensions include:
+
+- [WooCommerce Bookings](https://woocommerce.com/products/woocommerce-bookings/)
+- [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/)
+- [Product Add-Ons](https://woocommerce.com/products/product-add-ons/)
+- [Product Bundles](https://woocommerce.com/products/product-bundles/)
+- [Min/Max Quantities](https://woocommerce.com/products/minmax-quantities/)
+- [Shipment Tracking](https://woocommerce.com/products/shipment-tracking/)
+
+</details>
+
+<details>
+<summary>Compatibility with core WooCommerce features</summary>
+
+Visitors expect the WooCommerce.com Marketplace to be the leading source of extensions and themes for the optimal ecommerce experience. This means we only accept submissions which are compatible with the latest enhancements to the core WooCommerce platform and overall merchant experience.
+
+[Review Woo's public roadmap](https://developer.woocommerce.com/roadmap/) for primary initiatives and expectations.
+
+<details>
+<summary>Block editor compatibility</summary>
+
+As we evolve within the WordPress ecosystem, we're placing a strong emphasis on block editor compatibility for WooCommerce extensions. While we continue to support classic and hybrid approaches, prioritizing block editor compatibility ensures your extensions align with the latest trends and offer users a more intuitive and cohesive experience.
+
+- **Cart and Checkout blocks**: The block-based Cart and Checkout is now the default experience in WooCommerce, offering a more streamlined and visually cohesive shopping experience. As a developer, prioritizing compatibility with these default blocks ensures your extensions and themes seamlessly integrate with the enhanced default shopping flow. [Review Cart and Checkout block architecture](https://developer.woocommerce.com/2023/09/18/architecture-of-cart-and-checkout-blocks/).
+- **Extensions**: Eliminate shortcode dependency. Many plugins/extensions still rely on shortcodes to output content. To enhance block editor compatibility, it is essential that these shortcodes are provided as blocks. This not only future-proofs your product but also allows users to leverage the full potential of the block editor's capabilities.
+- **Themes**: While we continue to accept classic and hybrid themes, we are **prioritizing block themes** for the Woo Marketplace. Block themes are designed to fully leverage the capabilities of the block editor and provide users with a more intuitive and flexible content creation experience.
+
+</details>
+
+<details>
+<summary>HPOS compatibility</summary>
+
+High-Performance Order Storage (HPOS) is the **default experience for new WooCommerce stores**. It moves order data from the WordPress post and postmeta tables to dedicated order tables to improve scalability and reliability.
+
+:::info
+**All new extension submissions must be HPOS-compatible.** View our [HPOS recipe book](https://developer.woocommerce.com/docs/hpos-extension-recipe-book/) for ways to support HPOS in your product.
+:::
+
+</details>
+
+</details>
+
+## Submitting a product for review
+
+From your vendor dashboard, navigate to **Submissions > Submit Product** and select the product type you're planning to submit:
+
+- Extension
+- Theme
+- SaaS
+- Business Service
+
+
+
+:::note Freemium products
+Freemium products — products with both free and paid versions — require **two separate submissions**, one for each model. These will later be merged into a single product page where users can choose between versions.
+:::
+
+### File upload and submission info
+
+The information required varies slightly depending on the submission flow selected. To help streamline the submission process, we only ask for critical details:
+
+- Product upload
+- Business details
+- Testing instructions
+
+
+
+Next, **address any submission test failures** noted in the discussion dialog. In the event of failures — marked as *Failed* — please click the **View** link beside the failed test to review the results and upload a modified version of your submission.
+
+
+
+If necessary, **replace the previously uploaded file to test again.** When tests fail, the submission status updates to ***Changes required***.
+
+To proceed, click the **Replace** button to replace the current .zip file with a corrected version. This will automatically restart the testing process.
+
+
+
+:::tip
+If your product is at a stage other than *Changes required*, you will not be able to replace this file. Please comment within the submission to request a status change from the Marketplace team.
+:::
+
+## Review process
+
+Once the submitted product passes automated code tests, it moves to our review queue. Once it has been reviewed, the reviewer will share feedback (if any) with you.
+
+A review consists of the following steps:
+
+1. **Business review**: to ensure your product is a good fit for the Marketplace, and that there is a business model to share revenue.
+2. **Code review**: to ensure the submitted product's code is original, secure, and aligned with overall WordPress and WooCommerce quality standards.
+3. **User experience (UX) review**: to ensure the product works as expected and its look and feel aligns with our UX guidelines.
+4. **Launch preparations**: once a submission successfully passes these review phases, it will be formally approved and proceed to onboarding for launch.
+
+## FAQs
+
+<details>
+<summary>How long will it take for my product to be reviewed?</summary>
+
+Once the submission is in business review, you can expect a formal decision from a reviewer within 30 days. Throughout the review process, we may provide feedback and request changes before rejecting or approving a submission.
+
+</details>
+
+<details>
+<summary>Can I submit multiple products at once?</summary>
+
+Yes. If you are planning to submit multiple products, it's best to submit them all at once. This allows us to prioritize those that are most likely to be approved faster from those that might require additional work.
+
+</details>
+
+<details>
+<summary>Can I resubmit a previously rejected product?</summary>
+
+Yes. You are welcome to resubmit products, providing the previously-received feedback was incorporated and your product was improved to comply with our guidelines and quality standards.
+
+</details>
+
+## Submission support
+
+For additional questions related to your submission, please use the discussion box below the **Submission Bot** results table in the **Submission progress** tab within your vendor dashboard.
+
+
diff --git a/docs/woo-marketplace/support-guidelines.md b/docs/woo-marketplace/support-guidelines.md
new file mode 100644
index 0000000000..0ee0c45752
--- /dev/null
+++ b/docs/woo-marketplace/support-guidelines.md
@@ -0,0 +1,108 @@
+---
+sidebar_position: 9
+sidebar_label: 'Support guidelines'
+---
+
+# Support guidelines for the Woo Marketplace
+
+Adhering to the support expectations outlined in this guide is a requirement under the Marketplace Vendor Agreement. Failure to meet these expectations may result in temporary or permanent removal of your products from the Marketplace.
+
+By participating in the WooCommerce.com Marketplace, you're not just selling a product — you're offering a complete customer experience. Providing timely, high-quality support is a core part of that experience and a key factor in building long-term trust with your customers.
+
+That said, great support is not only a requirement — it's a growth opportunity. Providing excellent support boosts customer loyalty, increases positive reviews, encourages repeat purchases, and strengthens your reputation in the Marketplace, ultimately contributing to your long-term growth and profitability.
+
+## Support expectations
+
+Marketplace vendors are responsible for customer support in line with WooCommerce's Support Policy, including:
+
+- Timely responses to customer emails.
+- Handling customer reviews and ratings promptly.
+- Managing feature requests posted on product pages.
+
+The WooCommerce team supports vendors by managing account issues, refunds, coupons, escalations, and live chat queries.
+
+### Response times
+
+Timely responses are critical. If you are unavailable or expect delays, communicate this clearly with the WooCommerce team and arrange to redirect support requests appropriately.
+
+### Support ratings
+
+Customers can rate their support experience seven (7) days after submitting a ticket. Maintaining good support ratings is crucial for continued Marketplace participation.
+
+### Live chat
+
+Marketplace vendors provide support exclusively via email. WooCommerce handles live chat queries and redirects product-specific requests to a vendor's support email address.
+
+## How support works
+
+### Ticket routing
+
+Customers submit tickets through the support request form and are automatically routed to your designated support email address. Each support email includes:
+
+- Product name
+- Subscription dates
+- System status report
+- The customer's message.
+
+### Specifying your support email address
+
+Specify the email address that support tickets should be routed to in your vendor dashboard via _Settings > Store_. The WooCommerce team will also use this address to copy (CC) you in on tickets.
+
+:::note
+The Support Email field is different from Contact Email, which is used for order notifications.
+:::
+
+
+
+### Getting set up for support ticket replies
+
+- **Activate an autoresponder**: Automatically inform customers that you have received their request, including links to your privacy and data usage policies. Avoid promotional or affiliate links.
+- **Deactivate any platform feedback requests**: Customers already receive feedback requests from the Woo Marketplace directly.
+
+## Security and customer login credentials
+
+If you need to log in to a merchant's store in order to successfully assist them, please follow these guidelines:
+
+- **Only ask for login credentials once you have exhausted all other options.** This includes asking for screenshots and reproducing the problem on your own test site(s).
+- **When asking for login credentials:**
+ - Inform the customer that, under GDPR regulations, they must mention that they may need to give access to third-party support services in their store's terms and conditions.
+ - Always ask the customer to create a temporary administrator account for you. (You will need to tweak the instructions in the document linked above as you do not have access to `woologin@woocommerce.com`.)
+ - At the end of the support interaction, ask the merchant to remove this temporary account.
+- **If the customer shares their details before you are able to provide the instructions above**, always point out that they ideally don't do this and that you strongly advise them to reset their password.
+- **Never ask for plain-text passwords.** Instead, use a password-sharing service like [QuickForget.com](https://quickforget.com/) to create a unique, expiring link.
+
+## Collaboration, refunds, and escalations
+
+To collaborate with other Marketplace vendors, you can copy in (CC) relevant parties on support tickets. Contact information for other vendors is available from the WooCommerce team.
+
+All refunds, coupons, and escalations are managed by WooCommerce. Forward relevant tickets by CCing the private email address from the Marketplace Developer P2.
+
+## Marketplace support tools
+
+### Active subscription checks
+
+Subscription details are included in customer support emails. Additional checks can be done through your vendor dashboard via _Settings > Tools_.
+
+
+
+### Reviews and ratings
+
+Vendors are expected to monitor and respond to customer ratings and reviews as part of their support responsibilities. Addressing concerns promptly not only improves customer satisfaction but also demonstrates your commitment to quality service.
+
+Keep in mind that customers are significantly more likely to leave a positive review following a helpful and timely support experience. Engaging positively with customer feedback — both praise and criticism — can strengthen your product reputation and foster long-term trust.
+
+Reviews and ratings for your products are managed via your vendor dashboard.
+
+
+
+### Feature requests
+
+Customers can post feature requests via your product page. These requests are publicly visible and provide valuable insight into what users want from your product.
+
+Vendors are expected to regularly monitor and respond to these requests like any other support channel. Timely, thoughtful engagement with feature requests demonstrates that you value user input and are actively working to improve your product.
+
+Feature requests are a powerful tool for understanding how customers use your product, identifying common pain points, and shaping your product roadmap. By participating in these conversations, you can build trust and stay aligned with your customers' evolving needs.
+
+Feature requests for your products are managed in your vendor dashboard via _Feature Requests_.
+
+