Chargebee Invoice Sync & Webhook Handling

​

Overview

​

Key Features

• Automatic Sync: Invoices sync automatically when finalized
• Precision Handling: Different strategies for flat fee vs tiered pricing
• Customer Auto-Sync: Customers are synced automatically during invoice sync
• Webhook Processing: Payment webhooks update invoice status automatically
• Amount Accuracy: Ensures exact amount matching with Flexprice calculations

​

Invoice Sync Flow

​

Invoice Sync Timing

1. Invoice Finalization: Invoice status changes from DRAFT to FINALIZED
2. Invoice Sync Enabled: Invoice outbound sync is enabled in Chargebee connection
3. Connection Active: Chargebee connection exists and is active

• Invoices can also be synced manually via API if needed

​

Line Item Handling

​

Critical: Different Strategies by Pricing Model

​

Flat Fee / Per Unit / Package Pricing

{
  "item_price_id": "price_123",
  "quantity": 1,
  "unit_amount": 1000  // Exact amount in smallest currency unit (cents)
}

• Chargebee has 2 decimal precision limitations
• Sending exact amount as unit_amount ensures perfect accuracy
• Quantity=1 means “charge this exact amount once”
• Prevents rounding errors from quantity × unit_price calculations

• Flexprice amount: $10.50
• Sent to Chargebee: quantity=1, unit_amount=1050 (cents)
• Result: Exact $10.50 charge

​

Tiered Pricing

{
  "item_price_id": "price_123",
  "quantity": 1500
  // NO unit_amount - Chargebee calculates based on tiers
}

• Tier calculations involve complex multi-tier math
• Chargebee’s tier calculation may differ slightly due to rounding
• Sending quantity allows Chargebee to apply its tier logic correctly
• Prevents precision mismatches from manual tier calculations

• DO NOT set unit_amount for tiered pricing (Chargebee will reject it)
• Chargebee calculates the amount based on tier definitions
• There may be slight differences (usually < $0.01) due to rounding
• This is expected and acceptable for tiered pricing

• Flexprice quantity: 1500 units
• Flexprice calculated amount: $125.75
• Sent to Chargebee: quantity=1500 (no unit_amount)
• Chargebee calculates: $125.74 (may differ slightly)
• Difference: $0.01 (acceptable rounding difference)

​

Pricing Model Detection

1. Lookup Item Price: Retrieves Chargebee item price by Flexprice price ID
2. Check Pricing Model: Reads pricing_model from Chargebee item price
3. Determine Strategy:
   • If tiered, volume, or stairstep → Send quantity only
   • Otherwise → Send quantity=1 + unit_amount

​

Amount Conversion

​

Currency Precision

amount_in_smallest_unit = round(amount × 10^precision)

​

Why 2 Decimal Precision Matters

• 2 decimal currencies (USD, EUR, INR): Stored as cents/paise
• 0 decimal currencies (JPY): Stored as whole units

• If we send quantity × unit_price for flat fees, rounding errors can occur
• Example: quantity=1, unit_price=10.505 → rounds to 10.51 (wrong!)
• Solution: Send exact amount as unit_amount with quantity=1

​

Invoice Creation

​

Request Structure

{
  "customer_id": "cust_chargebee123",
  "auto_collection": "on",
  "line_items": [
    {
      "item_price_id": "price_123",
      "quantity": 1,
      "unit_amount": 1000
    }
  ],
  "invoice_date": 1642680600,
  "due_date": 1642767000
}

​

Line Item Fields

​

Auto Collection

• Chargebee automatically attempts payment collection
• Uses customer’s default payment method
• Sends payment reminders if needed

​

Entity Mapping

​

Invoice Mapping Storage

• Entity Type: invoice
• Entity ID: Flexprice invoice ID
• Provider Type: chargebee
• Provider Entity ID: Chargebee invoice ID

• Webhook processing (finding Flexprice invoice from Chargebee invoice)
• Duplicate prevention (checking if invoice already synced)
• Status updates (updating Flexprice invoice from Chargebee)

​

Webhook Handling

​

Supported Webhooks

​

Webhook URL Format

https://api.cloud.flexprice.io/v1/webhooks/chargebee/{tenant_id}/{environment_id}

​

Webhook Authentication

1. Configure in Chargebee: Set username and password in webhook settings
2. Store in Connection: Save credentials in Chargebee connection
3. Verify on Receipt: Flexprice verifies Basic Auth credentials
4. Optional: If not configured, webhooks are still accepted (less secure)

​

Payment Succeeded Webhook

{
  "event_type": "payment_succeeded",
  "content": {
    "transaction": {
      "id": "txn_123",
      "amount": 1000,
      "currency_code": "USD",
      "payment_method": "card"
    },
    "invoice": {
      "id": "inv_chargebee123"
    }
  }
}

1. Receive Webhook: Flexprice receives the webhook
2. Verify Auth: Verify Basic Authentication (if configured)
3. Find Invoice: Look up Flexprice invoice ID from Chargebee invoice ID
4. Check Duplicate: Verify payment doesn’t already exist
5. Create Payment: Create payment record in Flexprice
6. Update Invoice: Update invoice payment status and amounts
7. Reconcile: Reconcile invoice with payment

​

Payment Record Creation

{
  "id": "pay_123",
  "destination_type": "INVOICE",
  "destination_id": "inv_flexprice123",
  "amount": "10.00",
  "currency": "USD",
  "payment_status": "SUCCEEDED",
  "payment_gateway": "chargebee",
  "gateway_payment_id": "txn_123",
  "succeeded_at": "2024-01-20T10:30:00Z"
}

• Payments are checked for duplicates using gateway_payment_id
• Prevents duplicate payment records from webhook retries

​

Error Handling

​

Common Sync Errors

​

Webhook Errors

​

Best Practices

​

Invoice Sync

1. Sync Plans First: Always sync plans to Chargebee before creating invoices
2. Verify Items: Ensure item prices exist in Chargebee
3. Check Amounts: Verify amounts match between Flexprice and Chargebee

​

Amount Precision

1. Flat Fees: Always use quantity=1 + exact unit_amount
2. Tiered Pricing: Accept small rounding differences (< $0.01)
3. Currency Awareness: Be aware of currency precision (2 vs 0 decimals)
4. Testing: Test with various amounts to verify precision

​

Testing

​

Test Invoice Sync

1. Create Test Invoice: Create invoice in Flexprice
2. Finalize Invoice: Change status to FINALIZED
3. Verify Sync: Check Chargebee dashboard for invoice
4. Verify Amounts: Compare amounts between Flexprice and Chargebee
5. Test Payment: Process test payment in Chargebee
6. Verify Webhook: Check payment record in Flexprice

​

Next Steps

1. Sync Plans: Ensure all plans are synced to Chargebee
2. Create Invoices: Create and finalize invoices
3. Monitor Sync: Check sync status and logs
4. Test Payments: Process test payments and verify webhooks
5. Go Live: Switch to production when ready