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

# Offer billing credits

<div className="m-badge-page-wrapper">
  <Badge stroke color="orange" size="sm">Limited Release</Badge>
</div>

Billing credits are non-monetary grants that customers purchase or receive upfront to pay for their usage-based subscriptions. To offer billing credits, you create a digital wallet for each customer.

Billing credits have two types:

* **Prepaid credits**: Customers purchase with real money for advance payment.
* **Granted credits**: Free promotional credits you provide to customers.

Billing credits connect the following:

* <a href="/limited-release/usage-based-billing/set-up-billing-process/register-customers" target="_blank" rel="noopener noreferrer">Customers</a> who purchase or receive credits to pay for usage-based charges.
* Digital wallets that hold and manage credits for each customer.

<Warning>
  When PayPal generates invoices, billing credits are consumed first before charging payment methods.
</Warning>

## Prerequisite

Ensure you have <a href="/limited-release/usage-based-billing/set-up-billing-process/register-customers" target="_blank" rel="noopener noreferrer">registered customers</a> with valid `external_id` values and payment methods.

## 1. Understand wallet configuration

Before creating a wallet, understand the available configuration options.

**Basic wallet configuration**

* **Rate amount**: Specify the cost per credit in real money (example: rate amount of \$1.00 means 10 credits cost \$10.00).
* **Paid credits**: Specify the credits customers purchase with real money.
* **Granted credits**: Specify the free promotional credits you provide to customers.

**Applicability scope**

* **Fee types**: Determine which types of charges the credits can pay for. You can specify subscription fees, usage-based charges, minimum commitments, or any combination of these.
  <Note>
    If you do not specify the fee types scope, wallet credits apply to all three charge types by default.
  </Note>
* **Expiration date**: Optionally set when the credits expire if you want to create time-limited promotional offers or enforce credit usage policies.

**Automatic top-up configuration**

**Recurring transaction rules**: Set up automated rules that define when and how credits are added to the wallet. When you include the `recurring_transaction_rules[]` array in your wallet configuration, the `method` and `trigger` fields are mandatory for each rule.

| Method   | Description                            | Required field                       |
| -------- | -------------------------------------- | ------------------------------------ |
| `fixed`  | Add a specific amount of credits.      | `paid_credits` or `granted_credits`. |
| `target` | Add credits to reach a target balance. | `target_ongoing_balance`.            |

| Trigger     | Description                                                  | Required field       |
| ----------- | ------------------------------------------------------------ | -------------------- |
| `interval`  | At scheduled intervals (weekly, monthly, quarterly, yearly). | `interval`.          |
| `threshold` | When credits drop to less than a specific amount.            | `threshold_credits`. |

**Additional configuration**

| Configuration              | Description                                                                                                                                                          |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Threshold credits**      | When using `THRESHOLD` trigger, specify the credit balance that triggers automatic top-ups. The system adds credits when the wallet balance is less than this value. |
| **Target ongoing balance** | When using `TARGET` method, set the desired credit balance the wallet should maintain. The system calculates and adds the exact amount needed to reach this target.  |
| **Credit allocation**      | For each rule, specify whether to add paid credits, granted credits, or both when the automatic top-up triggers.                                                     |

| Method + Trigger                                                             | How the combination works                                                           | Required fields                                           |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [Fixed amount + Schedule](#fixed-amount-with-schedule-trigger)               | Adds fixed credits at regular intervals.                                            | `interval`, `paid_credits` OR `granted_credits`.          |
| [Fixed amount + Balance threshold](#fixed-amount-with-threshold-trigger)     | Adds fixed credits when balance is less than threshold.                             | `threshold_credits`, `paid_credits` OR `granted_credits`. |
| [Target balance + Schedule](#target-balance-with-schedule-trigger)           | Tops up with variable credits to achieve target balance at scheduled times.         | `interval`, `target_ongoing_balance`.                     |
| [Target balance + Balance threshold](#target-balance-with-threshold-trigger) | Tops up with variable credits to achieve target balance when threshold is breached. | `threshold_credits`, `target_ongoing_balance`.            |

## 2. Create wallet and add credits

You can create a basic wallet, or include [automatic top-up rules](#automatic-top-up-variations) to automatically replenish credits.

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a POST call to the `/v1/commerce/billing/wallets` endpoint. Include the following parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                                                                                                                 | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `external_customer_id`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                   | Set to the `external_id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/register-customers" target="_blank" rel="noopener noreferrer">registered the customer</a>.                           |
| `name`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                                                      | Provide a human-readable name to identify the wallet.                                                                                                                                                                                |
| `rate_amount`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                            | Set the cost per credit unit (for example, `"1.0"` means each credit costs \$1.00).                                                                                                                                                  |
| `paid_credits`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                                              | Set the initial paid credits to add when creating the wallet.                                                                                                                                                                        |
| `granted_credits`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                                           | Set the initial promotional or free credits to add when creating the wallet.                                                                                                                                                         |
| `currency`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                               | Set the three-letter ISO 4217 currency code (for example, `USD`). See <a href="https://developer.paypal.com/docs/reports/reference/paypal-supported-currencies/" target="_blank" rel="noopener noreferrer">supported currencies</a>. |
| `expiration_at`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                                                                                             | Set when the wallet and its credits expire in ISO 8601 format with timezone.                                                                                                                                                         |
| `applies_to.fee_types[]`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                                                                                     | Specify which fee types credits can pay for.<br /><br /><b>Possible values:</b> `SUBSCRIPTION`, `COMMITMENT`, `CHARGE`                                                                                                               |
| `recurring_transaction_rules[]`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                                                                              | Add automatic top-up rule configurations. See [Automatic top-up configuration](#automatic-top-up-configuration).                                                                                                                     |
| `recurring_transaction_rules[].method`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required when `recurring_transaction_rules[]` is included</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>  | Set to `FIXED` to add a specific amount of credits or `TARGET` to add credits to reach a target balance. See [Automatic top-up configuration](#automatic-top-up-configuration).                                                      |
| `recurring_transaction_rules[].trigger`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required when `recurring_transaction_rules[]` is included</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Set to `INTERVAL` for scheduled intervals or `THRESHOLD` to trigger when credits drop below a specific amount. See [Automatic top-up configuration](#automatic-top-up-configuration).                                                |

For information on all parameters, see <a href="/reference/api/rest/wallets/create-a-new-wallet" target="_blank" rel="noopener noreferrer">API reference</a>.

### Basic wallet example

The following example shows the fundamental structure of a basic wallet creation request where you manually add credits when required.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "external_customer_id": "ext_cus_1234567890abcdef",
    "name": "Prepaid Wallet",
    "rate_amount": "1.0",
    "paid_credits": "110.0",
    "currency": "USD",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION"
      ]
    },
    "expiration_at": "2026-08-12T12:43:31Z"
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "id": "13fddcdc-725b-4ca7-a522-a162ff038567",
    "external_customer_id": "ext_cus_1234567890abcdef",
    "status": "ACTIVE",
    "available_balance": {
      "value": 110,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 0,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 110,
      "currency_code": "USD"
    },
    "name": "Prepaid Wallet",
    "rate_amount": "1.0",
    "available_credits": "110.0",
    "consumed_credits": "0.0",
    "ongoing_usage_credits": "0.0",
    "net_balance_credits": "110.0",
    "created_at": "2025-09-17T00:00:00Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION"
      ]
    },
    "expiration_at": "2026-08-12T12:43:31Z"
  }
  ```
</CodeGroup>

### Automatic top-up variations

Each automatic top-up strategy requires different properties within the `recurring_transaction_rules[]` array. The following examples show how to configure the various strategies.

#### Fixed amount with schedule trigger

Use this strategy when you want to add predictable credit amounts at regular intervals. This approach adds the same number of credits weekly/monthly regardless of usage patterns, providing consistent credit additions for predictable billing scenarios.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
    "name": "Prepaid",
    "rate_amount": "1.0",
    "paid_credits": "2.0",
    "granted_credits": "1.0",
    "currency": "USD",
    "expiration_at": "2026-10-08T00:00:00Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION",
        "CHARGE",
        "COMMITMENT"
      ]
    },
    "recurring_transaction_rules": [
      {
        "method": "FIXED",
        "paid_credits": "5.5",
        "granted_credits": "1.0",
        "trigger": "INTERVAL",
        "interval": "WEEKLY",
        "started_at": "2025-07-24T17:30:15Z",
        "expiration_at": "2026-10-08T00:00:00Z"
      }
    ]
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "id": "943254a2-0240-4414-bede-c0d211340c53",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
    "status": "ACTIVE",
    "available_balance": {
      "value": 3.00,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 3.00,
      "currency_code": "USD"
    },
    "name": "Prepaid",
    "rate_amount": "1.0",
    "available_credits": "3.0",
    "consumed_credits": "0.0",
    "ongoing_usage_credits": "0.0",
    "net_balance_credits": "3.0",
    "created_at": "2025-07-24T17:57:36Z",
    "expiration_at": "2026-10-08T00:00:00Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION",
        "CHARGE",
        "COMMITMENT"
      ]
    },
    "recurring_transaction_rules": [
      {
        "trigger": "INTERVAL",
        "paid_credits": "5.5",
        "granted_credits": "1.0",
        "method": "FIXED",
        "interval": "WEEKLY",
        "started_at": "2025-07-24T17:30:15Z",
        "expiration_at": "2026-10-08T00:00:00Z",
        "threshold_credits": "0.0"
      }
    ]
  }
  ```
</CodeGroup>

#### Fixed amount with threshold trigger

Use this strategy to prevent service interruption by adding credits when your customer's balance is less than a set amount. Threshold triggers watch actual usage patterns and adds credits only when required.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
    "name": "Prepaid",
    "rate_amount": "1.0",
    "paid_credits": "2.0",
    "granted_credits": "1.0",
    "currency": "USD",
    "expiration_at": "2026-10-08T00:00:00Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION",
        "CHARGE",
        "COMMITMENT"
      ]
    },
    "recurring_transaction_rules": [
      {
        "method": "FIXED",
        "paid_credits": "5.5",
        "granted_credits": "1.0",
        "trigger": "THRESHOLD",
        "threshold_credits": "10.0"
      }
    ]
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "id": "943254a2-0240-4414-bede-c0d211340c54",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
    "status": "ACTIVE",
    "available_balance": {
      "value": 3.00,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 3.00,
      "currency_code": "USD"
    },
    "name": "Prepaid",
    "rate_amount": "1.0",
    "available_credits": "3.0",
    "consumed_credits": "0.0",
    "ongoing_usage_credits": "0.0",
    "net_balance_credits": "3.0",
    "created_at": "2025-07-24T17:57:36Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION",
        "CHARGE",
        "COMMITMENT"
      ]
    },
    "recurring_transaction_rules": [
      {
        "trigger": "THRESHOLD",
        "paid_credits": "5.5",
        "granted_credits": "1.0",
        "method": "FIXED",
        "threshold_credits": "10.0"
      }
    ]
  }
  ```
</CodeGroup>

#### Target balance with schedule trigger

Use this strategy to maintain a minimum balance through regular checks. This approach dynamically calculates the required credits to reach your specified balance during each scheduled interval.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
    "name": "Prepaid",
    "rate_amount": "1.0",
    "paid_credits": "2.0",
    "granted_credits": "1.0",
    "currency": "USD",
    "expiration_at": "2026-10-08T00:00:00Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION"
      ]
    },
    "recurring_transaction_rules": [
      {
        "method": "TARGET",
        "target_ongoing_balance": "200.0",
        "trigger": "INTERVAL",
        "interval": "WEEKLY",
        "started_at": "2025-07-01T17:30:15Z",
        "expiration_at": "2026-10-08T00:00:00Z"
      }
    ]
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "id": "bb0f90f6-dd5f-4244-a6d8-ec42f0e171ce",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
    "status": "ACTIVE",
    "available_balance": {
      "value": 3.00,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 3.00,
      "currency_code": "USD"
    },
    "name": "Prepaid",
    "rate_amount": "1.0",
    "available_credits": "3.0",
    "consumed_credits": "0.0",
    "ongoing_usage_credits": "0.0",
    "net_balance_credits": "3.0",
    "created_at": "2025-07-15T14:53:33Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION"
      ]
    },
    "recurring_transaction_rules": [
      {
        "trigger": "INTERVAL",
        "paid_credits": "0.0",
        "granted_credits": "0.0",
        "method": "TARGET",
        "interval": "WEEKLY",
        "started_at": "2025-07-01T17:30:15Z",
        "expiration_at": "2026-10-08T00:00:00Z",
        "threshold_credits": "0.0",
        "target_ongoing_balance": "200.0"
      }
    ]
  }
  ```
</CodeGroup>

#### Target balance with threshold trigger

Use this strategy to ensure customers always have sufficient credits balance while minimizing unused credit accumulation. This approach combines the efficiency of threshold-based triggering with the precision of target balance calculations - adding credits only when the balance is less than the threshold and calculating the exact amount needed to reach your target balance.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
    "name": "Prepaid",
    "rate_amount": "1.0",
    "paid_credits": "2.0",
    "granted_credits": "1.0",
    "currency": "USD",
    "expiration_at": "2026-10-08T00:00:00Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION"
      ]
    },
    "recurring_transaction_rules": [
      {
        "method": "TARGET",
        "target_ongoing_balance": "200.0",
        "trigger": "THRESHOLD",
        "threshold_credits": "10.00",
        "started_at": "2025-07-29T17:30:15Z",
        "expiration_at": "2026-10-08T00:00:00Z"
      }
    ]
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "id": "bb0f90f6-dd5f-4244-a6d8-ec42f0e171ce",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
    "status": "ACTIVE",
    "available_balance": {
      "value": 3.00,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 3.00,
      "currency_code": "USD"
    },
    "name": "Prepaid",
    "rate_amount": "1.0",
    "available_credits": "3.0",
    "consumed_credits": "0.0",
    "ongoing_usage_credits": "0.0",
    "net_balance_credits": "3.0",
    "created_at": "2025-07-15T14:53:33Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION"
      ]
    },
    "recurring_transaction_rules": [
      {
        "trigger": "THRESHOLD",
        "paid_credits": "0.0",
        "granted_credits": "0.0",
        "method": "TARGET",
        "started_at": "2025-07-29T17:30:15Z",
        "expiration_at": "2026-10-08T00:00:00Z",
        "threshold_credits": "10.0",
        "target_ongoing_balance": "200.0"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `201 Created` response. The response includes the following parameter:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>          | <span style={{textAlign: 'left', display: 'block'}}>Description</span> | <span style={{textAlign: 'left', display: 'block'}}>Further action</span>                                                                                                   |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Unique identifier for the wallet.                                      | Use this `id` when <a href="/limited-release/usage-based-billing/manage-entities/manage-billing-credits" target="_blank" rel="noopener noreferrer">managing the wallet</a>. |

For information on all parameters, see <a href="/reference/api/rest/wallets/create-a-new-wallet" target="_blank" rel="noopener noreferrer">API reference</a>.

## 3. Understand wallet lifecycle and manage wallets

Wallets progress through distinct states throughout their lifecycle. These states determine credit availability and available management actions.

To monitor a wallet's current state, make a GET call to the <a href="/reference/api/rest/wallets/retrieve-a-wallet-by-id" target="_blank" rel="noopener noreferrer">/v1/commerce/billing/wallets/{id}</a> endpoint and review the `status` parameter. The wallet's lifecycle state determines the management actions you can perform to ensure proper wallet handling.

| State          | Description                                   | Credit availability                                      | Possible management actions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------- | --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ACTIVE**     | Wallet is operational and credits can be used | Credits are available for billing.                       | <a href="/limited-release/usage-based-billing/manage-entities/manage-billing-credits#add-credits-to-wallet" target="_blank" rel="noopener noreferrer">Add credits</a> to increase wallet balance.<br /><br /><a href="/limited-release/usage-based-billing/manage-entities/manage-billing-credits#remove-credits-from-wallet" target="_blank" rel="noopener noreferrer">Remove credits</a> to decrease wallet balance.<br /><br /><a href="/limited-release/usage-based-billing/manage-entities/manage-billing-credits#update-wallet" target="_blank" rel="noopener noreferrer">Update wallet</a> configurations and settings.<br /><br /><a href="/limited-release/usage-based-billing/manage-entities/manage-billing-credits#terminate-wallet" target="_blank" rel="noopener noreferrer">Terminate wallet.</a> |
| **PENDING**    | Wallet is created but not yet operational     | Credits cannot be used for billing .                     | <a href="/limited-release/usage-based-billing/manage-entities/manage-billing-credits#update-wallet" target="_blank" rel="noopener noreferrer">Update wallet.</a>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **TERMINATED** | Wallet is permanently disabled                | No credit usage occurs, remaining credits are forfeited. | Wallet cannot be modified.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |