Skip to main content
Limited Release
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 endpoint. Include the following query parameters:
ParameterAction
page
string		Set the page number for paginated results.
per_page
string		Set the number of invoices to return per page.
issuing_date_from
Required, string		Set the start date to filter invoices issued on or after this date (YYYY-MM-DD).
issuing_date_to
Required, string		Set the end date to filter invoices issued on or before this date (YYYY-MM-DD).
status
string		Filter invoices by status.

Possible values: DRAFT, FINALIZED
payment_status
string		Filter invoices by payment status.

Possible values: PENDING, FAILED, SUCCEEDED
external_customer_id
string		Set to the external_id returned when you registered the customer to filter invoices for that customer.
For information on all parameters, see API reference. 
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>'
A successful call returns a 200 OK response. The response includes the following parameter:
ParameterDescriptionFurther action
id
string		Unique identifier for the invoice.Use this id when retrieving invoice details.
For information on all parameters, see API reference.

​
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. 
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>'
A successful call returns a 200 OK response with detailed invoice information. You can send or show the invoice information in the appropriate format to your customer.