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

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 valid access token and make a POST call to the /v1/commerce/billing/wallets/{wallet_id}/wallet-transactions endpoint with the required request parameters. Path parameter: wallet_id is the id returned when you created 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"
    }
  ]
}'
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 make a POST call to the /v1/commerce/billing/wallets/{wallet_id}/wallet-transactions endpoint with type set to VOID. Path parameter: wallet_id is the id returned when you created 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"
    }
  ]
}'
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 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 created 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>'
For the exhaustive list of response parameters, see API reference.

​
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 valid access token and make a GET call to the /v1/commerce/billing/wallets endpoint 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>'
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 make a GET call to the /v1/commerce/billing/wallets/{wallet_id} endpoint. Path parameter: wallet_id is the id returned when you created 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>'
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 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 created 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"
    }
  ]
}'
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 make a DELETE call to the /v1/commerce/billing/wallets/{wallet_id} endpoint. Path parameter: wallet_id is the id returned when you created 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>'
For the exhaustive list of response parameters, see API reference.