If you use Chargebee to track customer purchases, you can set up a webhook integration so PartnerStack can listen for events relating to charges and subscriptions. Once we receive information about a customer paying for your product, we can record that payment in PartnerStack and ensure your partners are properly attributed!

Supported Chargebee Events

PartnerStack supports listening for the following events from Chargebee per their developer documentation. Please note we only listen for V2 webhooks at this time.

Customer Events

customer_created, customer_changed

When PartnerStack receives one of these events, it attempts to create or update a customer record. The following fields are read and matched from the Chargebee customer object:

Here's how PartnerStack processes these events:

1. Search for a matching customer in PartnerStack by customer_key, then provider_key, then email.
2. Resolve the customer:
   1. If a matching customer is found:
      • Update the provider_key if one doesn't already exist.
      • Update the email if the email in Chargebee is different from what's stored.
      • Update the name if the name in Chargebee is different from what's stored. If the customer's name in PartnerStack was previously set to their email, and the email in Chargebee is different, update the name to match the email in Chargebee.
   2. If a matching customer is not found, a new customer is created if both customer_key and partner_key are available.

Payment Events

payment_succeeded

When PartnerStack receives this event, it attempts to record a transaction under the associated customer. The following fields are read and matched from the Chargebee customer, transaction, invoice, and subscription objects:

Here's how PartnerStack processes this event:

1. Check if a transaction exists with the same transaction_key. If found, the transaction is skipped.
2. Search for a matching customer in PartnerStack by customer_key, then provider_key, then email.
3. Resolve the customer:
   1. If a matching customer is found, PartnerStack will use the existing record and update the provider_key if one doesn't already exist.
   2. If a matching customer is not found, a new customer is created if both customer_key and partner_key are available.
4. Create a new transaction in PartnerStack tied to the resolved customer.

Refund Events

payment_refunded, payment_failed

When PartnerStack receives one of these events, it processes a refund against the original transaction. The following fields are read from the Chargebee customer and transaction objects:

Here's how PartnerStack processes these events:

1. Search for a matching transaction in PartnerStack using the transaction_key.
2. If no matching transaction is found, nothing happens.
3. If a matching transaction is found, it checks the refunded amount against the original transaction amount:
   • For full refunds, PartnerStack will delete the original transaction.
   • For partial refunds, PartnerStack will delete the original transaction and create a new transaction record with amount_refunded subtracted from the original amount.

Integration

Get your Webhook URL

Navigate to Settings > Integrations > Webhooks and look for Chargebee from the Supported integrations.

Click the Copy button to save the URL to your clipboard.

Create the Webhook on the Chargebee Dashboard

1. Log in to your Chargebee dashboard.
2. From the sidebar, select Settings > Configure Chargebee and click on Webhooks.
3. Click on "+ Add Webhook" and fill out the URL you copied in your PartnerStack dashboard as the Webhook URL.
4. Select the events you want to send under "Events to Send." The most important ones to track purchases are Customer Created, Customer Changed and Payment Succeeded.
5. Make sure to select "Exclude card information from webhook call" -- we don't need any credit card information to record transactions on our platform!

Add customer key to Chargebee Metadata

Whenever you interact with Chargebee to record transactions under a customer, you need to let PartnerStack know which customer you're referring to. At PartnerStack, we identify customers using their customer key. This can be any value that uniquely identifies customers on your platform, for example their email address.

If you're using PartnerStackJS, this would be the value you used for growsumo.data.customer_key when the customer signed up. If you used our PartnerStack API to create the customer record, this would be the value you passed as the key.

When PartnerStack receives the webhook from Chargebee, the platform tries to find a customer with the same customer_key as the one listed in the customer meta_data in Chargebee. Please ensure these match, or the transaction will not be properly recorded. This is an example of how the metadata object can be set when creating the customer through your backend. The implementation varies depending on how you've integrated with Chargebee in your product!

ADD `meta_data` containing the `customer_key`
MAKE SURE it matches the one used with PartnerStackJS
`partner_key` is required if not using PartnerStackJS

  chargebee.configure("test_2L7HV...", "your-site...")
  chargebee.Customer.create({
      "first_name" : "John", 
      "last_name" : "Doe", 
      "email" : "[email protected]",
      "meta_data": {
          "customer_key": <YOUR_CUSTOMERS_KEY>,
        "partner_key": <partner_key>
      }
# })

ADD `metadata` containing the `customer_key`
MAKE SURE it matches the one used with GrowSumoJS

# require 'chargebee'
# ChargeBee.configure(:site => "{site}", :api_key => "{site_api_key}")
# result = ChargeBee::Customer.create({
    :meta_data => {"customer_key" => <YOUR_CUSTOMERS_KEY>),
#   :first_name => "John", 
#   :last_name => "Doe",
#   ...
# })
# customer = result.customer
# card = result.card

ADD `metadata` containing the `customer_key`
MAKE SURE it matches the one used with GrowSumoJS
<?
// require 'ChargeBee.php';
// ChargeBee_Environment::configure("{site}","{site_api_key}");
// $result = ChargeBee_Customer::create(array(
//   "firstName" => "John", 
//   "lastName" => "Doe", 
     "metaData" => array("customer_key" => <YOUR_CUSTOMERS_KEY>)
//   ...
// ));
// $customer = $result->customer();
// $card = $result->card();

ADD `metadata` containing the `customer_key`
MAKE SURE it matches the one used with GrowSumoJS

// Environment.configure("{site}","{site_api_key}");
// Result result = Customer.create()
//                   .firstName("John")
//                   .lastName("Doe")
                     .metaData("customer_key", <YOUR_CUSTOMERS_KEY>)
//                   ...
// Customer customer = result.customer();
// Card card = result.card();

ADD `metadata` containing the `customer_key`
MAKE SURE it matches the one used with GrowSumoJS

// var chargebee = require("chargebee");
// chargebee.configure({site : "{site}", api_key : "{site_api_key}"});
// chargebee.customer.create({
//   first_name : "John", 
//   last_name : "Doe", 
     meta_data: { "customer_key": <YOUR_CUSTOMERS_KEY> },
//   ..
// })