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"
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "debug_id": "dc99e3955cdd8",
  "details": [
    {
      "field": "/email",
      "value": "abc",
      "location": "body",
      "issue": "INVALID_PARAMETER_VALUE",
      "description": "The value of a field does not conform to the expected format."
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "565f78f101498",
  "details": [
    {
      "issue": "PERMISSION_DENIED",
      "description": "You do not have permission to access or perform operations on this resource."
    }
  ]
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
  "debug_id": "90957fca61718",
  "details": [
    {
      "field": "/email",
      "value": "sdfwdj@sdfs.com",
      "location": "body",
      "issue": "UNSUPPORTED_EMAIL",
      "description": "The email provided is not supported."
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error has occurred.",
  "debug_id": "90957fca61718"
}

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"
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "debug_id": "dc99e3955cdd8",
  "details": [
    {
      "field": "/email",
      "value": "abc",
      "location": "body",
      "issue": "INVALID_PARAMETER_VALUE",
      "description": "The value of a field does not conform to the expected format."
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "565f78f101498",
  "details": [
    {
      "issue": "PERMISSION_DENIED",
      "description": "You do not have permission to access or perform operations on this resource."
    }
  ]
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
  "debug_id": "90957fca61718",
  "details": [
    {
      "field": "/email",
      "value": "sdfwdj@sdfs.com",
      "location": "body",
      "issue": "UNSUPPORTED_EMAIL",
      "description": "The email provided is not supported."
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error has occurred.",
  "debug_id": "90957fca61718"
}

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

Pattern: ^[A-Z]{3}$

Example:

"USD"

rate_amount

string

required

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

Pattern: ^(?!0+(?:\.0+)?$)\d+(\.\d+)?$

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

Pattern: ^(0|[1-9]\d*)(\.\d+)?$

Example:

"10.0"

granted_credits

string

Number of granted credits to initialize, must be positive value

Pattern: ^(0|[1-9]\d*)(\.\d+)?$

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.

Show child attributes

recurring_transaction_rules

object[]

List of recurring transaction rules for automatic top-ups

Show child attributes

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

Show child attributes

ongoing_usage

object

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

Show child attributes

Example:

{ "value": 100, "currency_code": "USD" }

net_balance

object

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

Show child attributes

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.

Show child attributes

recurring_transaction_rules

object[]

List of recurring transaction rules for automatic top-ups

Show child attributes

string

Unique identifier for the wallet

Example:

"sub_01H3YT8P7Q5R3S1T2U0V4W9X8"

⌘I