> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing integration

## Billing integration

Stigg sits alongside your existing billing stack without no rip-and-replace. Payments, taxes, invoicing, and payment methods continue to run through your provider; Stigg handles credit pools, grants, consumption, and enforcement. When money moves, Stigg creates or updates the right credit grant and records everything in the ledger.

### How it works

1. **Payment or invoice**\
   A customer pays by card or you issue an invoice through your billing system.

2. **Grant creation**\
   Stigg creates a **paid grant** with amount, **cost basis** (price per credit), priority, and dates, then updates the customer’s credit pool and writes a ledger entry.

3. **Real-time burn**\
   As usage events arrive, Stigg prices them via your feature→credit mapping and burns credits immediately. No billing migration is required.

4. **Promotional grants**\
   Free credits are issued with **zero cost basis** (no revenue impact) and tracked separately in the ledger.

5. **Refunds and revocations**\
   If you refund in your billing system, revoke the corresponding grant (or its remainder) in Stigg to keep deferred and recognized amounts aligned; the ledger records the revocation.

### Common flows

* **Self-serve top-ups**\
  Let customers buy more credits in-app; after a successful charge, Stigg issues a paid grant and updates the balance. You can define min/max purchase rules and default pricing in the plan.

* **Sales-led purchases (invoice)**\
  Issue an invoice via your billing provider; grant credits when the invoice is issued or paid (per your policy). Cost basis is captured on the grant for revenue reporting.

* **Automatic top-ups**\
  Configure a low-balance trigger, top-up amount, and spend cap. When the threshold is reached, Stigg initiates a purchase via your chosen flow and creates a new grant on success.

### System boundaries

* **Your billing system:** product catalog and prices, taxes, invoicing, payments, refunds/credit memos, collections.
* **Stigg:** credit types and pools, grants/top-ups, real-time consumption and enforcement, ledger/export, customer widgets.

### Reconciliation and reporting

Use the ledger and grants exports to tie purchases, consumption, expirations, and revocations back to invoices and journals in Finance. See the **Integrations** overview and export schema for setup details:

* [Native integrations overview](https://docs.stigg.io/documentation/native-integrations/overview)
* [Data export schema](https://docs.stigg.io/documentation/importing-and-exporting-data/export/schema#schema)

### Overdraft grants and billing

Overdraft grants are **excluded from billing integration**. They are created with `paymentCollection: NOT_REQUIRED` and `paymentCollectionMethod: NONE`, which means:

* **Stripe**: No invoice is created for overdraft grants.
* **Zuora**: No order or invoice is created for overdraft grants.

Overdraft grants represent a deficit, not a purchase - billing occurs when the customer purchases new credits that settle the overdraft.

### Go-live checklist

1. Connect your billing provider in **Integrations**.
2. Create a **credit type** and a **prepaid plan** with pricing and min/max rules.
3. Wire **checkout/top-up** (self-serve) or **invoice** (sales-led) purchase flows.
4. Map **features → credits** and send **event-based usage**.
5. Test: purchase → grant → burn → auto top-up → refund/revoke → export.