> ## Documentation Index > Fetch the complete documentation index at: https://vida.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Chargebee Billing Integration > Chargebee Billing Integration and Configuration Chargebee is a subscription billing and revenue management platform built for businesses offering recurring, SaaS-based, or usage-based pricing models. It integrates with multiple payment gateways, including Stripe and Authorize.net, to securely process payments. Vida integrates with Chargebee to enable your Agent product plans to work seamlessly with Chargebee’s subscription system. This allows you to create and manage monthly subscriptions based on your Vida plans. ## Preparing for configuration This integration is available to eligible reseller and partner accounts that bill downstream customers. Before starting, confirm the Vida account that will own the billing connection and note its account ID. * Resellers use their reseller account ID in the Chargebee webhook URL. * Partners use their partner account ID in the Chargebee webhook URL. Keep these values available for the final Vida connection step: * Full-access API key * Publishable key * Chargebee site name * Product ID for each Agent plan * Price ID for each Agent plan * Webhook username * Webhook password You can connect the provider through the [Billing Provider API guide](/docs/api-reference/platform-guides/billing-providers). If your account does not have access to billing-provider configuration, contact Vida. ## What the integration covers * Creating new subscriptions through Chargebee hosted checkout * Cancelling subscriptions * Subscription renewals * Upgrading / Downgrading Plans in a subscription * Adding usage overages to pending invoices * Creating a secure portal session between your customers and Chargebee for managing payment methods and invoices * Account activation based on subscription activation and successful payment * Create new customer in Chargebee if they don't exist * Will use existing customer if we find one based on email address ### New subscriptions Through your Vida reseller portal, customers can subscribe to your Agent product plans and be redirected to Chargebee's secure hosted checkout. This collects the customer's payment information and creates a new subscription under the Chargebee customer profile. If the payment succeeds, Chargebee will inform the Vida platform the account is paid and apply the requested plan. If the Chargebee customer already has active subscriptions for other products, Vida creates a separate subscription so those subscriptions remain unchanged. Vida can use pending invoices for its subscription when supported usage charges must be added before payment. ### Cancelling subscriptions Subscriptions can be cancelled by a few different methods: * Customer disables their account on the Vida platform * Customer cancels their plan through the Vida billing settings * You cancel the subscription manually through Chargebee * Chargebee is set to automatically cancel the subscription if payment is uncollectible after the dunning period. ### Subscription Renewals Chargebee manages subscription renewals. By default, Vida subscriptions renew on the anniversary day of their creation. When a subscription renews, Chargebee tells Vida that a new billing cycle has begun so Vida can display the current and previous billing-period ranges. ### Upgrading or Downgrading Plans When a customer wants to upgrade or downgrade their Agent plan, Vida automatically switches the plan in the existing subscription. On upgrades, Chargebee will charge the prorated amount of the new plan immediately to bring the balance where it should be. On downgrades, Chargebee may be configured to credit customer account the amount instead of refunding. This would be applied on the next billing cycle. ### Adding usage overages to pending invoices As a customer's usage progresses through the month, when the next billing cycle happens, we will grab the usage from the previous billing period (previous month) and determine if any usage overages are due. Overages are any product items you have configured for their plan and they have consumed an amount that exceeds any included amount. These charges are then pushed to Chargebee's pending invoice so payment can be collected. ## Configure Chargebee and Connect It to Vida This section covers configuring Chargebee to prepare for the integration with Vida. We'll be covering: * Creating the Product Plans and Pricing * Enabling Hosted Pages (Checkout screens) * Enabling Self Service Portal (Payment Method Management and Invoices) * Automated Metered Billing Settings * Configuring Webhooks to Vida platform * Creating API Keys * Getting your Site value * Configure Dunning Settings ### Creating the Product Plans and Pricing After creating your Agent product plans in Vida, create the corresponding plans and prices in Chargebee. Record each Chargebee plan ID and price ID so the matching Vida plan can be connected to it. \ \ In your Chargebee account: 1. (Skip this step if you have your own product family you'd like to use) Navigate to Product Catalog -> Product Families -> "+ Create Product Family" button. Product families are used to bucketize product plans and add-ons to be used together. 2. Enter a Product family name and description and click **Create**. 3. Create the product plan by navigating to Product Catalog -> Plans -> "+ Create Plan" button. * Product Family: Select the previously created Product Family or the family you wish to use.\\ * External Name: This should match the plan name you provided in your Vida Agent plan\\ * Internal Name: This is Chargebee's internal plan name and will be used to generate the Plan Id. * This plan is metered - Leave this box **Unchecked** * Display in Self-Serve Portal - Leave this box **Unchecked** as we do not want to allow plan switching in Chargebee portal, only through the Vida platform. 4. After you click **Create**, you will be brought back to the product plans overview screen. Here we will set the price. * Under pricing section, click "**Set Price**" next to the **Monthly** frequency line. This will bring you to the screen to set the monthly price. * **Pricing Model**: Set this to **Flat Fee** * **Price**: set this to the USD value that you have configured on your Vida Agent plan\\ * **Billing Cycles**: Set this to forever to keep the subscription ongoing until either you or your customer cancels. * Click **Create**. 5. After creation, collect both the **plan Id** and the **price Id**. The plan Id appears in the top section of the product plan. 6. Open the Plan's **Pricing** section, select the **Monthly** price you created, and copy its ID from the price configuration screen. 7. Repeat these steps for every Agent product plan. Provide both the **Product Plan ID** and **Price Id** to Vida to complete the Agent product-plan configuration. ### Enabling Hosted Pages (Checkout) Vida uses Chargebee's hosted pages for checkout when customers choose an initial plan in the Agent platform. To enable: 1. Navigate to Settings -> Configure Chargebee -> Customer-Facing Essentials Section -> Checkout and Self-Serve Portal 2. Click the Configuration tab at the top right 3. Under the checkout section: * **Identify existing customers for checkout access using**: Set to **Single Sign On API** ### Enabling Self Service Portal (Payment Method Management and Invoices) \ In the same configuration screen, navigate to the **Self-Service Portal** section. 1. Set **Customers can access the self-serve portal** to **Via Single Sign On API**. This allows the Vida platform to create portal sessions for your customers to securely manage payment methods and view invoices. ### Automated Metered Billing Settings The Vida platform will leverage pending invoices on the subscriptions it manages to append usage charges before the invoice is finalized. Let's configure the settings for this to describe how Chargebee should handle and automatically close these invoices. 1. Navigate to **Settings -> Configure Chargebee -> Billing Section -> Billing LogIQ -> Billing & Invoices -> Metered Billing** 2. Click **Enable** and configure the settings for your billing policy. 3. Click **Apply** button on the top right of the screen. ### Configuring Webhooks to Vida platform Lastly, let's configure the communication link between Chargebee and Vida. This will allow Vida to receive the events from Chargebee when payments or subscription events occur. 1. Navigate to **Settings -> Configure Chargebee -> API Keys and Events Section -> Webhooks**\\ 2. Click "**+ Add Webhook**" button * Webhook Name: Vida * Webhook URL for a reseller: `https://api.vida.dev/chargebee/events?resellerId=YOUR_RESELLER_ACCOUNT_ID` * Webhook URL for a partner: `https://api.vida.dev/chargebee/events?partnerId=YOUR_PARTNER_ACCOUNT_ID` 1. Toggle "Protect webhook URL with basic authentication" to On. 2. Configure the Username and Password to something that is secure 3. Set API Version to "Version 2" 4. Set this as primary should be toggled to On. If you have an existing webhook that is primary, please let Vida know as this may impact the integration. 5. **IMPORTANT STEP**: Click the "**Events to Send**" box and configure the below events: * Customer Changed * Subscription Created * Subscription Activated * Subscription Changed * Subscription Cancelled * Subscription Renewed * Pending Invoice Created * Pending Invoice Updated * Invoice Generated * Invoice Updated * Invoice Deleted * Payment Succeeded * Payment Failed\ \ (13 total event types) ### Creating API Keys Lastly, we need to configure the API keys (API Key and PublishableKey) so that Vida can connect to your Chargebee instance. 1. Navigate to **Settings -> Configure Chargebee -> API Keys and Events section -> API Keys** 2. Click "**+ Add API Key**" button 3. Choose "**Full-Access Key**" 4. Choose "**All**" 5. Set the name of the API Key to "**Vida**". 6. Click **Create Key** button\\ 7. After creation, this will take you back to the key list. Find the key you created with the name Vida and copy its value. \\ 8. In the same list, copy the key named **publishable\_api\_key** or similar. Use both keys, the site name, and the webhook credentials when you [connect Chargebee to Vida](/docs/api-reference/platform-guides/billing-providers). ### Getting your Site value Your Chargebee site tells Vida where to connect to your platform. This is located in the URL of your browser session and also in the top left corner of Chargebee dashboard. By default, Chargebee gives you a production site and a test site. You will need your **Production Site** value to configure with Vida. \ \ For instance, if you are logged into your production Chargebee account at [**https://acmesolar.chargebee.com**](https://acmesolar.chargebee.com), your site value would be "**acmesolar**". ### Configure Dunning Settings Chargebee's dunning feature controls collection after an invoice payment fails. You can configure how long an account remains in dunning and how often Chargebee retries the payment. \ \ This is also where you decide what happens after all retries are exhausted. For example, Chargebee can cancel the subscription, which tells Vida that the account is unpaid and can remove access to paid resources. Choose settings that match your collection and customer-support policies.\ \ To configure the Dunning settings, go to **Settings->Configure Chargebee -> Dunning for online/offline payments**. \ \ If you wish for Chargebee to cancel the subscription after all payment reattempts have failed, configure the "**When dunning period ends, what happens to subscriptions**" setting to "**Cancel Subscriptions**". Click **Apply** button. \ \ Also, review the Dunning period duration and the Retry Frequency to best suit your business needs.