Generate invoices - Paypal Docs

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:

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

{
  "invoices": [
    {
      "id": "27986ceb-bb27-461d-82b1-f044646e192d",
      "sequential_id": 5,
      "status": "FINALIZED",
      "payment_status": "PENDING",
      "amount": {
        "total_amount": {
          "value": 220.2,
          "currency_code": "USD"
        }
      },
      "due_date": "2025-07-28",
      "issued_date": "2025-07-28",
      "invoice_number": "PPC-9E32-202507-012",
      "version_number": "4",
      "payment_overdue": true,
      "invoice_type": "SUBSCRIPTION",
      "customer": {
        "name": "Test Plan Override Customer",
        "external_id": "5eb02857-a71e-4ea2-bcf9-1752555395",
        "email": "finance@techstart.io",
        "address": {
          "line1": "123 Innovation Way",
          "line2": "Suite 400",
          "city": "San Francisco",
          "state": "CA",
          "country": "US"
        },
        "phone": "+1 (555) 789-1234",
        "id": "5a31b634-3213-42f5-a184-c68f93e47dc1"
      },
      "created_at": "2025-07-28T00:10:01Z",
      "updated_at": "2025-07-29T00:25:00Z"
    },
    {
      "id": "9cf09b3f-9e52-434c-b3f4-3675739795fa",
      "sequential_id": 3,
      "status": "FINALIZED",
      "payment_status": "PENDING",
      "amount": {
        "total_amount": {
          "value": 500.11,
          "currency_code": "USD"
        }
      },
      "due_date": "2025-07-28",
      "issued_date": "2025-07-28",
      "invoice_number": "PPC-9E32-202507-003",
      "version_number": "4",
      "payment_overdue": true,
      "invoice_type": "SUBSCRIPTION",
      "customer": {
        "name": "CUST_NLT_1752783445",
        "external_id": "5eb02857-a71e-4ea2-bcf9-1752783445",
        "email": "sakdjas@comp.net",
        "id": "6610c88a-bde2-4f62-bce5-02a29384cfc3"
      },
      "created_at": "2025-07-28T00:10:01Z",
      "updated_at": "2025-07-29T00:25:02Z"
    }
  ]
}

A successful call returns a 200 OK response. The response includes the following parameter:

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

{
      "id": "9cf09b3f-9e52-434c-b3f4-3675739795fa",
      "sequential_id": 3,
      "status": "FINALIZED",
      "payment_status": "PENDING",
      "payment_overdue": true,
      "invoice_type": "SUBSCRIPTION",
      "invoice_number": "PPC-9E32-202507-003",
      "version_number": 4,
      "billing_entity_code": "US_ENTITY",
      "amount": {
        "total_amount": {
          "value": 500.11,
          "currency_code": "USD"
        }
      },
      "fees": [
        {
          "id": "f3c91be7-85ba-4f41-857b-f844749e4f1b",
          "total_amount": {
            "value": 500.00,
            "currency_code": "USD"
          }
        },
        {
          "id": "e58684ef-8e26-4339-a2ba-b243beffc3f1",
          "total_amount": {
            "value": 0.11,
            "currency_code": "USD"
          }
        }
      ],
      "applied_taxes": [
        {
          "tax_name": "State Tax",
          "tax_amount": {
            "value": 45.46,
            "currency_code": "USD"
          },
          "tax_rate": 10.0
        }
      ],
      "billing_period": [
        {
          "subscription_id": "sub_02H3YT8P7Q5R3S1T2U0V4W9X9",
          "external_subscription_id": "ext_sub_67890",
          "plan_id": "plan_02H3YT8P7Q5R3S1T2U0V4W9X9",
          "payment_method_token": "pm_visa_5555",
          "payment_method_type": "CARD",
          "subscription_from_datetime": "2025-07-01T00:00:00Z",
          "subscription_to_datetime": "2025-07-31T23:59:59Z",
          "charges_from_datetime": "2025-07-01T00:00:00Z",
          "charges_to_datetime": "2025-07-31T23:59:59Z",
          "invoicing_reason": "subscription"
        }
      ],
      "due_date": "2025-07-28",
      "issued_date": "2025-07-28",
      "customer": {
        "id": "6610c88a-bde2-4f62-bce5-02a29384cfc3",
        "external_id": "5eb02857-a71e-4ea2-bcf9-1752783445",
        "name": "Sarah Johnson",
        "email": "sarah.johnson@company.com",
        "phone": "+1 (555) 123-4567",
        "address": {
          "line1": "456 Business Ave",
          "line2": "Floor 2",
          "city": "Austin",
          "state": "TX",
          "country": "US"
        }
      },
      "created_at": "2025-07-28T00:10:01Z",
      "updated_at": "2025-07-29T00:25:02Z"
    }

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.

​List invoices

​Get invoice details

List invoices

Get invoice details