diff --git a/www/apps/cloud/app/billing-usage/page.mdx b/www/apps/cloud/app/billing-usage/page.mdx
new file mode 100644
index 0000000000..a3aa3790d8
--- /dev/null
+++ b/www/apps/cloud/app/billing-usage/page.mdx
@@ -0,0 +1,152 @@
+import { InlineIcon } from "docs-ui"
+import { EllipsisHorizontal, ArrowDownTray } from "@medusajs/icons"
+
+export const metadata = {
+ title: `Billing & Usage`,
+}
+
+# {metadata.title}
+
+In this guide, you'll learn how to manage your billing and usage details in Cloud.
+
+## Billing and Usage Overview
+
+After signing up for Cloud, you can view and manage your organization's billing and usage details in the Cloud dashboard.
+
+This is useful if you want to make sure you're not exceeding your usage limits, understand your plan's offerings, and manage your billing details.
+
+---
+
+## Edit Billing Email
+
+To edit the email used for billing:
+
+1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
+2. Click on the [organization switcher](../organizations/page.mdx#switch-organization) at the top left of the Cloud dashboard.
+3. Choose "Organization Settings" from the dropdown.
+
+
+
+4. In the Details section of the General settings, change the "Billing email" field.
+5. Once you're done, click the "Save changes" button.
+
+
+
+---
+
+## Manage Payment Method
+
+You can manage the payment methods used for the monthly Cloud payment subscriptions for your organization.
+
+### Add Payment Method to Organization
+
+To add a payment method that can be used for Cloud payments in an organization:
+
+1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
+2. Click on the [organization switcher](../organizations/page.mdx#switch-organization) at the top left of the Cloud dashboard.
+3. Choose "Organization Settings" from the dropdown.
+4. Change to the "Billing" settings from the sidebar.
+5. In the "Payment methods" section, click the "Add new" button.
+6. This will open a form where you can add credit card details.
+7. Once you're done, click the "Save" button.
+
+### Set Payment Method as Default
+
+When Cloud captures the subscription payment for your organization, it first uses the default payment method in your organization. If payment fails, Cloud tries to use other payment methods in the organization, if available.
+
+When you have multiple payment methods added to your organization, you can change the default payment method.
+
+To change the default payment method:
+
+1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
+2. Click on the [organization switcher](../organizations/page.mdx#switch-organization) at the top left of the Cloud dashboard.
+3. Choose "Organization Settings" from the dropdown.
+4. Change to the "Billing" settings from the sidebar.
+5. In the "Payment methods" section, find the payment method you want to set as default.
+6. Click the icon next to the payment method.
+7. Choose "Set as default" from the dropdown.
+
+The next time Cloud captures the subscription payment for your organization, it will use this payment method first.
+
+---
+
+## Edit Billing Information
+
+Billing information is used in your organization's invoices. You can edit the billing information to make sure the invoices include the correct details.
+
+To edit the billing information:
+
+1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
+2. Click on the [organization switcher](../organizations/page.mdx#switch-organization) at the top left of the Cloud dashboard.
+3. Choose "Organization Settings" from the dropdown.
+4. Change to the "Billing" settings from the sidebar.
+5. In the "Billing information" section, you can edit the legal name, country, address line, city, and post code.
+6. Once you're done, click the "Save changes" button.
+
+The new billing information will be used in your organization's next invoice.
+
+
+
+---
+
+## View Usage
+
+In your organization's settings, you can view your current plan and usage limits.
+
+To view your organization's usage:
+
+1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
+2. Click on the [organization switcher](../organizations/page.mdx#switch-organization) at the top left of the Cloud dashboard.
+3. Choose "Organization Settings" from the dropdown.
+4. Change to the "Billing" settings from the sidebar.
+
+You'll find two sections at the top of the Billing settings:
+
+- **Current plan**: The plan your organization is currently subscribed to and when the next billing date is.
+- **Usage limits**: The usage limits for your current plan. The **Usage** column indicates how much your organization has used so far, and the **Included** column indicates the limits of your current plan. You'll mainly find the following usage limits:
+ - **Seats**: The number of users that can be added to your organization.
+ - **Projects**: The number of projects that can be created in your organization.
+ - Other add-ons may be listed based on your plan.
+
+
+
+### Change Plan
+
+You set your organization's plan when you sign up for Cloud. However, the plan may not be the best fit for your needs as your business grows.
+
+If you want to change your plan or learn more about your plan's resources and limits, [contact support](#) for assistance.
+
+---
+
+## View Billing History and Invoices
+
+You can view your payment history in the organization's settings, and download invoices for each payment.
+
+To view your organization's billing history and invoices:
+
+1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
+2. Click on the [organization switcher](../organizations/page.mdx#switch-organization) at the top left of the Cloud dashboard.
+3. Choose "Organization Settings" from the dropdown.
+4. Change to the "Invoices" settings from the sidebar.
+
+This will show a table of all the payments made for your organization, including the date, status, and amount of each payment.
+
+
+
+### Download Invoice
+
+To download an invoice for a specific payment, click the icon in the same row as the payment you want to download.
+
+This will open the invoice in a new tab, where you can view and download it as a PDF.
+
+
+
+---
+
+## Handle Unsuccessful Payments
+
+If a payment for your organization's subscription fails, you'll receive a [notification](../notifications/page.mdx) in the Cloud dashboard.
+
+The payment may fail for various reasons, such as insufficient funds, an expired card, or other issues with the payment method. Make sure to [update your payment method](#manage-payment-method) if needed.
+
+If there are no issues with your payment method and the payment still fails, [contact support](#) for assistance.
\ No newline at end of file
diff --git a/www/apps/cloud/app/environments/page.mdx b/www/apps/cloud/app/environments/page.mdx
index 1dfb06ac78..0db963110c 100644
--- a/www/apps/cloud/app/environments/page.mdx
+++ b/www/apps/cloud/app/environments/page.mdx
@@ -66,6 +66,7 @@ To create a long-lived environment:
2. In the side window that opens:
- Enter the name of the environment. For example, `Staging`.
- Select the branch you want to associate with this environment. For example, `staging`.
+ - If you don't see the branch you want to use, refresh the page to load the latest branches from your repository.
- Set the custom subdomain for the environment. All environments are subdomains of `medusajs.app`. So, if you set the subdomain to `staging-my-project`, the environment's URL will be `staging-my-project.medusajs.app`.
3. Once you're done, click the "Create" button.
diff --git a/www/apps/cloud/generated/edit-dates.mjs b/www/apps/cloud/generated/edit-dates.mjs
index 704e03e6df..5cd92268c1 100644
--- a/www/apps/cloud/generated/edit-dates.mjs
+++ b/www/apps/cloud/generated/edit-dates.mjs
@@ -10,5 +10,6 @@ export const generatedEditDates = {
"app/redis/page.mdx": "2025-06-18T06:50:30.705Z",
"app/s3/page.mdx": "2025-06-18T07:16:14.453Z",
"app/draft-order-plugin/page.mdx": "2025-06-18T08:32:21.263Z",
- "app/loyalty-plugin/page.mdx": "2025-06-18T08:28:51.756Z"
+ "app/loyalty-plugin/page.mdx": "2025-06-18T08:28:51.756Z",
+ "app/billing-usage/page.mdx": "2025-06-18T10:35:56.993Z"
}
\ No newline at end of file
diff --git a/www/apps/cloud/generated/sidebar.mjs b/www/apps/cloud/generated/sidebar.mjs
index ba1bd465df..e85cecb9e9 100644
--- a/www/apps/cloud/generated/sidebar.mjs
+++ b/www/apps/cloud/generated/sidebar.mjs
@@ -113,6 +113,23 @@ export const generatedSidebars = [
}
]
},
+ {
+ "loaded": true,
+ "isPathHref": true,
+ "type": "category",
+ "title": "Billing",
+ "initialOpen": true,
+ "children": [
+ {
+ "loaded": true,
+ "isPathHref": true,
+ "type": "link",
+ "title": "Billing & Usage",
+ "path": "/billing-usage",
+ "children": []
+ }
+ ]
+ },
{
"loaded": true,
"isPathHref": true,
diff --git a/www/apps/cloud/sidebar.mjs b/www/apps/cloud/sidebar.mjs
index 77a134e5c5..d8bd92f85a 100644
--- a/www/apps/cloud/sidebar.mjs
+++ b/www/apps/cloud/sidebar.mjs
@@ -78,6 +78,18 @@ export const sidebar = [
},
],
},
+ {
+ type: "category",
+ title: "Billing",
+ initialOpen: true,
+ children: [
+ {
+ type: "link",
+ title: "Billing & Usage",
+ path: "/billing-usage",
+ },
+ ],
+ },
{
type: "category",
title: "Monitoring & Support",