🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Billing
πŸ¦€ ClawHub

Billing

by @ivangdavila

Build payment integrations, subscription management, and invoicing systems with webhook handling, tax compliance, and revenue recognition.

Versionv1.0.0
Downloads1,200
Stars⭐ 3
#clawhub
TERMINAL
clawhub install billing

πŸ“– About This Skill

name: Billing slug: billing version: 1.0.0 description: Build payment integrations, subscription management, and invoicing systems with webhook handling, tax compliance, and revenue recognition. metadata: {"clawdbot":{"emoji":"πŸ’³","requires":{"bins":[]},"os":["linux","darwin","win32"]}}

When to Use

User needs to implement or debug payment processing, subscription lifecycles, invoicing, or revenue operations. Agent handles Stripe/Paddle integration, webhook architecture, multi-currency, tax compliance, chargebacks, usage-based billing, marketplace splits, and revenue recognition patterns.

Quick Reference

| Topic | File | |-------|------| | Stripe integration | stripe.md | | Webhooks & events | webhooks.md | | Subscription lifecycle | subscriptions.md | | Invoice generation | invoicing.md | | Tax compliance | tax.md | | Usage-based billing | usage-billing.md | | Chargebacks & disputes | disputes.md | | Marketplace payments | marketplace.md | | Revenue recognition | revenue-recognition.md |

Core Rules

1. Money in Smallest Units, Always

  • Stripe/most PSPs use cents: amount: 1000 = $10.00
  • Store amounts as integers, NEVER floats (floating-point math fails)
  • Always clarify currency in variable names: amount_cents_usd
  • Different currencies have different decimal places (JPY has 0, KWD has 3)

    • 2. Webhook Security is Non-Negotiable

  • ALWAYS verify signatures before processing (Stripe-Signature header)
  • Store event_id and check idempotency β€” webhooks duplicate
  • Events arrive out of order β€” design state machines, not sequential flows
  • Use raw request body for signature verification, not parsed JSON
  • See webhooks.md for implementation patterns

    • 3. Subscription State Machine

    Critical states and transitions: | State | Meaning | Access | |-------|---------|--------| | trialing | Free trial period | βœ… Full | | active | Paid and current | βœ… Full | | past_due | Payment failed, retrying | ⚠️ Grace period | | canceled | Will end at period end | βœ… Until period_end | | unpaid | Exhausted retries | ❌ None |

    Never grant access based on status === 'active' alone β€” check current_period_end.

    4. Cancel vs Delete: Revenue at Stake

  • cancel_at_period_end: true β†’ Access until period ends, stops renewal
  • subscription.delete() β†’ Immediate termination, possible refund
  • Confusing these loses revenue OR creates angry customers
  • Default to cancel-at-period-end; immediate delete only when requested

    • 5. Proration Requires Explicit Choice

    When changing plans mid-cycle: | Mode | Behavior | Use When | |------|----------|----------| | create_prorations | Credit unused, charge new | Standard upgrades | | none | Change at renewal only | Downgrades | | always_invoice | Immediate charge/credit | Enterprise billing |

    Never rely on PSP defaults β€” specify explicitly every time.

    6. Race Conditions Are Guaranteed

    customer.subscription.updated fires BEFORE invoice.paid frequently.
  • Design for eventual consistency
  • Use database transactions for access changes
  • Idempotent handlers that can safely reprocess
  • Status checks before granting/revoking access

    • 7. Tax Compliance Is Not Optional

    | Scenario | Action | |----------|--------| | Same country | Charge local VAT/sales tax | | EU B2B + valid VAT | 0% reverse charge (verify via VIES) | | EU B2C | MOSS β€” charge buyer's country VAT | | US | Sales tax varies by 11,000+ jurisdictions | | Export (non-EU) | 0% typically |

    Missing required invoice fields = legally invalid invoice. See tax.md.

    8. PCI-DSS: Never Touch Card Data

  • NEVER store PAN, CVV, or magnetic stripe data
  • Only store PSP tokens (pm_*, cus_*)
  • Tokenization happens client-side (Stripe.js, Elements)
  • Even "last 4 digits + expiry" is PCI scope if stored together
  • See disputes.md for compliance patterns

    • 9. Chargebacks Have Deadlines

    | Stage | Timeline | Action | |-------|----------|--------| | Inquiry | 1-3 days | Provide evidence proactively | | Dispute opened | 7-21 days | Submit compelling evidence | | Deadline missed | Automatic loss | Set alerts |

    >3 intentos de cobro fallidos consecutivos = posible trigger de fraude monitoring.

    10. Revenue Recognition β‰  Cash Collected

    For SaaS under ASC 606/IFRS 15:
  • Annual payment β‰  annual revenue (recognized monthly)
  • Deferred revenue is a liability, not an asset
  • Multi-element contracts require allocation to performance obligations
  • See revenue-recognition.md for accounting patterns

    • Billing Traps

    Security & Compliance

  • Webhook without signature verification β†’ attackers fake invoice.paid
  • Storing tokens in frontend JS β†’ extractable by attackers
  • CVV in logs β†’ PCI violation, massive fines
  • Retry loops without limits β†’ fraud monitoring triggers

    • Integration Errors

  • Not storing subscription_id β†’ impossible to reconcile refunds
  • Assuming charge success = payment complete (3D Secure exists)
  • Ignoring payment_intent.requires_action β†’ stuck payments
  • Using mode: 'subscription' without handling customer.subscription.deleted

    • Financial Errors

  • Hardcoding tax rates β†’ wrong when rates change
  • Amounts in dollars when PSP expects cents β†’ 100x overcharge
  • Recognizing 100% revenue upfront on annual plans β†’ audit findings
  • Confusing bookings vs billings vs revenue β†’ material discrepancies

    • Operational Errors

  • Sending payment reminders during contractual grace period
  • Dunning without checking for open disputes β†’ double loss
  • Proration without specifying mode β†’ unexpected customer charges
  • Refunding without checking for existing chargeback β†’ paying twice

    • ⚑ When to Use

    User needs to implement or debug payment processing, subscription lifecycles, invoicing, or revenue operations. Agent handles Stripe/Paddle integration, webhook architecture, multi-currency, tax compliance, chargebacks, usage-based billing, marketplace splits, and revenue recognition patterns.