Skip to main content
Limited Release
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. Include the following parameters: Path parameter: wallet_id is the id returned when you created a wallet.
ParameterAction
type
Required, string		Set to TOPUP to add credits.
paid_credits
string		Set the number of paid credits to add. Must be a positive value.
granted_credits
string		Set the number of granted (promotional) credits to add. Must be a positive value.
metadata
array		Provide optional metadata for tracking purposes. Each object contains key and value pairs.
For information on all parameters, see API reference. 
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"
    }
  ]
}'
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 valid access token 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 created a wallet.
ParameterAction
type
Required, string		Set to VOID to remove credits.
credits_to_void
Required, string		Set the number of credits to remove. Must be a positive value.
metadata
array		Provide optional metadata for tracking purposes. Each object contains key and value pairs.
For information on all parameters, see API reference. 
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"
    }
  ]
}'
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 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. For information on all parameters, see API reference. 
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>'
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 valid access token and make a GET call to the /v1/commerce/billing/wallets endpoint. For information on all parameters, see API reference. 
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>'
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 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>'
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 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. For information on all parameters, see API reference. 
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"
    }
  ]
}'
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 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>'
A successful call returns a 200 OK response with the terminated wallet details.