Chargebee Item Sync

​

Overview

​

Key Concepts

• Item Family: A container for related items in Chargebee (required before syncing plans)
• Item: Represents a chargeable entity (one per price/currency combination)
• Item Price: Defines the pricing model and rates for an item
• One Item Per Currency: Chargebee only allows one item price per currency per item, so we create separate items for each price

​

Item Family

​

Overview

​

Creating an Item Family

1. Go to Products → Item Families
2. Click + Add Item Family
3. Enter a name (e.g., “Flexprice Charges”)
4. Click Save

{
  "id": "item_family_123",
  "name": "Flexprice Charges"
}

​

Item Family Selection

1. Retrieves all item families from Chargebee
2. Selects the latest item family (most recently created)
3. Uses it for all synced items

​

Item Sync Process

​

Plan Sync Flow

​

Item Creation

1. One Item (type: charge)
   • ID format: charge_{uuid}
   • Name: Same as ID (must be unique)
   • Type: charge (for one-time/recurring charges)
   • Item Family: Latest item family from Chargebee
   • External Name: {display_name} - {currency} (e.g., “API Calls - USD”)
2. One Item Price (linked to the item)
   • ID: Flexprice price ID (for easy mapping)
   • Item ID: The created item ID
   • External Name: {display_name} - {currency}
   • Currency: Price currency
   • Pricing Model: Mapped from Flexprice billing model

​

Why Separate Items Per Price?

• Plan: “Pro Plan” with prices in USD and EUR
• Result: 2 items created (charge_uuid1 for USD, charge_uuid2 for EUR)

​

Item Price Sync

​

Pricing Model Mapping

​

Flat Fee / Per Unit Pricing

{
  "id": "price_123",
  "item_id": "charge_uuid1",
  "pricing_model": "flat_fee",
  "price": 1000,  // Amount in smallest currency unit (cents for USD)
  "currency_code": "USD"
}

• price: Amount converted to smallest currency unit (cents for USD, paise for INR)
• No tiers required
• Simple fixed pricing

​

Package Pricing

{
  "id": "price_123",
  "item_id": "charge_uuid1",
  "pricing_model": "package",
  "price": 1000,
  "currency_code": "USD",
  "period": 10,  // Optional: package size
  "period_unit": "month"
}

• price: Package price in smallest currency unit
• period: Optional package size (e.g., 10 units per package)
• Used for bulk pricing models

​

Tiered Pricing

{
  "id": "price_123",
  "item_id": "charge_uuid1",
  "pricing_model": "volume",
  "currency_code": "USD",
  "tiers": [
    {
      "starting_unit": 1,
      "ending_unit": 1000,
      "price": 100  // Price per unit in this tier (in cents)
    },
    {
      "starting_unit": 1001,
      "ending_unit": 10000,
      "price": 80
    },
    {
      "starting_unit": 10001,
      "ending_unit": null,  // Last tier has no ending
      "price": 60
    }
  ]
}

• tiers: Array of tier definitions
• starting_unit: Minimum quantity for this tier (1-based)
• ending_unit: Maximum quantity for this tier (null for last tier)
• price: Price per unit in this tier (in smallest currency unit)
• Tiers are converted from Flexprice tier format to Chargebee format

​

Tier Conversion

{
  "up_to": 1000,
  "unit_amount": 1.00
}

{
  "starting_unit": 1,
  "ending_unit": 1000,
  "price": 100  // 1.00 USD = 100 cents
}

1. unit_amount converted to smallest currency unit (e.g., $1.00 → 100 cents)
2. up_to becomes ending_unit
3. starting_unit calculated from previous tier’s ending_unit + 1
4. First tier always starts at 1
5. Last tier has ending_unit: null

​

Amount Conversion

​

Currency Precision

amount_in_smallest_unit = amount × 10^precision

​

Why Convert to Smallest Unit?

​

Entity Mapping

​

Mapping Storage

• Entity Type: item_price
• Entity ID: Flexprice price ID
• Provider Entity ID: Chargebee item price ID
• Provider Type: chargebee

​

Display Names

​

External Names

• “API Calls - USD”
• “Pro Plan - EUR”
• “Storage - INR”

1. Feature name (if price has a meter/feature)
2. Meter name (if feature not found)
3. Plan name (fallback)

​

Error Handling

​

Common Sync Errors

​

Sync Failure Recovery

1. Partial Sync: Some items may be created even if others fail
2. Retry: Re-sync the plan to create missing items
3. Manual Cleanup: Remove failed items from Chargebee if needed
4. Logs: Check application logs for detailed error messages

​

Best Practices

​

Item Family Management

1. Single Family: Use one item family for all Flexprice items (simplifies management)
2. Naming: Use descriptive names (e.g., “Flexprice Charges”)
3. Organization: Group related items in the same family

​

Price Sync Strategy

1. Sync Before Invoicing: Always sync plans before creating invoices
2. Currency Separation: Each currency requires a separate item
3. Tier Precision: Be aware that tier calculations may have slight differences due to rounding

​

Testing

1. Test Environment: Use Chargebee test mode for development
2. Verify Items: Check created items in Chargebee dashboard
3. Test Invoices: Create test invoices to verify item prices work correctly

​

Next Steps

1. Verify Items: Check created items in Chargebee dashboard
2. Test Invoice Sync: Create a test invoice and sync to Chargebee
3. Monitor Mappings: Ensure entity mappings are created correctly
4. Go Live: Switch to production when ready