> ## Documentation Index
> Fetch the complete documentation index at: https://dodopayments-mintlify-external-integration-datafast-autosen.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Credits

> Learn how to manage customer credit balances, issue service credits, and handle billing adjustments seamlessly with Dodo Payments.

<CardGroup cols={1}>
  <Card title="API Reference - Customer Credits" icon="code" href="/api-reference/customers/get-customer-wallets">
    Access the complete API documentation for managing customer credits and test credit operations interactively.
  </Card>
</CardGroup>

## What is Customer Credit?

Customer Credits provide a flexible way to manage customer balances and enhance billing relationships. With customer credits, you can:

* **Reward loyal customers** with account credits for exceptional service or loyalty programs
* **Issue service credits** to compensate for service interruptions or billing adjustments
* **Handle manual adjustments** without disrupting existing billing cycles
* **Provide refunds** that customers can use for future purchases

<Info>
  Customer credits create a positive balance in a customer's account that automatically applies to future subscription payments, reducing the amount charged to their payment method.
</Info>

## How Customer Credits Work

Customer credits operate on a simple principle: available credit is automatically applied to subscription payments before charging the customer's payment method.

### Automatic Credit Application

When a subscription payment is due, Dodo Payments follows this payment sequence:

<Steps>
  <Step title="Check Credit Balance">
    The system checks if the customer has available credit in their account.
  </Step>

  <Step title="Apply Available Credit">
    If credit is available, it's automatically applied to reduce the payment amount.
  </Step>

  <Step title="Calculate Remaining Balance">
    Any remaining amount after credit application is charged to the customer's payment method.
  </Step>

  <Step title="Process Payment">
    The final payment is processed for the remaining balance, if any.
  </Step>
</Steps>

<Info>
  Dodo Payments supports separate credit wallets for INR and USD. Credits added to an INR wallet can only be used for INR subscriptions, while USD wallet credits apply exclusively to USD subscriptions. You cannot use credits from one currency wallet to pay for subscriptions in another currency.
</Info>

### Payment Scenarios

<Tabs>
  <Tab title="Full Credit Coverage">
    **Scenario**: Customer has 60 USD credit, subscription costs 20 USD

    **Result**:

    * \$20 deducted from credit balance
    * \$0 charged to payment method
    * Remaining credit: \$40

    <Check>
      No payment method charge required when credit fully covers the subscription cost.
    </Check>
  </Tab>

  <Tab title="Partial Credit Coverage">
    **Scenario**: Customer has 60 USD credit, subscription costs 100 USD

    **Result**:

    * \$60 deducted from credit balance
    * \$40 charged to payment method
    * Remaining credit: \$0

    <Info>
      Credits are always applied first, minimizing the charge to the customer's payment method.
    </Info>
  </Tab>

  <Tab title="No Credit Available">
    **Scenario**: Customer has 0 USD credit, subscription costs 50 USD

    **Result**:

    * \$0 deducted from credit balance
    * \$50 charged to payment method
    * Remaining credit: \$0
  </Tab>
</Tabs>

## Managing Customer Credits

Effectively manage customer credit balances through the Dodo Payments dashboard with comprehensive credit and debit operations.

### Adding Credits to Customer Accounts

Increase customer account balances by adding credits for various business scenarios:

<Steps>
  <Step title="Navigate to Customer Details">
    Go to **Customers** in your dashboard and select the specific customer you want to manage.
  </Step>

  <Step title="Access Credit Ledger">
    Navigate to the **Credit Ledger** section on the customer detail page.

    <Info>
      The Credit Ledger provides a complete transaction history and current balance overview for the customer.
    </Info>
  </Step>

  <Step title="Initiate Credit Application">
    Click **Apply Credit** to open the credit management interface.
  </Step>

  <Step title="Configure Credit Details">
    Set up the credit transaction with the following information:

    <ParamField path="Transaction Type" type="string" required>
      Select **Credit** to add funds to the customer's account balance.
    </ParamField>

    <ParamField path="Amount" type="number" required>
      Enter the credit amount to add to the customer's account.
    </ParamField>

    <ParamField path="Currency" type="string" required>
      Choose the currency for the credit transaction:

      * **USD** - US Dollars
      * **INR** - Indian Rupees
    </ParamField>

    <ParamField path="Reason" type="string">
      Provide an optional explanation for the credit application, such as "Service compensation" or "Loyalty reward".
    </ParamField>
  </Step>

  <Step title="Apply Credit">
    Review the credit details and click **Apply** to add the credit to the customer's account.

    <Check>
      The credit is immediately available for use on the customer's next subscription payment.
    </Check>
  </Step>
</Steps>

### Removing Credits (Debit Operations)

Remove funds from customer accounts when adjustments or corrections are needed:

<Steps>
  <Step title="Access Credit Management">
    Follow the same navigation path: **Customers** → **Customer Detail Page** → **Credit Ledger** → **Apply Credit**.
  </Step>

  <Step title="Configure Debit Transaction">
    Set up the debit operation:

    <ParamField path="Transaction Type" type="string" required>
      Select **Debit** to remove funds from the customer's account balance.
    </ParamField>

    <ParamField path="Amount" type="number" required>
      Enter the amount to deduct from the customer's credit balance.
    </ParamField>

    <ParamField path="Currency" type="string" required>
      Choose the appropriate currency (USD or INR).
    </ParamField>

    <ParamField path="Reason" type="string">
      Provide an explanation for the debit, such as "Billing correction" or "Credit adjustment".
    </ParamField>

    <Warning>
      Ensure the customer has sufficient credit balance before applying a debit. Negative balances are not supported.
    </Warning>
  </Step>

  <Step title="Apply Debit">
    Review and confirm the debit transaction to remove the specified amount from the customer's account.
  </Step>
</Steps>

## Understanding the Credit Ledger

The Credit Ledger provides comprehensive tracking and transparency for all customer credit transactions.

### Available Credit Balance

The customer's available credit balance is prominently displayed at the top of the Credit Ledger interface, providing immediate visibility into their current credit status.

**Total Balance Overview**\
The main balance display shows the combined credit amount across all supported currencies, converted to a single currency for easy reference. This unified view helps you quickly assess the customer's total available credit without needing to calculate across multiple currencies.

<Tip>
  The total balance is automatically calculated using current exchange rates to provide an accurate combined view of multi-currency credits.
</Tip>

**Currency Breakdown**
Click the "View Breakdown" button to expand the detailed view and see individual balances for each currency:

* **USD Balance**: Shows the exact amount available in US Dollars
* **INR Balance**: Shows the exact amount available in Indian Rupees
* **Additional Currencies**: Any other currencies with available credit balances

<Note>
  The breakdown view is particularly useful when managing customers who make payments in multiple currencies or when you need to verify specific currency allocations.
</Note>

### Ledger Entry Components

Each transaction in the Credit Ledger contains the following information:

<ResponseField name="Entry ID" type="string">
  Unique identifier for each credit transaction, ensuring complete auditability.
</ResponseField>

<ResponseField name="Reference ID" type="string">
  Payment ID when the transaction is linked to a specific payment or billing event.
</ResponseField>

<ResponseField name="Event Type" type="string">
  The type of transaction that created this ledger entry:

  * **Payment** - Credit used for subscription payment
  * **PaymentReversal** - Payment reversal creating credit
  * **Refund** - Refund processed as credit
  * **RefundReversal** - Refund reversal removing credit
  * **Dispute** - Dispute-related credit adjustment
  * **DisputeReversal** - Dispute resolution adjustment
  * **MerchantAdjustment** - Manual credit/debit by merchant
</ResponseField>

<ResponseField name="Amount" type="number">
  The transaction amount, showing positive values for credits and negative values for debits.
</ResponseField>

<ResponseField name="Before Balance" type="number">
  Customer's credit balance before this transaction was processed.
</ResponseField>

<ResponseField name="After Balance" type="number">
  Customer's credit balance after this transaction was completed.
</ResponseField>

<ResponseField name="Reason" type="string">
  Optional explanation provided when the transaction was created.
</ResponseField>

<ResponseField name="Created At" type="timestamp">
  When the transaction was processed, in ISO 8601 format.
</ResponseField>

## Real-World Credit Scenarios

Understanding practical applications helps you leverage customer credits effectively for business growth and customer satisfaction.

### Scenario Examples

<AccordionGroup>
  <Accordion title="Service Credit for Downtime">
    **Situation**: Your service experienced a 2-hour outage affecting a premium customer.

    **Action**: Apply a 25 USD service credit with reason "Compensation for service downtime on \[date]"

    **Result**: Customer receives credit that automatically applies to their next USD 50 subscription, reducing their charge to \$25.

    **Business Impact**: Maintains customer satisfaction and demonstrates commitment to service quality.
  </Accordion>

  <Accordion title="Loyalty Reward Program">
    **Situation**: A customer has been subscribed for 12 consecutive months.

    **Action**: Apply a \$10 loyalty credit with reason "Annual loyalty reward - Thank you for being with us!"

    **Result**: Customer receives unexpected value, strengthening retention and brand loyalty.

    **Business Impact**: Proactive customer appreciation that encourages continued subscription.
  </Accordion>
</AccordionGroup>

## Current Limitations

<Warning>
  The following features are planned for Phase 2 release and are not currently available:
</Warning>

### Checkout Integration

Customer credits cannot currently be applied during the checkout process. Customers cannot view or use their available credit balance when making new purchases through payment pages.

**Planned Enhancement**: Future releases will include credit balance display and application options in checkout flows.

### One-Time Payment Products

Credits are currently only applicable to recurring subscription payments. They cannot be used for one-time payment products or single purchases.