Skip to main content
An invoice is a billing document that charges customers for their usage during a billing period. PayPal’s Usage-based Billing automatically creates these invoices when billing periods end or when subscriptions are cancelled. You can:
  • List invoices to manage your billing operations:
    • View all invoices with filters and create customer dashboards to track payment history.
    • Reconcile billing data with your internal systems for accurate record keeping.
  • Get the invoice details of a specific customer and display invoice information to the customer.

​
List invoices

Use a valid access token and make a GET call to the /v1/commerce/billing/invoices?issuing_date_from={date}&issuing_date_to={date} endpoint with required query parameters. On successful request processing, PayPal returns the list of filtered invoices. 
curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/invoices?page=1&per_page=20&issuing_date_from=2022-07-08&issuing_date_to=2025-07-29&status=FINALIZED&external_customer_id=5eb02857-a71e-4ea2-bcf9-1752555395' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'

​
Query parameters

Parameter nameDescription
page
string		Page number for retrieval.
per_page
string		Number of invoices per page.
issuing_date_from
Required, string		Filter invoices issued after this date (YYYY-MM-DD).
issuing_date_to
Required, string		Filter invoices issued before this date (YYYY-MM-DD).
status
string		Filter invoices by status.

Possible values:
DRAFT: The invoice is in draft state and can be modified
FINALIZED: The invoice has been finalized and cannot be modified
payment_status
string		Filter invoices by payment status.

Possible values:
PENDING: Invoices awaiting payment
FAILED: Invoices with a failed payment status
SUCCEEDED: Invoices with a successful payment status
external_customer_id
string		Filter invoices pertaining to a customer. Use the external_id you provided when you registered the customer.

​
Response parameter

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

​
Get invoice details

Use a valid access token and make a GET call to the /v1/commerce/billing/invoices/{invoice_id} endpoint. Path parameter: invoice_id is the id returned in the List invoices response. On successful request processing, PayPal returns detailed invoice information. You can send or show the invoice information in the appropriate format to your customer. 
curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/invoices/9cf09b3f-9e52-434c-b3f4-3675739795fa' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
For the exhaustive list of response parameters, see API reference.