Skip to main content
Billing credits are non-monetary grants that customers purchase or receive upfront to pay for their usage-based subscriptions. To offer billing credits, you create a digital wallet for each customer. Billing credits have two types:
  • Prepaid credits: Customers purchase with real money for advance payment.
  • Granted credits: Free promotional credits you provide to customers.
Billing credits connect the following:
  • Customers who purchase or receive credits to pay for usage-based charges.
  • Digital wallets that hold and manage credits for each customer.
When PayPal generates invoices, billing credits are consumed first before charging payment methods.

​
Prerequisite

Ensure you have registered customers with valid external_id values and payment methods.

​
1. Understand wallet configuration

Before creating a wallet, understand the available configuration options. Basic wallet configuration
  • Rate amount: Specify the cost per credit in real money (example: rate amount of $1.00 means 10 credits cost $10.00).
  • Paid credits: Specify the credits customers purchase with real money.
  • Granted credits: Specify the free promotional credits you provide to customers.
Applicability scope
  • Fee types: Determine which types of charges the credits can pay for. You can specify subscription fees, usage-based charges, minimum commitments, or any combination of these.
    If you do not specify the fee types scope, wallet credits apply to all three charge types by default.
  • Expiration date: Optionally set when the credits expire if you want to create time-limited promotional offers or enforce credit usage policies.
Automatic top-up configuration Recurring transaction rules: Set up automated rules that define when and how credits are added to the wallet. When you include the recurring_transaction_rules[] array in your wallet configuration, the method and trigger fields are mandatory for each rule.
MethodDescriptionRequired field
fixedAdd a specific amount of credits.paid_credits or granted_credits.
targetAdd credits to reach a target balance.target_ongoing_balance.
TriggerDescriptionRequired field
intervalAt scheduled intervals (weekly, monthly, quarterly, yearly).interval.
thresholdWhen credits drop to less than a specific amount.threshold_credits.
Additional configuration
ConfigurationDescription
Threshold creditsWhen using THRESHOLD trigger, specify the credit balance that triggers automatic top-ups. The system adds credits when the wallet balance is less than this value.
Target ongoing balanceWhen using TARGET method, set the desired credit balance the wallet should maintain. The system calculates and adds the exact amount needed to reach this target.
Credit allocationFor each rule, specify whether to add paid credits, granted credits, or both when the automatic top-up triggers.
Method + TriggerHow the combination worksRequired fields
Fixed amount + ScheduleAdds fixed credits at regular intervals.interval, paid_credits OR granted_credits.
Fixed amount + Balance thresholdAdds fixed credits when balance is less than threshold.threshold_credits, paid_credits OR granted_credits.
Target balance + ScheduleTops up with variable credits to achieve target balance at scheduled times.interval, target_ongoing_balance.
Target balance + Balance thresholdTops up with variable credits to achieve target balance when threshold is breached.threshold_credits, target_ongoing_balance.

​
2. Create wallet and add credits

Use a valid access token and make a POST call to the /v1/commerce/billing/wallets endpoint with all required request parameters for existing registered customers. On successful wallet creation, PayPal returns a wallet ID. The structure of your request depends on whether you want an automatic top-up configuration in addition to the basic configuration. The basic wallet structure remains the same, but the recurring_transaction_rules[] array varies based on your automatic top-up variations.

​
Basic wallet example

The following example shows the fundamental structure of a basic wallet creation request where you manually add credits when required. 
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "external_customer_id": "ext_cus_1234567890abcdef",
  "name": "Prepaid Wallet",
  "rate_amount": "1.0",
  "paid_credits": "110.0",
  "currency": "USD",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION"
    ]
  },
  "expiration_at": "2026-08-12T12:43:31Z"
}'

​
Automatic top-up variations

Each automatic top-up strategy requires different properties within the recurring_transaction_rules[] array. The following examples show how to configure the various strategies.

​
Fixed amount with schedule trigger

Use this strategy when you want to add predictable credit amounts at regular intervals. This approach adds the same number of credits weekly/monthly regardless of usage patterns, providing consistent credit additions for predictable billing scenarios. 
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
  "name": "Prepaid",
  "rate_amount": "1.0",
  "paid_credits": "2.0",
  "granted_credits": "1.0",
  "currency": "USD",
  "expiration_at": "2026-10-08T00:00:00Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION",
      "CHARGE",
      "COMMITMENT"
    ]
  },
  "recurring_transaction_rules": [
    {
      "method": "FIXED",
      "paid_credits": "5.5",
      "granted_credits": "1.0",
      "trigger": "INTERVAL",
      "interval": "WEEKLY",
      "started_at": "2025-07-24T17:30:15Z",
      "expiration_at": "2026-10-08T00:00:00Z"
    }
  ]
}'

​
Fixed amount with threshold trigger

Use this strategy to prevent service interruption by adding credits when your customer’s balance is less than a set amount. Threshold triggers watch actual usage patterns and adds credits only when required. 
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
  "name": "Prepaid",
  "rate_amount": "1.0",
  "paid_credits": "2.0",
  "granted_credits": "1.0",
  "currency": "USD",
  "expiration_at": "2026-10-08T00:00:00Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION",
      "CHARGE",
      "COMMITMENT"
    ]
  },
  "recurring_transaction_rules": [
    {
      "method": "FIXED",
      "paid_credits": "5.5",
      "granted_credits": "1.0",
      "trigger": "THRESHOLD",
      "threshold_credits": "10.0"
    }
  ]
}'

​
Target balance with schedule trigger

Use this strategy to maintain a minimum balance through regular checks. This approach dynamically calculates the required credits to reach your specified balance during each scheduled interval. 
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
  "name": "Prepaid",
  "rate_amount": "1.0",
  "paid_credits": "2.0",
  "granted_credits": "1.0",
  "currency": "USD",
  "expiration_at": "2026-10-08T00:00:00Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION"
    ]
  },
  "recurring_transaction_rules": [
    {
      "method": "TARGET",
      "target_ongoing_balance": "200.0",
      "trigger": "INTERVAL",
      "interval": "WEEKLY",
      "started_at": "2025-07-01T17:30:15Z",
      "expiration_at": "2026-10-08T00:00:00Z"
    }
  ]
}'

​
Target balance with threshold trigger

Use this strategy to ensure customers always have sufficient credits balance while minimizing unused credit accumulation. This approach combines the efficiency of threshold-based triggering with the precision of target balance calculations - adding credits only when the balance is less than the threshold and calculating the exact amount needed to reach your target balance. 
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/wallets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
  "name": "Prepaid",
  "rate_amount": "1.0",
  "paid_credits": "2.0",
  "granted_credits": "1.0",
  "currency": "USD",
  "expiration_at": "2026-10-08T00:00:00Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION"
    ]
  },
  "recurring_transaction_rules": [
    {
      "method": "TARGET",
      "target_ongoing_balance": "200.0",
      "trigger": "THRESHOLD",
      "threshold_credits": "10.00",
      "started_at": "2025-07-29T17:30:15Z",
      "expiration_at": "2026-10-08T00:00:00Z"
    }
  ]
}'

​
Request body parameters

This section documents only a subset of relevant request parameters. For the exhaustive list of request parameters, see API reference.
Parameter nameDescription
external_customer_id
Required, string		Your unique identifier for the customer who owns this wallet.
name
string		Human-readable name that helps you identify the wallet.
rate_amount
Required, string		Cost per credit unit in the specified currency. For example, “1.0” means each credit costs $1.00.
paid_credits
string		Initial paid credits that you add to the wallet when you create it.
granted_credits
string		Initial granted (promotional/free) credits that you add to the wallet when you create it.
currency
Required, string		Three-letter ISO 4217 currency code. Must be exactly 3 uppercase letters. See supported currencies.
expiration_at
string		Date and time when the wallet and its credits expire and become unusable. Must be in ISO 8601 format with timezone.
applies_to.fee_types[]
array		Fees that credits can pay for.

Possible values: SUBSCRIPTION, COMMITMENT, CHARGE
recurring_transaction_rules[]
array		Automatic top-up rule configurations. Each rule defines when and how the system adds credits automatically.
recurring_transaction_rules[].method
Required when recurring_transaction_rules[] is included, string		How to top up the wallet.

Possible values: FIXED, TARGET

See Automatic top-up configuration for validation requirements.
recurring_transaction_rules[].trigger
Required when recurring_transaction_rules[] is included, string		When to execute the top-up.

Possible values: INTERVAL, THRESHOLD

See Automatic top-up configuration for validation requirements.

​
Response parameters

This section documents only the response parameters relevant for the next step. For the exhaustive list of response fields, see API reference.
Parameter nameDescription and further action
id
string		Unique identifier for the wallet.
Use this id to reference the wallet in future operations, such as managing the wallet.

​
3. Understand wallet lifecycle and manage wallets

Wallets progress through distinct states throughout their lifecycle. These states determine credit availability and available management actions. To monitor a wallet’s current state, make a GET call to the /v1/commerce/billing/wallets/ endpoint and review the status parameter. The wallet’s lifecycle state determines the management actions you can perform to ensure proper wallet handling.
StateDescriptionCredit availabilityPossible management actions
ACTIVEWallet is operational and credits can be usedCredits are available for billing.Add credits to increase wallet balance.

Remove credits to decrease wallet balance.

Update wallet configurations and settings.

Terminate wallet.
PENDINGWallet is created but not yet operationalCredits cannot be used for billing .Update wallet.
TERMINATEDWallet is permanently disabledNo credit usage occurs, remaining credits are forfeited.Wallet cannot be modified.