Skip to main content
POST
/
wallets
Create a new wallet
curl --request POST \
  --url https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "external_customer_id": "client-xyz456",
  "currency": "USD",
  "rate_amount": "1.5",
  "name": "Prepaid Wallet",
  "paid_credits": "10.0",
  "granted_credits": "5.0",
  "expiration_at": "2025-01-01T00:00:00Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION"
    ]
  },
  "recurring_transaction_rules": [
    {
      "trigger": "THRESHOLD",
      "method": "FIXED",
      "paid_credits": "20.0",
      "granted_credits": "10.0",
      "interval": "MONTHLY",
      "started_at": "2025-01-01T00:00:00Z",
      "expiration_at": "2025-01-01T00:00:00Z",
      "threshold_credits": "5.0",
      "target_ongoing_balance": "200.0"
    }
  ]
}
'
{
  "id": "13fddcdc-725b-4ca7-a522-a162ff038567",
  "external_customer_id": "ext_cus_1234567890abcdef",
  "status": "ACTIVE",
  "available_balance": {
    "value": 110,
    "currency_code": "USD"
  },
  "ongoing_usage": {
    "value": 0,
    "currency_code": "USD"
  },
  "net_balance": {
    "value": 110,
    "currency_code": "USD"
  },
  "name": "Prepaid Wallet",
  "rate_amount": "1.0",
  "available_credits": "110.0",
  "consumed_credits": "0.0",
  "ongoing_usage_credits": "0.0",
  "net_balance_credits": "110.0",
  "created_at": "2025-09-17T00:00:00Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION"
    ]
  },
  "expiration_at": "2026-08-12T12:43:31Z"
}

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.

Body

application/json
​
external_customer_id
string
required

External reference to the customer

Example:

"client-xyz456"

​
currency
string
required

Currency in which the wallet operates

Required string length: 3
Example:

"USD"

​
rate_amount
string
required

Cost rate per credit unit, must be non zero positive value

Example:

"1.5"

​
name
string

Name of the wallet

Example:

"Prepaid Wallet"

​
paid_credits
string

Number of paid credits to initialize, must be positive value

Example:

"10.0"

​
granted_credits
string

Number of granted credits to initialize, must be positive value

Example:

"5.0"

​
expiration_at
string<date-time>

Cancelled date of the subscription

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

Response

Wallet created 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"