> ## 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.

# Manage billing credits

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

Billing credits management helps you control customer credit balances and wallet operations. Managing billing credits means you handle wallet transactions and wallet settings. This makes sure customers have enough credits to pay for their usage charges. It also helps you keep good financial records.

## Manage credit transactions

You can perform the following credit transaction operations:

### Add credits to wallet

You can add credits when a customer buys more credits or gets free promotional 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/{wallet_id}/wallet-transactions` endpoint. Include the following parameters:

**Path parameter**: `wallet_id` is the `id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/offer-billing-credits#2-create-wallet-and-add-credits" target="_blank" rel="noopener noreferrer">created a wallet</a>.

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                               | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `type`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Set to `TOPUP` to add credits.                                                                 |
| `paid_credits`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                            | Set the number of paid credits to add. Must be a positive value.                               |
| `granted_credits`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                         | Set the number of granted (promotional) credits to add. Must be a positive value.              |
| `metadata`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                 | Provide optional metadata for tracking purposes. Each object contains `key` and `value` pairs. |

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

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets/927ba6cc-3025-4203-abb9-ccba67caacc6/wallet-transactions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "type": "TOPUP",
    "paid_credits": "200.0",
    "granted_credits": "100.0",
    "metadata": [
      {
        "key": "reason",
        "value": "customer purchase"
      }
    ]
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "wallet_transactions": [
      {
        "wallet_transaction_id": "8ab3c56a-51e6-4e7c-9f10-332107a31bdc",
        "wallet_id": "927ba6cc-3025-4203-abb9-ccba67caacc6",
        "payment_status": "PENDING",
        "source": "MANUAL",
        "transaction_status": "PURCHASED",
        "transaction_type": "INBOUND",
        "amount": {
          "value": 200.00,
          "currency_code": "USD"
        },
        "credits": "200.0",
        "created_at": "2025-07-30T07:11:49Z"
      },
      {
        "wallet_transaction_id": "7bc4d78b-62f8-5f8d-a011-443218b42ced",
        "wallet_id": "927ba6cc-3025-4203-abb9-ccba67caacc6",
        "payment_status": "SETTLED",
        "source": "MANUAL",
        "transaction_status": "GRANTED",
        "transaction_type": "INBOUND",
        "amount": {
          "value": 100.00,
          "currency_code": "USD"
        },
        "credits": "100.0",
        "settled_at": "2025-07-30T07:11:49Z",
        "created_at": "2025-07-30T07:11:49Z"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with an array of wallet transactions.

### Remove credits from wallet

You do this to give refunds, fix billing mistakes, or remove expired promotional 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/{wallet_id}/wallet-transactions` endpoint. Include the following parameters:

**Path parameter**: `wallet_id` is the `id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/offer-billing-credits#2-create-wallet-and-add-credits" target="_blank" rel="noopener noreferrer">created a wallet</a>.

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                                                                                          | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `type`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>            | Set to `VOID` to remove credits.                                                               |
| `credits_to_void`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Set the number of credits to remove. Must be a positive value.                                 |
| `metadata`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>array</span>                                                                            | Provide optional metadata for tracking purposes. Each object contains `key` and `value` pairs. |

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

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets/927ba6cc-3025-4203-abb9-ccba67caacc6/wallet-transactions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "type": "VOID",
    "credits_to_void": "50.0",
    "metadata": [
      {
        "key": "reason",
        "value": "billing correction"
      }
    ]
  }'
  ```

  ```json lines title="Sample response" theme={null}
  {
    "wallet_transactions": [
      {
        "wallet_transaction_id": "a2c1715d-b8f7-4d66-9f33-691bd065c7ab",
        "wallet_id": "927ba6cc-3025-4203-abb9-ccba67caacc6",
        "payment_status": "SETTLED",
        "source": "MANUAL",
        "transaction_status": "VOIDED",
        "transaction_type": "OUTBOUND",
        "amount": {
          "value": 50.00,
          "currency_code": "USD"
        },
        "credits": "50.0",
        "settled_at": "2025-07-30T07:12:16Z",
        "created_at": "2025-07-30T07:12:16Z"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with an array of wallet transactions.

### Get transaction history

You can get a wallet's transaction history to audit credit movements and reconcile balances.

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 GET call to the `/v1/commerce/billing/wallets/{wallet_id}/wallet-transactions` endpoint.

**Path parameter**: `wallet_id` is the `id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/offer-billing-credits#2-create-wallet-and-add-credits" target="_blank" rel="noopener noreferrer">created a wallet</a>.

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

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets/927ba6cc-3025-4203-abb9-ccba67caacc6/wallet-transactions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "wallet_transactions": [
      {
        "wallet_transaction_id": "a2c1715d-b8f7-4d66-9f33-691bd065c7ab",
        "wallet_id": "927ba6cc-3025-4203-abb9-ccba67caacc6",
        "payment_status": "SETTLED",
        "source": "MANUAL",
        "transaction_status": "VOIDED",
        "transaction_type": "OUTBOUND",
        "amount": {
          "value": 50.00,
          "currency_code": "USD"
        },
        "credits": "50.0",
        "settled_at": "2025-07-30T07:12:16Z",
        "created_at": "2025-07-30T07:12:16Z"
      },
      {
        "wallet_transaction_id": "8ab3c56a-51e6-4e7c-9f10-332107a31bdc",
        "wallet_id": "927ba6cc-3025-4203-abb9-ccba67caacc6",
        "payment_status": "PENDING",
        "source": "MANUAL",
        "transaction_status": "PURCHASED",
        "transaction_type": "INBOUND",
        "amount": {
          "value": 200.00,
          "currency_code": "USD"
        },
        "credits": "200.0",
        "created_at": "2025-07-30T07:11:49Z"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with an array of wallet transactions.

## Manage wallets

You can perform the following wallet management operations:

### List wallets

You can view customer wallet collections, find wallets by specific criteria, or create reports across multiple wallets.

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 GET call to the `/v1/commerce/billing/wallets` endpoint.

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

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets?external_customer_id=5eb02857-a71e-4ea2-bcf9-1753842358&page=1&per_page=10' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "wallets": [
      {
        "id": "635b39e4-5db1-45dd-b774-acdc0b0e78ba",
        "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
        "status": "ACTIVE",
        "available_balance": {
          "value": 150.00,
          "currency_code": "USD"
        },
        "ongoing_usage": {
          "value": 0.00,
          "currency_code": "USD"
        },
        "net_balance": {
          "value": 150.00,
          "currency_code": "USD"
        },
        "name": "Prepaid",
        "available_credits": "150.0",
        "consumed_credits": "50.0",
        "ongoing_usage_credits": "0.0",
        "net_balance_credits": "150.0",
        "applies_to": {
          "fee_types": [
            "SUBSCRIPTION",
            "CHARGE",
            "COMMITMENT"
          ]
        }
      }
    ],
    "metadata": {
      "total_count": 1,
      "total_pages": 1,
      "current_page": 1
    }
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with an array of wallets.

### Get wallet details

You can check current balances, track how customers use credits, or verify wallet status and perform further wallet actions.

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 GET call to the `/v1/commerce/billing/wallets/{wallet_id}` endpoint.

**Path parameter**: `wallet_id` is the `id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/offer-billing-credits#2-create-wallet-and-add-credits" target="_blank" rel="noopener noreferrer">created a wallet</a>.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets/635b39e4-5db1-45dd-b774-acdc0b0e78ba' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "id": "635b39e4-5db1-45dd-b774-acdc0b0e78ba",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
    "status": "ACTIVE",
    "available_balance": {
      "value": 150.00,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 150.00,
      "currency_code": "USD"
    },
    "name": "Prepaid",
    "rate_amount": "1.0",
    "available_credits": "150.0",
    "consumed_credits": "50.0",
    "ongoing_usage_credits": "0.0",
    "net_balance_credits": "150.0",
    "created_at": "2025-07-30T20:13:18Z",
    "expiration_at": "2026-10-08T00:00:00Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION",
        "CHARGE",
        "COMMITMENT"
      ]
    },
    "recurring_transaction_rules": [
      {
        "trigger": "INTERVAL",
        "method": "TARGET",
        "interval": "WEEKLY",
        "started_at": "2025-07-01T17:30:15Z",
        "expiration_at": "2026-10-08T00:00:00Z",
        "target_ongoing_balance": "200.0"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with the wallet details.

### Update wallet

You can change wallet expiration dates, modify which charges can use credits, or update automatic top-up rules.

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 PUT call to the `/v1/commerce/billing/wallets/{wallet_id}` endpoint with the modified parameters.

**Path parameter**: `wallet_id` is the `id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/offer-billing-credits#2-create-wallet-and-add-credits" target="_blank" rel="noopener noreferrer">created a wallet</a>.

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

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X PUT 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets/635b39e4-5db1-45dd-b774-acdc0b0e78ba' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
    "name": "Updated Prepaid Wallet",
    "expiration_at": "2026-12-31T00:00:00Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION",
        "CHARGE",
        "COMMITMENT"
      ]
    },
    "recurring_transaction_rules": [
      {
        "trigger": "THRESHOLD",
        "threshold_credits": "50.0",
        "paid_credits": "100.0"
      }
    ]
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "id": "635b39e4-5db1-45dd-b774-acdc0b0e78ba",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
    "status": "ACTIVE",
    "available_balance": {
      "value": 150.00,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 150.00,
      "currency_code": "USD"
    },
    "name": "Updated Prepaid Wallet",
    "rate_amount": "1.0",
    "expiration_at": "2026-12-31T00:00:00Z",
    "available_credits": "150.0",
    "consumed_credits": "50.0",
    "ongoing_usage_credits": "0.0",
    "net_balance_credits": "150.0",
    "created_at": "2025-07-30T20:13:18Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION",
        "CHARGE",
        "COMMITMENT"
      ]
    },
    "recurring_transaction_rules": [
      {
        "trigger": "THRESHOLD",
        "threshold_credits": "50.0",
        "paid_credits": "100.0"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with the updated wallet information.

### Terminate wallet

You can close a wallet to stop unauthorized credit use. You can also turn off wallets that still have credits. You cannot reactivate a terminated wallet.

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 DELETE call to the `/v1/commerce/billing/wallets/{wallet_id}` endpoint.

**Path parameter**: `wallet_id` is the `id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/offer-billing-credits#2-create-wallet-and-add-credits" target="_blank" rel="noopener noreferrer">created a wallet</a>.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X DELETE 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets/635b39e4-5db1-45dd-b774-acdc0b0e78ba' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "id": "635b39e4-5db1-45dd-b774-acdc0b0e78ba",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
    "status": "TERMINATED",
    "available_balance": {
      "value": 150.00,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 150.00,
      "currency_code": "USD"
    },
    "name": "Updated Prepaid Wallet",
    "rate_amount": "1.0",
    "available_credits": "150.0",
    "consumed_credits": "50.0",
    "ongoing_usage_credits": "0.0",
    "net_balance_credits": "150.0",
    "created_at": "2025-07-30T20:13:18Z",
    "terminated_at": "2025-07-30T20:25:30Z",
    "applies_to": {
      "fee_types": [
        "SUBSCRIPTION",
        "CHARGE",
        "COMMITMENT"
      ]
    }
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with the terminated wallet details.