Billing Documentation

Billing & Subscriptions

Manage recurring billing, subscriptions, invoices, and customer billing lifecycle with PayAiML's comprehensive billing platform.

Billing Features

Subscription Management
Flexible recurring billing for any business model
  • • Monthly, yearly, or custom intervals
  • • Proration and plan changes
  • • Trial periods and discounts
Invoice Generation
Automated invoicing with customizable templates
  • • Branded invoice templates
  • • Automatic PDF generation
  • • Multi-currency support
Usage-Based Billing
Charge customers based on actual usage
  • • Metered billing and quotas
  • • Tiered pricing models
  • • Real-time usage tracking
Customer Portal
Self-service billing management for customers
  • • Update payment methods
  • • Download invoices
  • • Manage subscriptions
Dunning Management
Automated retry logic for failed payments
  • • Smart retry schedules
  • • Customer notifications
  • • Subscription recovery
Tax Management
Automated tax calculation and compliance
  • • Global tax compliance
  • • VAT and sales tax
  • • Tax reporting

Implementation Examples

Create a Subscription
Set up recurring billing for a customer
const payaiml = require('@payaiml/node')('sk_test_...');

const subscription = await payaiml.subscriptions.create({
  customer: 'cus_customer_id',
  items: [{
    price: 'price_monthly_plan',
    quantity: 1,
  }],
  trial_period_days: 14,
  collection_method: 'charge_automatically',
  expand: ['latest_invoice.payment_intent'],
});
Generate Invoice
Create and send invoices to customers
const invoice = await payaiml.invoices.create({
  customer: 'cus_customer_id',
  collection_method: 'send_invoice',
  days_until_due: 30,
  auto_advance: true,
});

await payaiml.invoiceItems.create({
  customer: 'cus_customer_id',
  amount: 2500, // $25.00
  currency: 'usd',
  description: 'Professional Plan - Monthly',
  invoice: invoice.id,
});

await payaiml.invoices.finalizeInvoice(invoice.id);
Usage-Based Billing
Track and bill for metered usage
// Report usage for metered billing
await payaiml.subscriptionItems.createUsageRecord(
  'si_subscription_item_id',
  {
    quantity: 100, // API calls made
    timestamp: Math.floor(Date.now() / 1000),
    action: 'increment',
  }
);

// Create tiered pricing
const price = await payaiml.prices.create({
  currency: 'usd',
  product: 'prod_api_calls',
  billing_scheme: 'tiered',
  recurring: { interval: 'month' },
  tiers: [
    { up_to: 1000, flat_amount: 0 },
    { up_to: 10000, unit_amount: 10 },
    { up_to: 'inf', unit_amount: 5 },
  ],
});

Billing Best Practices

Subscription Management
  • • Offer flexible billing cycles
  • • Implement graceful downgrades
  • • Provide clear pricing information
  • • Handle proration transparently
Payment Recovery
  • • Set up smart retry logic
  • • Send payment failure notifications
  • • Offer payment method updates
  • • Implement grace periods
Invoice Management
  • • Use clear, branded templates
  • • Include detailed line items
  • • Provide multiple payment options
  • • Send timely reminders
Customer Experience
  • • Provide self-service options
  • • Show usage and billing history
  • • Enable easy plan changes
  • • Offer billing support

Important Billing Webhooks

Key Events to Monitor
Essential webhook events for billing automation

Subscription Events

  • • customer.subscription.created
  • • customer.subscription.updated
  • • customer.subscription.deleted
  • • customer.subscription.trial_will_end

Invoice Events

  • • invoice.payment_succeeded
  • • invoice.payment_failed
  • • invoice.upcoming
  • • invoice.finalized

Ready to automate your billing?

Start building subscription and billing workflows with PayAiML's powerful APIs.