bunnyapp/bunny-plugin

Making changes in Bunny through the MCP tools — why subscription changes go through quotes rather than direct edits, picking the right quote kind (subscribe, update, renew, price_list_change), the compose/charge/apply lifecycle, why quantities are absolute and never deltas, what must be true before a quote can apply, discounts and price adjustments, cancelling, building the product catalogue, and chaining dependent writes with $N references. Use when the user wants to add seats, change quantity or price, upgrade, discount, renew, migrate or cancel a subscription, or set up products, plans and pricing.

Reading data out of Bunny through the MCP tools — gql_query for records, analytics_query for aggregates and metrics like MRR, churn and retention, invoices_preview for a forward view, and export_csv for large result sets. Covers how to pick between them, the exact measures shape analytics_query expects, discovering data sources, and pagination. Use when answering questions about a Bunny account's data.

How to operate a Bunny billing account through the Bunny MCP tools — which tool answers which request, the domain model behind them (warren, entity, account, subscription, quote, invoice), and the rules that keep an agent from inventing IDs, dates or amounts. Use whenever the Bunny MCP server is connected and the user asks about their customers, subscriptions, invoices, quotes, pricing, or revenue.

Pull revenue metrics and financial reporting from Bunny. Covers MRR / ARR / MUR scalars on Account, monthly RecurringRevenue time-series (plain list on Account, Relay connection at top level), RevenueMovement events tracking new / expansion / contraction / churn / reactivation deltas plus manual adjustments (revenueMovementCreate / revenueMovementUpdate / revenueMovementDelete, all billing:write), revenue recognition (ASC 606 / IFRS 15) via revenueRecognitionTable and revenueRecognitionExport (24 month columns + period tag), revenueToDate, client-side aggregation for failed/unpaid stuck revenue, the narrow filter-string grammar the server accepts, the billing:read + standard:read scope pair required for revenue reads, and patterns for MRR dashboards, churn waterfalls, and quarterly RevRec exports. Use for revenue dashboards, RevRec schedule exports, or subscription movement tracking.

Invoice, payment, and credit-note handling in Bunny. Covers the invoice state machine (DRAFT, PREPARING, READY, NOT_DUE, DUE, UNPAID, PROCESSING_PAYMENT, PAID, VOIDED, FAILED, MERGED, QUEUED, CONSOLIDATED), the credit-note lifecycle (DRAFT → READY → APPLIED / PARTIALLY_APPLIED), how invoices are generated by the cron vs invoiceGenerateNextPeriod, the void-vs-credit-vs-refund decision, the Payment + PaymentApplication model with multi-invoice application (paymentApplyToInvoices, paymentApplyToAccount), crediting (invoiceCredit, invoiceAddCredit, creditNoteCreate / creditNoteIssue / creditNoteApplyToInvoices), refund via invoiceRefund, consolidation billing (invoiceMerge), tax retries (invoiceRetryTax, invoiceUpdateTaxes), invoice templates, and reconciliation against external accounting systems. Use when handling invoices, capturing payments, issuing refunds or credits, or reconciling Bunny against your books.

Build and maintain a product catalog in Bunny — the subscription billing and management platform. Covers the object hierarchy (ProductCategory → Product → Plan → PriceList → PriceListCharge), Features for entitlement and metered billing, pricing models (flat, tiered, volume, bands) with tier configuration, charge types (recurring, one-time, usage) and billing periods, trial and renewal-term configuration on price lists, coupons (amount vs percentage, plan-scoped vs global), safe price versioning via price-list deprecation and duplication, and one-way catalog-sync patterns for mirroring an external source of truth into Bunny. Use when creating or updating products, plans, features, prices, or coupons; when modelling a pricing table; when implementing a catalog-sync job; or when versioning prices without breaking active subscriptions.

Official React component library for Bunny — @bunnyapp/components. Embeddable UI for signup, subscription management, invoices, quotes, billing details, and transaction history. Covers installation, wrapping an app tree in BunnyProvider (required apiHost and — for any functional rendering — a token prop), generating portal session tokens server-side with the portalSessionCreate GraphQL mutation, the single-provider pattern across multiple components, CORS subdomain whitelisting, and the component catalogue (BillingDetails, Invoice, Signup, Subscriptions, Quote, Quotes, Transactions). Use when embedding Bunny billing UI into a React, Next.js, Remix, or Vite app. For the hosted (non-React) alternatives see bunny-customer-portal; for server-side SDKs see bunny-node-sdk and bunny-ruby-sdk.

Hosted Bunny Customer Portal — three embedding variants for non-React apps (or when you prefer hosted over embedded). Covers the popup portal (via the https://cdn.bunny.com/v1/bunny.js SDK with new Bunny(subdomain, token).popup({page})), the standalone redirect portal at https://<subdomain>.bunny.com/portal?token=<token> with deep links to /portal/subscriptions, /portal/transactions, /portal/payment-method, and the hosted signup page at https://<subdomain>.bunny.com/portal/signup with pre-selectable priceListCode, returnUrl, couponCode, and prefilled customer fields. Also covers generating portal session tokens server-side via portalSessionCreate and the separate signup:read / signup:write token scopes the signup page requires. Use when embedding billing UI without using the React components, or when the simplest integration is a redirect.

Direct GraphQL API integration with Bunny — the subscription billing and management platform. Covers the endpoint URL (https://<subdomain>.bunny.com/graphql), Bearer-token authentication, OAuth2 client-credentials flow with automatic token refresh, pagination via Relay-style connections, error response shape, and the most common queries and mutations for accounts, subscriptions, quotes, invoices, and payments. Use when calling Bunny's GraphQL API from a language without an official SDK (Go, Python, Rust, Elixir, PHP, Java, .NET, etc.), when the Node or Ruby SDKs don't cover an operation you need, or when you need to understand the raw request / response shape. For Node prefer the bunny-node-sdk skill; for Ruby prefer the bunny-ruby-sdk skill.

Official Node.js / TypeScript SDK for Bunny — @bunnyapp/api-client. Covers installation, OAuth2 client-credentials setup (recommended, with automatic token refresh) and access-token setup, helper methods for creating and cancelling subscriptions, managing tenants, updating accounts, generating customer-portal sessions, recording metered feature usage, validating incoming webhooks with the x-bunny-signature header, and dropping down to raw GraphQL via bunny.query(). Use when integrating Bunny into a Node or TypeScript app (Express, Next.js, NestJS, Koa, serverless handlers, CLIs). For Ruby see bunny-ruby-sdk; for raw GraphQL see bunny-graphql; for React UI embedding see bunny-components.

Build quote flows in Bunny — the subscription billing platform. Covers the quote lifecycle state machine (DRAFT, IN_APPROVAL, APPROVED, SHARED, VIEWED, ACCEPTED, REJECTED, UNDONE), the Quote → QuoteChange → QuoteCharge three-level hierarchy, QuoteChangeKind (SUBSCRIBE, RENEW, UPDATE, UNSUBSCRIBE, ADJUSTMENT, DISCOUNT, QUANTITY_UPDATE, PRICE_UPDATE, …), the canonical create-change-apply flow, renewal/upgrade/add-on shortcuts (quoteSubscriptionRenew, quoteSubscriptionUpgrade, quoteSubscriptionAddon), coupon application (quoteChangeAddCoupon), the share/accept workflow (quoteMarkAsShared + quoteAccept), approval gating (quoteApprovalStart / quoteApprove), ramp deals (quoteChangeCreateRampUp) for stepped-quantity contracts, and the quoteApplyChanges output envelope ({ quote, subscriptions, invoice, errors }). Use when creating, modifying, or applying quotes; when building sales-assisted signup; or when orchestrating renewals and upgrades.

Official Ruby gem for Bunny — bunny_app. Covers installation, Rails initializer generator (bin/rails g bunny_app:install), OAuth2 client-credentials configuration (recommended, with automatic token refresh) and access-token configuration, module methods for creating and cancelling subscriptions, updating subscription quantities, converting trials, managing tenants and platforms, pushing tenant metrics, recording feature usage, generating customer-portal sessions, validating incoming webhooks with the x-bunny-signature header, and dropping down to raw GraphQL via BunnyApp.query / BunnyApp.query_async. Use when integrating Bunny into a Ruby or Rails app. For Node / TypeScript see bunny-node-sdk; for raw GraphQL see bunny-graphql.

Manage subscription lifecycle in Bunny. Covers the state machine (PENDING → ACTIVE → CANCELED / EXPIRED / TRIAL / TRIAL_EXPIRED), direct creation via subscriptionCreate vs quote-based creation, the nightly cron driving automated renewals / expirations / trial transitions, the evergreen auto-renew gate, explicit lifecycle mutations (subscriptionCancel, subscriptionReinstate, subscriptionSetAutoRenew, subscriptionTrialExtend, subscriptionTrialConvert), quantity updates (subscriptionQuantityUpdate), tenant metadata (subscriptionTenantUpdate), metered-usage reporting with featureUsageCreate / featureUsageUpdate / featureUsageDelete (requires billing:write), add-on co-renewal rules, price-adjustment timing on renewal, and when to reach for a quote (bunny-quoting) vs a direct mutation. Use when creating, modifying, renewing, or cancelling subscriptions; when reporting metered usage; or when orchestrating trial conversions.

Build webhook handlers that receive events from Bunny. Covers the two webhook flavours (Platform webhooks for tenant provisioning and checkout validation; Workflow webhooks for arbitrary object-change events across Accounts, Subscriptions, Invoices, Quotes, and 20+ other types), HMAC signature validation via the x-bunny-signature header against the raw request body, the optional Bearer-token Authorization header on platform webhooks, default payload envelope with type and payload fields, custom templated payloads with {{placeholder}} syntax, idempotency patterns, Bunny's per-event-class retry and timeout policy, and the Node / Ruby SDK verification helpers (bunny.webhooks.validate, BunnyApp::Webhook.verify). Use when receiving Bunny webhooks on a server you control.