---
title: Usage Based Billing API v1
canonical: https://developer.paypal.com/api/usage-based-billing/v1
openapi_schema:
  json: https://developer.paypal.com/api/usage-based-billing/v1/schema.json
  yaml: https://developer.paypal.com/api/usage-based-billing/v1/schema.yaml
---

# Usage Based Billing API v1 (/api/usage-based-billing/v1)

> This is an API reference page. The information below is a summary — the [JSON](https://developer.paypal.com/api/usage-based-billing/v1/schema.json) and [YAML](https://developer.paypal.com/api/usage-based-billing/v1/schema.yaml) schema are the preferred, authoritative source for exact parameters, request/response shapes, and validation rules.

## Base URL(s)

- https://api-m.sandbox.paypal.com

## Authentication

- BearerAuth (OAuth 2.0, clientCredentials)

## Operations

### Billing Entities

- `GET` [List all billing entities](/api/usage-based-billing/v1/getbillingentities)
- `POST` [Create a billing entity](/api/usage-based-billing/v1/createbillingentity)
- `GET` [Get a billing entity by code](/api/usage-based-billing/v1/getbillingentitybycode)
- `PUT` [Update a billing entity by code](/api/usage-based-billing/v1/updatebillingentitybycode)

### Taxes

- `GET` [List all taxes](/api/usage-based-billing/v1/gettaxes): Retrieves a paginated list of all taxes
- `POST` [Create a tax](/api/usage-based-billing/v1/createtax): Creates a new tax that can be applied to invoices
- `GET` [Retrieve a Tax](/api/usage-based-billing/v1/gettaxbycode): Retrieves an existing tax by its unique code
- `DELETE` [Delete a tax](/api/usage-based-billing/v1/deletetax): Deletes an existing tax
- `PUT` [Update a tax](/api/usage-based-billing/v1/updatetax): Updates an existing tax

### Merchant Activation

- `POST` [Activate Usage Based Billing](/api/usage-based-billing/v1/activatemerchant)

### Invoices

- `GET` [Get all invoices](/api/usage-based-billing/v1/getinvoices)
- `GET` [Get a single invoice by ID](/api/usage-based-billing/v1/getinvoicebyid)
- `POST` [Retry payment for a specific invoice](/api/usage-based-billing/v1/retryinvoicepayment)

### Metrics

- `GET` [Get all metrics](/api/usage-based-billing/v1/getmetrics)
- `POST` [Create a new metric](/api/usage-based-billing/v1/createmetric)
- `GET` [Get a metric by code](/api/usage-based-billing/v1/getmetricbycode)
- `DELETE` [Delete a metric by Code](/api/usage-based-billing/v1/deletemetricbycode)
- `PUT` [Update a metric by Code](/api/usage-based-billing/v1/updatemetricbycode)

### Plans

- `GET` [Get all plans](/api/usage-based-billing/v1/getplans)
- `POST` [Create a new plan](/api/usage-based-billing/v1/createplan)
- `GET` [Get a plan by Code](/api/usage-based-billing/v1/getplanbycode)
- `DELETE` [Delete a plan by Code](/api/usage-based-billing/v1/deleteplanbycode): Delete a plan by providing the plan ID.
- `PUT` [Update a plan by Code](/api/usage-based-billing/v1/updateplanbycode)

### Customers

- `GET` [Get all customers](/api/usage-based-billing/v1/getcustomers)
- `POST` [Create a new customer](/api/usage-based-billing/v1/createcustomer)
- `GET` [Get a customer by ID](/api/usage-based-billing/v1/getcustomerbyid)
- `DELETE` [Delete a customer by ID](/api/usage-based-billing/v1/deletecustomerbyid)
- `PUT` [Update a customer by ID](/api/usage-based-billing/v1/updatecustomerbyid)
- `GET` [Retrieve customer analytics for overdue balance](/api/usage-based-billing/v1/getcustomeranalyticsoverduebalance)
- `GET` [Retrieve customer gross revenue analytics](/api/usage-based-billing/v1/getcustomeranalyticsgrossrevenue)
- `GET` [Get current usage for a customer](/api/usage-based-billing/v1/getcustomerscurrentusage): Retrieves the current billing period usage information for a specific customer
- `GET` [Get past usage for a customer](/api/usage-based-billing/v1/getcustomerpastusage): Retrieves historical usage information for a specific customer across previous billing periods
- `GET` [Get an embeddable URL to the customer portal](/api/usage-based-billing/v1/getembeddableportalurl)

### Subscriptions

- `GET` [Get all subscriptions](/api/usage-based-billing/v1/getsubscriptions)
- `POST` [Create a new subscription](/api/usage-based-billing/v1/createsubscription)
- `GET` [Get a subscription by ID](/api/usage-based-billing/v1/getsubscriptionbyid)
- `PUT` [Update a subscription](/api/usage-based-billing/v1/updatesubscriptionbyid): Updates an existing subscription's details such as name, or metadata.
- `GET` [Retrieve lifetime usage for a specific subscription](/api/usage-based-billing/v1/getlifetimeusagebysubscriptionid)
- `POST` [Cancel a subscription](/api/usage-based-billing/v1/cancelsubscription): This endpoint allows you to cancel an existing subscription.

### Events

- `GET` [Query usage events](/api/usage-based-billing/v1/getevents)
- `POST` [Create a new usage event](/api/usage-based-billing/v1/createevent)
- `POST` [Create multiple usage events in batch.](/api/usage-based-billing/v1/createeventsbatch)

### Wallets

- `GET` [Get all wallets](/api/usage-based-billing/v1/getwallets)
- `POST` [Create a new wallet](/api/usage-based-billing/v1/createwallet)
- `GET` [Retrieve a wallet by ID](/api/usage-based-billing/v1/getwalletbyid)
- `DELETE` [Terminate wallet](/api/usage-based-billing/v1/terminatewalletbyid)
- `PUT` [Update a wallet](/api/usage-based-billing/v1/updatewalletbyid)
- `GET` [Get wallet transactions](/api/usage-based-billing/v1/getwallettransactions)
- `POST` [Create Wallet transaction](/api/usage-based-billing/v1/createwallettransaction)
- `GET` [Get Wallet transaction by id](/api/usage-based-billing/v1/getwallettransactionbyid)

### Credit Notes

- `GET` [Get all credit notes](/api/usage-based-billing/v1/getcreditnotes)
- `POST` [Create a new credit note](/api/usage-based-billing/v1/createcreditnote)
- `GET` [Get a single credit note by ID](/api/usage-based-billing/v1/getcreditnotebyid)
- `POST` [Void a credit note](/api/usage-based-billing/v1/voidcreditnote): Voids a credit note, making it no longer available for use.

### Alerts

- `GET` [Retrieve subscription alerts](/api/usage-based-billing/v1/getalertsbyexternalid): Retrieves all usage-based alerts configured for a specific subscription.
- `POST` [Create subscription alert](/api/usage-based-billing/v1/createalert): Establishes a new usage-based alert for a subscription to notify merchants when consumption reaches specified thresholds.
- `GET` [Retrieve specific subscription alert](/api/usage-based-billing/v1/getalertbyexternalidandcode): Retrieves detailed information about a specific alert identified by its unique code within a subscription.
- `DELETE` [Remove subscription alert](/api/usage-based-billing/v1/deletealertbyexternalidandcode): Permanently deletes a subscription alert identified by its unique code.
- `PUT` [Modify subscription alert](/api/usage-based-billing/v1/updatealertbyexternalidandcode): Updates the configuration of an existing subscription alert.

### Features

- `GET` [List all features](/api/usage-based-billing/v1/getfeatures): Retrieves a comprehensive list of all features defined in your system.
- `POST` [Create a feature](/api/usage-based-billing/v1/createfeature): Creates a new feature that represents a capability or functionality that can be entitled to customers.
- `GET` [Retrieve a feature](/api/usage-based-billing/v1/getfeaturebycode): Retrieves complete details of a specific feature including all its privileges and configuration.
- `DELETE` [Delete a feature](/api/usage-based-billing/v1/deletefeature): Permanently deletes a feature from the system.
- `PUT` [Update a feature](/api/usage-based-billing/v1/updatefeature): Updates an existing feature's properties including name, description, and privileges.
- `DELETE` [Delete a feature privilege](/api/usage-based-billing/v1/deletefeatureprivilege): Removes a specific privilege from a feature definition.

### Entitlements

- `GET` [List all entitlements](/api/usage-based-billing/v1/getplanentitlements): Retrieve all entitlements assigned to a specific plan
- `POST` [Create an entitlement](/api/usage-based-billing/v1/createplanentitlement): Assign a feature to a plan with specific privilege values.
- `PATCH` [Partial update of entitlements](/api/usage-based-billing/v1/updateplanentitlements): Update privilege values for one or more plan entitlements.
- `GET` [Retrieve an entitlement](/api/usage-based-billing/v1/getplanentitlement): Get details of a specific entitlement for a plan
- `DELETE` [Delete an entitlement](/api/usage-based-billing/v1/deleteplanentitlement): Remove a feature entitlement from a plan
- `DELETE` [Remove a privilege from an entitlement](/api/usage-based-billing/v1/deleteplanentitlementprivilege): Remove a specific privilege from a plan entitlement
- `GET` [List all subscription entitlements](/api/usage-based-billing/v1/getsubscriptionentitlements): Retrieve effective entitlements for a subscription, including plan defaults and subscription-specific overrides
- `PATCH` [Update subscription entitlements](/api/usage-based-billing/v1/updatesubscriptionentitlements): This endpoint performs partial updates to subscription entitlements.
- `DELETE` [Remove an entitlement from a subscription](/api/usage-based-billing/v1/deletesubscriptionentitlementoverride): Remove a subscription-specific entitlement override, reverting to plan defaults
- `DELETE` [Remove a privilege from a subscription entitlement override](/api/usage-based-billing/v1/deletesubscriptionentitlementprivilegeoverride): Remove a specific privilege override from a subscription entitlement, reverting to plan default for that privilege

## Full schema

The list above is a summary. Full parameter, request, and response detail for every operation lives in the schema: [JSON](https://developer.paypal.com/api/usage-based-billing/v1/schema.json) · [YAML](https://developer.paypal.com/api/usage-based-billing/v1/schema.yaml)