Offer billing credits

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.

Method	Description	Required field
`fixed`	Add a specific amount of credits.	`paid_credits` or `granted_credits`.
`target`	Add credits to reach a target balance.	`target_ongoing_balance`.

Trigger	Description	Required field
`interval`	At scheduled intervals (weekly, monthly, quarterly, yearly).	`interval`.
`threshold`	When credits drop to less than a specific amount.	`threshold_credits`.

Additional configuration

Configuration	Description
Threshold credits	When 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 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	Required fields
Fixed amount + Schedule	Adds fixed credits at regular intervals.	`interval`, `paid_credits` OR `granted_credits`.
Fixed amount + Balance threshold	Adds fixed credits when balance is less than threshold.	`threshold_credits`, `paid_credits` OR `granted_credits`.
Target balance + Schedule	Tops up with variable credits to achieve target balance at scheduled times.	`interval`, `target_ongoing_balance`.
Target balance + Balance threshold	Tops 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:

Parameter	Action
`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"
}'

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

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

{
  "id": "943254a2-0240-4414-bede-c0d211340c53",
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
  "status": "ACTIVE",
  "available_balance": {
    "value": 3.00,
    "currency_code": "USD"
  },
  "ongoing_usage": {
    "value": 0.00,
    "currency_code": "USD"
  },
  "net_balance": {
    "value": 3.00,
    "currency_code": "USD"
  },
  "name": "Prepaid",
  "rate_amount": "1.0",
  "available_credits": "3.0",
  "consumed_credits": "0.0",
  "ongoing_usage_credits": "0.0",
  "net_balance_credits": "3.0",
  "created_at": "2025-07-24T17:57:36Z",
  "expiration_at": "2026-10-08T00:00:00Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION",
      "CHARGE",
      "COMMITMENT"
    ]
  },
  "recurring_transaction_rules": [
    {
      "trigger": "INTERVAL",
      "paid_credits": "5.5",
      "granted_credits": "1.0",
      "method": "FIXED",
      "interval": "WEEKLY",
      "started_at": "2025-07-24T17:30:15Z",
      "expiration_at": "2026-10-08T00:00:00Z",
      "threshold_credits": "0.0"
    }
  ]
}

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

{
  "id": "943254a2-0240-4414-bede-c0d211340c54",
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
  "status": "ACTIVE",
  "available_balance": {
    "value": 3.00,
    "currency_code": "USD"
  },
  "ongoing_usage": {
    "value": 0.00,
    "currency_code": "USD"
  },
  "net_balance": {
    "value": 3.00,
    "currency_code": "USD"
  },
  "name": "Prepaid",
  "rate_amount": "1.0",
  "available_credits": "3.0",
  "consumed_credits": "0.0",
  "ongoing_usage_credits": "0.0",
  "net_balance_credits": "3.0",
  "created_at": "2025-07-24T17:57:36Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION",
      "CHARGE",
      "COMMITMENT"
    ]
  },
  "recurring_transaction_rules": [
    {
      "trigger": "THRESHOLD",
      "paid_credits": "5.5",
      "granted_credits": "1.0",
      "method": "FIXED",
      "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"
    }
  ]
}'

{
  "id": "bb0f90f6-dd5f-4244-a6d8-ec42f0e171ce",
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
  "status": "ACTIVE",
  "available_balance": {
    "value": 3.00,
    "currency_code": "USD"
  },
  "ongoing_usage": {
    "value": 0.00,
    "currency_code": "USD"
  },
  "net_balance": {
    "value": 3.00,
    "currency_code": "USD"
  },
  "name": "Prepaid",
  "rate_amount": "1.0",
  "available_credits": "3.0",
  "consumed_credits": "0.0",
  "ongoing_usage_credits": "0.0",
  "net_balance_credits": "3.0",
  "created_at": "2025-07-15T14:53:33Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION"
    ]
  },
  "recurring_transaction_rules": [
    {
      "trigger": "INTERVAL",
      "paid_credits": "0.0",
      "granted_credits": "0.0",
      "method": "TARGET",
      "interval": "WEEKLY",
      "started_at": "2025-07-01T17:30:15Z",
      "expiration_at": "2026-10-08T00:00:00Z",
      "threshold_credits": "0.0",
      "target_ongoing_balance": "200.0"
    }
  ]
}

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

{
  "id": "bb0f90f6-dd5f-4244-a6d8-ec42f0e171ce",
  "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752591145",
  "status": "ACTIVE",
  "available_balance": {
    "value": 3.00,
    "currency_code": "USD"
  },
  "ongoing_usage": {
    "value": 0.00,
    "currency_code": "USD"
  },
  "net_balance": {
    "value": 3.00,
    "currency_code": "USD"
  },
  "name": "Prepaid",
  "rate_amount": "1.0",
  "available_credits": "3.0",
  "consumed_credits": "0.0",
  "ongoing_usage_credits": "0.0",
  "net_balance_credits": "3.0",
  "created_at": "2025-07-15T14:53:33Z",
  "applies_to": {
    "fee_types": [
      "SUBSCRIPTION"
    ]
  },
  "recurring_transaction_rules": [
    {
      "trigger": "THRESHOLD",
      "paid_credits": "0.0",
      "granted_credits": "0.0",
      "method": "TARGET",
      "started_at": "2025-07-29T17:30:15Z",
      "expiration_at": "2026-10-08T00:00:00Z",
      "threshold_credits": "10.0",
      "target_ongoing_balance": "200.0"
    }
  ]
}

A successful call returns a 201 Created response. The response includes the following parameter:

Parameter	Description	Further 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.

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.

​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

​3. Understand wallet lifecycle and manage wallets

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

3. Understand wallet lifecycle and manage wallets