add tutorial for flat subscription with usage based billing

[Muhammad-Owais-Warsi]

📋 Description

Add a tutorial for flat subscription with usage based billing

🎯 Type of Change

• 📝 Documentation update (improving existing docs)
• ✨ New documentation (adding new guides, API docs, etc.)
• 🐛 Bug fix (fixing errors, broken links, incorrect information)
• 🎨 Style/formatting (improving readability, fixing formatting)
• 🏗️ Structural change (reorganizing content, navigation updates)
• 🌐 Translation (adding or improving translations)
• 🖼️ Assets (adding or updating images, diagrams)

📖 What documentation does this PR affect?

• Getting Started / Setup
• API Reference
• Developer Resources
• Integration Guides
• Features Documentation
• External Integrations
• Changelog
• Other:

✅ Checklist

• I have read the Contributing Guidelines
• I have tested my changes locally with mintlify dev
• All links are working correctly
• Images are properly displayed and optimized
• Code examples are tested and working
• I have updated the navigation in docs.json (if applicable)
• My changes follow the project's style guide
• I have performed a self-review of my changes
• I have added appropriate frontmatter to new pages

🧪 Testing

• Verified locally at http://localhost:3000
• Checked responsive design on mobile viewport
• Tested all code examples
• Validated all external links

📸 Screenshots (if applicable)

🔗 Related Issues

Closes #84

📝 Additional Notes

👥 Reviewers

@dodopayments/documentation-team

Summary by CodeRabbit

• Documentation
  • Added a new tutorial: “Subscription with Usage-Based Billing” in Developer Resources → Integration Guides.
  • Step-by-step guidance to configure a Meter and Product, covering pricing setup, meter association, price-per-unit, free thresholds, and subscription settings.
  • Includes annotated images, inline UI guidance components, and confirmation that the product setup completes successfully.

[coderabbitai]

Walkthrough

Adds a new MDX tutorial "Subscription with Usage Based Billing Tutorial" describing Meter and Product setup for combining flat subscriptions with usage-based billing, and registers the page in the docs navigation under Developer Resources → Integration Guides.

Changes

Cohort / File(s)	Summary
New tutorial content developer-resources/subscription-with-usage-based-billing-tutorial.mdx	Adds a step-by-step MDX tutorial covering Meter creation, Product/pricing configuration for usage-based billing (price per unit, free threshold), meter association, subscription settings, UI framing components (Frame, Check, ParamField, Note), images, read-more links, validation messages, and completion confirmation.
Docs navigation update docs.json	Inserts the new tutorial page under Developer Resources → Integration Guides → pages; no other structural deletions or edits.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Author as Docs Author
  participant CMS as Docs CMS
  participant Reader as Developer
  participant Billing as Billing System

  rect rgb(235,248,255)
    Author->>CMS: Create Meter section (define meter, unit)
    Author->>CMS: Create Product section (flat price + UBB settings)
    Author->>CMS: Add images, notes, validation copy
    CMS-->>Author: Save tutorial page
  end

  rect rgb(245,255,235)
    Reader->>CMS: Open tutorial page
    Note right of CMS: Reader follows steps to\ncreate Meter and Product in app
    Reader->>Billing: Create Meter (runtime)
    Reader->>Billing: Create Product and associate Meter
    Billing-->>Reader: Subscription established (flat + usage meter)
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

In burrows of docs I nibble bright,
I stitch a flat fee with usage light.
When meters climb past thresholds clear,
Extra hops appear — no fear! 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues Check	⚠️ Warning	The tutorial covers creating a flat subscription with usage-based billing and includes threshold configuration for free usage, satisfying the guide’s primary objectives from issue #84, but it lacks code examples demonstrating the combination of flat fees with threshold-based extra charges.	Add code snippets showing how to integrate flat subscription and usage-based billing programmatically, including logic for threshold-based extra charges as specified in issue #84.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title clearly summarizes the main change by specifying the addition of a tutorial for flat subscription with usage-based billing and is fully related to the changeset.
Out of Scope Changes Check	✅ Passed	All modifications are confined to adding a new tutorial file and updating docs.json for navigation, which directly correspond to the objectives of documenting flat subscriptions with usage-based billing.
Description Check	✅ Passed	The PR description follows the required template by including a clear description, selecting the correct type of change, identifying the affected documentation area, completing the checklist, detailing testing steps, linking the related issue, and tagging reviewers.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e0f129e and d26be8c.

📒 Files selected for processing (1)

• docs.json (1 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a83d02c and c0cff1d.

⛔ Files ignored due to path filters (4)

• images/guides/subscription-with-usage-based-billing/meter.png is excluded by !**/*.png
• images/guides/subscription-with-usage-based-billing/product-1.png is excluded by !**/*.png
• images/guides/subscription-with-usage-based-billing/product-2.png is excluded by !**/*.png
• images/guides/subscription-with-usage-based-billing/product-3.png is excluded by !**/*.png

📒 Files selected for processing (2)

• developer-resources/subscription-with-usage-based-billing-tutorial.mdx (1 hunks)
• docs.json (1 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*.{md,mdx}

📄 CodeRabbit inference engine (.cursor/rules/mintlify.mdc)

Every documentation page must begin with YAML frontmatter containing title and description

Files:

• developer-resources/subscription-with-usage-based-billing-tutorial.mdx

**/*.mdx

📄 CodeRabbit inference engine (.cursor/rules/mintlify.mdc)

**/*.mdx: Use clear, direct language appropriate for technical audiences
Write instructions in second person (you)
Use active voice over passive voice
Use present tense for current states and future tense for outcomes
Maintain consistent terminology across documentation
Keep sentences concise while preserving necessary context
Use parallel structure in lists, headings, and procedures
Lead sections with the most important information (inverted pyramid)
Use progressive disclosure: introduce basics before advanced topics
Break complex procedures into numbered steps using /
Include prerequisites and context before instructions
Provide expected outcomes for each major step
End sections with next steps or related information
Use descriptive, keyword-rich headings for navigation and SEO
Focus on user goals and outcomes rather than system features
Anticipate common questions and address them proactively
Include troubleshooting for likely failure points
Provide multiple pathways (beginner vs advanced) when appropriate, with an opinionated recommended path
Use for supplementary information that supports main content
Use for expert advice, shortcuts, or best practices
Use for critical cautions, breaking changes, or destructive actions
Use for neutral background or contextual information
Use for success confirmations or achievement indicators
Use to present the same concept in multiple languages
Provide complete, runnable code examples with language specified and filename when relevant
Include RequestExample/ResponseExample blocks for API endpoint docs
Document API parameters using (path, query, header, body) with types and required/defaults
Document API responses using with names, types, and required flags
Use for nested object properties or hierarchical information
Use / for platform-specific or alternative approaches
Use / for suppl...

Files:

• developer-resources/subscription-with-usage-based-billing-tutorial.mdx