Skip to main content
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

​
Add credits to wallet

You can add credits when a customer buys more credits or gets free promotional credits. Use a valid access token and send a POST request to /v1/commerce/billing/wallets/{wallet_id}/wallet-transactions with the required request parameters. Path parameter: wallet_id is the unique identifier returned as id when you create a wallet.

​
Request parameters

Parameter nameDescription
type
Required, string		Transaction type. Set to TOPUP to add credits.
paid_credits
string		Number of paid credits to add. Must be a positive value.
granted_credits
string		Number of granted (promotional) credits to add. Must be a positive value.
metadata
array		Optional metadata for tracking purposes. Each object contains key and value pairs.
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"
    }
  ]
}'
Note: For the exhaustive list of response parameters, see API reference.

​
Remove credits from wallet

You do this to give refunds, fix billing mistakes, or remove expired promotional credits. Use a valid access token and send a POST request to /v1/commerce/billing/wallets/{wallet_id}/wallet-transactions with type set to VOID. Path parameter: wallet_id is the unique identifier returned as id when you create a wallet.

​
Request parameters

Parameter nameDescription
type
Required, string		Transaction type. Set to VOID to remove credits.
credits_to_void
Required, string		Number of credits to remove. Must be a positive value.
metadata
array		Optional metadata for tracking purposes. Each object contains key and value pairs.
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"
    }
  ]
}'
Note: For the exhaustive list of response parameters, see API reference.

​
Get transaction history

You can get a wallet’s transaction history to audit credit movements and reconcile balances. Use a valid access token and send a GET request to /v1/commerce/billing/wallets/{wallet_id}/wallet-transactions. Path parameter: wallet_id is the unique identifier returned as id when you create a wallet. 
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>'
Note: For the exhaustive list of response parameters, see API reference.

​
Manage wallets

​
List wallets

You can view customer wallet collections, find wallets by specific criteria, or create reports across multiple wallets. Use a valid access token and send a GET request to /v1/commerce/billing/wallets with optional query parameters. 
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>'
Note: For the exhaustive list of query and response parameters, see API reference.

​
Get wallet details

You can check current balances, track how customers use credits, or verify wallet status and perform further wallet actions. Use a valid access token and send a GET request to /v1/commerce/billing/wallets/{id}. Path parameter: id is the unique identifier returned as id when you create a wallet. 
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>'
Note: For the exhaustive list of response parameters, see API reference.

​
Update wallet

You can change wallet expiration dates, modify which charges can use credits, or update automatic top-up rules. Use a valid access token and send a PUT request to /v1/commerce/billing/wallets/{id} with the modified parameters. Path parameter: id is the unique identifier returned as id when you create a wallet. 
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"
    }
  ]
}'
Note: For the exhaustive list of request and response parameters, see API reference.

​
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 valid access token and send a DELETE request to /v1/commerce/billing/wallets/{id}. Path parameter: id is the unique identifier returned as id when you create a wallet. 
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>'
Note: For the exhaustive list of response parameters, see API reference.
⌘I