Skip to main content
Limited Release
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

You can create a basic wallet, or include automatic top-up rules to automatically replenish credits. Use a valid access token and make a POST call to the /v1/commerce/billing/wallets endpoint. Include the following parameters:
ParameterAction
external_customer_id
Required, string		Set to the external_id returned when you registered the customer.
name
string		Provide a human-readable name to identify the wallet.
rate_amount
Required, string		Set the cost per credit unit (for example, "1.0" means each credit costs $1.00).
paid_credits
string		Set the initial paid credits to add when creating the wallet.
granted_credits
string		Set the initial promotional or free credits to add when creating the wallet.
currency
Required, string		Set the three-letter ISO 4217 currency code (for example, USD). See supported currencies.
expiration_at
string		Set when the wallet and its credits expire in ISO 8601 format with timezone.
applies_to.fee_types[]
array		Specify which fee types credits can pay for.

Possible values: SUBSCRIPTION, COMMITMENT, CHARGE
recurring_transaction_rules[]
array		Add automatic top-up rule configurations. See Automatic top-up configuration.
recurring_transaction_rules[].method
Required when recurring_transaction_rules[] is included, string		Set to FIXED to add a specific amount of credits or TARGET to add credits to reach a target balance. See Automatic top-up configuration.
recurring_transaction_rules[].trigger
Required when recurring_transaction_rules[] is included, string		Set to INTERVAL for scheduled intervals or THRESHOLD to trigger when credits drop below a specific amount. See Automatic top-up configuration.
For information on all parameters, see API reference.

​
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"
    }
  ]
}'
A successful call returns a 201 Created response. The response includes the following parameter:
ParameterDescriptionFurther action
id
string		Unique identifier for the wallet.Use this id when managing the wallet.
For information on all parameters, see API reference.

​
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.