Skip to main content
GET
/
wallets
/
{wallet_id}
Retrieve a wallet by ID
curl --request GET \
  --url https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets/{wallet_id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "943254a2-0240-4414-bede-c0d211340c53",
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
  "status": "ACTIVE",
  "available_balance": {
    "value": 3,
    "currency_code": "USD"
  },
  "ongoing_usage": {
    "value": 0,
    "currency_code": "USD"
  },
  "net_balance": {
    "value": 3,
    "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-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"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

Path Parameters

​
wallet_id
string
required

Wallet ID

Response

Wallet retrieved successfully

​
external_customer_id
string
required

External system reference to the customer

Example:

"client-12345"

​
status
enum<string>
required

Current status of the wallet

Available options:
ACTIVE,
TERMINATED,
PENDING
Example:

"ACTIVE"

​
rate_amount
string
required

Price charged per credit unit

Example:

"1.5"

​
available_balance
object
​
ongoing_usage
object

The ongoing usage of the wallet, and it reflects all current usage and draft invoices including taxes.

Example:
{ "value": 100, "currency_code": "USD" }
​
net_balance
object

This represents the real-time balance after accounting for current usage,.

Example:
{ "value": 50, "currency_code": "USD" }
​
name
string

Human-readable wallet name

Example:

"Prepaid Wallet"

​
available_credits
string

Current credit balance available

Example:

"28.0"

​
ongoing_usage_credits
string

This reflects all current usage and draft invoices.

Example:

"10.0"

​
net_balance_credits
string

This represents the real time balance after accounting for current usage.

Example:

"18.0"

​
consumed_credits
string

Total credits consumed so far

Example:

"2.0"

​
created_at
string<date-time>

Date and time when the wallet was created, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).

Example:

"2025-01-01T00:00:00Z"

​
expiration_at
string<date-time>

Date and time when the wallet is set to expire, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).

Example:

"2025-01-01T00:00:00Z"

​
terminated_at
string<date-time>

Date and time when the wallet was terminated, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).

Example:

"2025-01-01T00:00:00Z"

​
applies_to
object

Indicates whether the prepaid credit applies to the entire invoice or only to specific line items.

​
recurring_transaction_rules
object[]

List of recurring transaction rules for automatic top-ups

​
id
string

Unique identifier for the wallet

Example:

"sub_01H3YT8P7Q5R3S1T2U0V4W9X8"