billing

name	billing
description	Use when creating, updating, reviewing, or debugging billing, payments, subscriptions, invoices, checkout, payment providers, webhooks, refunds, plans, or paid access.

Billing

Use this skill for safe billing, payment, subscription, and paid-access flows.

Rules

• Follow the project’s existing billing and payment architecture.
• Do not add a new payment provider, billing library, queue system, or subscription model unless already used or explicitly requested.
• Treat all payment operations as sensitive.
• Never trust client-side payment success alone.
• Verify provider webhooks before updating billing, order, subscription, or access state.
• Use idempotency for payment creation, webhook handling, refunds, and retries.
• Store local billing/subscription state when the app needs fast access checks.
• Do not query the payment provider on every access-control check unless this is already the project pattern.
• Do not log card data, secrets, webhook secrets, tokens, client secrets, signed URLs, or sensitive provider payloads.
• Preserve existing response, error, logging, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing billing code, check existing patterns for:

• payment provider
• checkout/payment flow
• subscription model
• invoice/refund model
• webhook handling
• idempotency
• paid access checks
• user/customer mapping
• background jobs
• test style

Implementation Checklist

• Reuse existing provider clients, services, models, and helpers.
• Validate all client input.
• Create payment/session/subscription operations idempotently.
• Store provider IDs when the project does this.
• Verify webhook signatures before trusting events.
• Process webhook events idempotently.
• Track processed provider event IDs when supported.
• Update local billing state safely.
• Enforce paid access from trusted server-side state.
• Add or update relevant tests.

Webhook Rules

• Verify signature before parsing or processing.
• Use raw body when the provider requires it.
• Reject invalid signatures.
• Ignore duplicate events safely.
• Keep webhook handlers small.
• Move heavy work to existing background jobs if available.
• Do not expose webhook secrets or raw provider errors.

Subscription and Access Rules

• Follow existing subscription/status values.
• Do not invent new statuses if the project already has them.
• Use verified provider events to update local state.
• Do not grant paid access from client-only confirmation.
• Check paid access server-side.
• Prevent users from accessing another user’s customer, invoice, subscription, or payment data.
• For team/org/tenant billing, verify membership and permissions.

Refund and Cancellation Rules

• Follow the existing provider integration.
• Verify permission before canceling, refunding, or changing plans.
• Use idempotency for repeatable provider actions.
• Update local state only after confirmed provider action or verified webhook.
• Keep audit records if the project supports them.

Failure Handling

• Invalid input: fail safely.
• Provider failure: return safe error and keep state recoverable.
• Duplicate webhook/payment event: skip safely.
• Payment failure: update state according to existing business rules.
• Partial failure: avoid inconsistent billing/access state.
• Never expose raw provider errors or secrets to clients.

Tests

Cover relevant paths:

• payment/session creation
• invalid input
• unauthorized billing action
• forbidden billing access
• webhook signature verification
• duplicate webhook event
• idempotency behavior
• subscription activation/cancellation
• refund or plan change
• paid access allowed/denied
• provider failure handling