Offer billing credits

Billing credits are non-monetary grants that customers purchase or receive upfront to pay for their usage-based subscriptions. These can be,

Prepaid credits that customers purchase with real money.
Granted credits that are free promotional credits you provide to customers.

Prepaid credits enable you to get paid in advance instead of waiting until the end of each billing period. To offer billing credits, you should set up a digital wallet for your customer. A digital wallet connects the following entities:

A customer.
The billing credits offered to the customer.

To offer billing credits to your customers:

Understand wallet configuration
Create wallets and add credits
Configure automatic top-up
Manage wallets

Important: 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

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. Note: If you do not specify this 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. Each rule combines a trigger condition with a top-up method to create flexible credit management strategies.

Top-up methods: Choose between FIXED (adds a specific amount of credits each time) or TARGET (adds enough credits to reach a target balance).
Top-up triggers: Set conditions that activate the top-up rules. Use INTERVAL for time-based top-ups (weekly, monthly, quarterly, yearly) or THRESHOLD for balance-based top-ups when credits drop below a specific amount.
Threshold credits: When using THRESHOLD trigger, specify the credit balance that triggers automatic top-ups. The system adds credits when the wallet balance drops below this value.
Target ongoing balance: When 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 allocation: For each rule, specify whether to add paid credits, granted credits, or both when the automatic top-up triggers.

Method + Trigger	How the combination works
Fixed amount + Schedule	Adds fixed credits at regular intervals
Fixed amount + Balance threshold	Adds fixed credits when balance drops below threshold
Target balance + Schedule	Tops up with variable credits to achieve target balance at scheduled times
Target balance + Balance threshold	Tops up with variable credits to achieve target balance when threshold is breached

2. Create wallet and add credits

Use a valid access token and send a POST request to /v1/commerce/billing/wallets 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": "5eb02857-a71e-4ea2-bcf9-1752591145",
  "name": "Prepaid",
  "rate_amount": "1.0",
  "paid_credits": "2.0",
  "granted_credits": "1.0",
  "currency": "USD"
}'

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 drops below 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 drops below 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

Note: This section documents only a subset of relevant request parameters. For the exhaustive list of request parameters, see API reference.

Parameter name	Description
`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.

Response parameters

Note: This section documents only the response parameters relevant for the next step. For the exhaustive list of response fields, see API reference.

Parameter name	Description and further action
`id` string	Unique wallet identifier. Use this ID to reference the wallet in future operations, such as adding credits or updating top-up rules.

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, call the Get wallet details endpoint and review the status parameter. The wallet’s lifecycle state determines the management actions you can perform to ensure proper wallet handling.

State	Description	Credit availability	Possible management actions
ACTIVE	Wallet is operational and credits can be used	Credits are available for billing.	Add credits to increase wallet balance. Remove credits to decrease wallet balance. Update wallet configurations and settings. Terminate wallet.
PENDING	Wallet is created but not yet operational	Credits cannot be used for billing .	Update wallet.
TERMINATED	Wallet is permanently disabled	No credit usage occurs, remaining credits are forfeited.	Wallet cannot be modified.

Usage-based Billing

​Prerequisite

​1. Understand wallet configuration

​2. Create wallet and add credits

​Basic wallet example

​Automatic top-up variations

​Fixed amount with schedule trigger

​Fixed amount with threshold trigger

​Target balance with schedule trigger

​Target balance with threshold trigger

​Request body parameters

​Response parameters

​3. Understand wallet lifecycle and manage wallets