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

# Credits

> Manage customer credit balances and apply them to invoices

## Overview

Credits allow you to maintain a running balance for each customer that can be applied to reduce invoice amounts. Instead of issuing refunds or adjusting invoices directly, you can grant credits to a customer’s account and let those credits be applied over time.

This approach provides flexibility for handling prepayments, refunds, promotional offers, and billing adjustments, while keeping a clear and auditable record of all changes through the customer’s credit ledger.

## How credits work

Each customer has a credit ledger that tracks every credit-related transaction. When credits are granted, deducted, or applied to invoices, those actions are recorded as entries in the ledger, along with the resulting balance.

The ledger includes:

* **Grant entries** – Credits added to the customer’s account
* **Deduction entries** – Credits removed from the customer’s account
* **Application entries** – Credits applied to specific invoices
* **Running balance** – The available credit balance after each transaction

This structure ensures that every change to a customer’s balance is traceable and tied to a specific action or invoice.

## Granting credits

You can grant credits to a customer either through the Vayu interface or programmatically through the API.

### Through the UI

Navigate to **Customers**, select the relevant customer, and open the **Credits** tab. From there, click **Grant Credits**, enter the amount, and optionally include a note explaining the reason for the credit. Once confirmed, the credits are added to the customer’s balance and recorded in the ledger.

### Through the API

Use the `POST /credits/grant` endpoint to add credits programmatically:

```json theme={null}
{
  "creditAmount": 500,
  "customerId": "customer_123"
}
```

## Credit Ledger

The credit ledger provides a complete audit trail of all credit activity for a customer. It records every grant, deduction, and application of credits, maintaining a running balance that shows the customer's available credit at any point in time.

### Accessing the credit ledger

To view a customer's credit ledger:

1. Navigate to **Customers**
2. Select the customer
3. Go to the **Credits** tab

The ledger displays all credit transactions in chronological order, showing the most recent activity first.

### Transaction types

The credit ledger tracks three types of transactions:

#### Grant transactions

Credits added to the customer's account. These can come from:

* Manual grants through the UI
* API-based credit grants
* Promotional credits
* Service credits for issue resolution

#### Deduction transactions

Credits removed from the customer's account. These include:

* Manual deductions through the API
* Administrative adjustments
* Expired credits (if applicable)

#### Application transactions

Credits applied to reduce invoice amounts. These show:

* The invoice that received the credit
* The amount applied
* The remaining balance after application

### Ledger information

Each ledger entry includes:

* **Transaction type** - Grant, deduct, or application
* **Amount** - The credit value for this transaction
* **Running balance** - Available credit after this transaction
* **Timestamp** - When the transaction occurred
* **Associated invoice** - For application transactions, which invoice was credited
* **Notes** - Optional description or reason for the transaction
* **Created by** - User or system that initiated the transaction

### Viewing credit history via API

You can retrieve a customer's credit ledger programmatically using the `/credits` endpoint:

```bash theme={null}
GET /credits?customerId=customer_123
```

The API returns the complete transaction history with all ledger details.

### **Auditing and compliance**

The credit ledger serves as an immutable audit trail for:

* **Financial reconciliation** - Match credit activity to accounting records
* **Customer inquiries** - Provide transparent history of credit usage
* **Dispute resolution** - Reference exact dates and amounts of credit transactions
* **Compliance reporting** - Track promotional credits or service level agreements

### **Filtering and search**

Use the ledger interface to:

* Filter by transaction type (grants, deductions, applications)
* Search by date range
* View transactions for specific invoices
* Export ledger data for reporting

### **Balance calculation**

The running balance updates with each transaction:

* **Grants** increase the balance
* **Deductions** decrease the balance
* **Applications** decrease the balance and link to an invoice

The current balance represents the total credits available for the customer to use on future invoices.