> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get all invoices ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json get /invoices openapi: 3.0.1 info: title: Usage Based Billing API version: 1.0.0 description: An Orchestrator for Usage Based Billing and Payments servers: - url: https://api-m.sandbox.paypal.com/v1/commerce/billing security: - BearerAuth: - read - write tags: - name: Alerts description: API endpoints for managing subscription alerts - name: Events description: API endpoints for managing events - name: Metrics description: API endpoints for metrics and usage data - name: Merchant Activation description: API endpoint for merchant activation - name: Credit Notes description: API endpoints for credit notes management - name: Customers description: API endpoints for customer management - name: Invoices description: API endpoints for invoice management - name: Plans description: API endpoints for subscription plans - name: Subscriptions description: API endpoints for subscriptions - name: Wallets description: API endpoints for wallet management - name: Taxes description: API endpoints for tax management - name: Billing Entities description: API endpoints for billing entities - name: Features description: API endpoints for managing features and privileges - name: Entitlements description: API endpoints for managing plan and subscription entitlements paths: /invoices: get: tags: - Invoices summary: Get all invoices operationId: GetInvoices parameters: - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' - name: status in: query description: Filter invoices by status required: false schema: $ref: '#/components/schemas/InvoiceStatus' - name: payment_status in: query description: Filter invoices by payment status (e.g., pending, failed, succeeded) required: false schema: type: string enum: - PENDING - FAILED - SUCCEEDED default: PENDING x-enum-varnames: - PENDING - FAILED - SUCCEEDED x-enum-descriptions: - The invoice is awaiting payment. - The payment for the invoice has failed. - The payment for the invoice was successful. - name: external_customer_id in: query description: Filter invoices by external customer ID required: false schema: type: string - name: issuing_date_from in: query description: Filter invoices issued on or after this date (ISO 8601 format) required: true schema: $ref: '#/components/schemas/Date' - name: issuing_date_to in: query description: Filter invoices issued on or before this date (ISO 8601 format) required: true schema: $ref: '#/components/schemas/Date' responses: '200': description: A list of invoices. content: application/json: schema: type: object properties: invoices: type: array items: $ref: '#/components/schemas/InvoiceWithId' metadata: $ref: '#/components/schemas/PaginationMetadata' example: 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' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: per_page: name: per_page in: query description: Number of records per page schema: type: integer page: name: page in: query description: Page number schema: type: integer schemas: InvoiceStatus: type: string nullable: true enum: - DRAFT - FINALIZED x-enum-varnames: - DRAFT - FINALIZED x-enum-descriptions: - The invoice is in draft state and can be modified - The invoice has been finalized and cannot be modified description: Status of the invoice example: FINALIZED Date: type: string format: date description: Date in ISO 8601 format (YYYY-MM-DD). example: '2023-10-01' pattern: >- ^(?:[1-9]\d{3}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|02-(?:0[1-9]|1\d|2[0-8]))|(?:(?:\d{2}(?:0[48]|[2468][048]|[13579][26]))|(?:[02468][048]00|[13579][26]00))-02-29)$ InvoiceWithId: allOf: - $ref: '#/components/schemas/Invoice' - type: object properties: id: type: string created_at: description: Timestamp when the invoice was created allOf: - $ref: '#/components/schemas/DateTimeWithZone' example: '2023-01-01T00:00:00Z' updated_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' description: Timestamp when the invoice was last updated example: '2023-01-01T00:00:00Z' PaginationMetadata: type: object properties: total_count: type: integer total_pages: type: integer current_page: type: integer Invoice: type: object properties: id: type: string description: The unique identifier of the invoice example: 1a901a90-1a90-1a90-1a90-1a901a901a90 billing_entity_code: $ref: '#/components/schemas/BillingEntityCode' sequential_id: type: integer description: Sequential ID of the invoice, unique within the billing entity. example: 3 status: $ref: '#/components/schemas/InvoiceStatus' payment_status: $ref: '#/components/schemas/PaymentStatus' amount: allOf: - $ref: '#/components/schemas/AmountWithBreakdown' description: >- Total amount due for the invoice, including breakdown of fees, taxes, and discounts. example: total_amount: value: 19.99 currency_code: USD breakdown: fees: value: 1 currency_code: USD credit_notes: value: 0 currency_code: USD sub_total_excluding_taxes: value: 20 currency_code: USD taxes: value: 0.99 currency_code: USD sub_total_including_taxes: value: 19.99 currency_code: USD fees: type: array items: $ref: '#/components/schemas/FeeObject' due_date: allOf: - $ref: '#/components/schemas/Date' description: Due date for the invoice payment example: '2023-01-15' issued_date: allOf: - $ref: '#/components/schemas/Date' description: Date when the invoice was issued example: '2023-01-01' invoice_number: type: string description: Invoice number, unique within the billing entity. example: INV-2023-001 version_number: type: string format: number description: >- Version number of the invoice, indicating the revision of the invoice. example: INV-2023-001 payment_overdue: type: boolean description: Indicates whether the invoice payment is overdue. example: false invoice_type: $ref: '#/components/schemas/InvoiceType' customer: $ref: '#/components/schemas/CustomerWithId' billing_period: type: array items: type: object properties: subscription_id: type: string description: Unique identifier for the subscription example: sub_01H3YT8P7Q5R3S1T2U0V4W9X8 external_subscription_id: type: string description: >- The subscription external unique identifier supplied by client. example: ext_id_23fw3 plan_id: description: Unique identifier for the plan type: string example: plan_01H3YT8P7Q5R3S1T2U0V4W9X8 payment_method_token: allOf: - $ref: '#/components/schemas/PaymentMethodToken' description: Token representing the customer's payment method example: pm_visa_4242 payment_method_type: allOf: - $ref: '#/components/schemas/PaymentMethodType' subscription_from_datetime: allOf: - $ref: '#/components/schemas/DateTimeWithZone' subscription_to_datetime: allOf: - $ref: '#/components/schemas/DateTimeWithZone' charges_from_datetime: allOf: - $ref: '#/components/schemas/DateTimeWithZone' charges_to_datetime: allOf: - $ref: '#/components/schemas/DateTimeWithZone' invoicing_reason: type: string description: >- Reason for invoicing, e.g., 'subscription', 'usage', 'one-time charge' example: subscription created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' updated_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' applied_taxes: type: array items: allOf: - $ref: '#/components/schemas/BaseAppliedTax' - type: object properties: fees_amount: $ref: '#/components/schemas/AmountNoCurrency' description: The total fees amount to which the tax is applied. example: value: 10.05 DateTimeWithZone: type: string format: date-time description: Date and time in ISO 8601 format. example: '2023-10-01T12:00:00Z' Error: type: object properties: name: type: string debug_id: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' BillingEntityCode: type: string description: >- Unique code used to identify the billing entity. Must contain only alphanumeric characters, underscores, and hyphens. pattern: ^[a-zA-Z0-9_-]*$ example: acme_inc PaymentStatus: type: string description: Status of invoice payment enum: - PENDING - FAILED - SUCCEEDED x-enum-varnames: - PENDING - FAILED - SUCCEEDED x-enum-descriptions: - The invoice is awaiting payment - The payment for the invoice has failed - The payment for the invoice was successful example: PENDING AmountWithBreakdown: type: object properties: total_amount: allOf: - $ref: '#/components/schemas/Amount' breakdown: allOf: - $ref: '#/components/schemas/AmountBreakdown' FeeObject: type: object properties: id: type: string nullable: true format: uuid description: >- Unique identifier assigned to the fee. This ID is exclusively and serves as a unique identifier for the fee's record. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 total_amount: $ref: '#/components/schemas/Amount' description: The cost of this specific fee, including any applicable taxes. example: value: 1.2 currency_code: USD name: type: string nullable: true description: >- The the name of the fee associated to any one of the charge, the credit, the subscription or the commitment example: Basic Plan InvoiceType: type: string nullable: true enum: - SUBSCRIPTION - ONE_OFF - CREDIT x-enum-varnames: - SUBSCRIPTION - ONE_OFF - CREDIT x-enum-descriptions: - Invoice generated for subscription recurring charges - Invoice generated for one-time charges - Credit note invoice for refunds or adjustments description: Type of invoice example: SUBSCRIPTION CustomerWithId: allOf: - $ref: '#/components/schemas/Customer' - type: object properties: id: type: string PaymentMethodToken: type: string minLength: 1 maxLength: 36 description: Token representing the customer's saved payment method in PayPal Vault. example: pm_visa_4242 PaymentMethodType: type: string description: Type of payment method used (e.g., CARD, ACH_DEBIT) enum: - CARD - PAYPAL - ACH_DEBIT - APPLE_PAY x-enum-varnames: - CARD - PAYPAL - ACH_DEBIT - APPLE_PAY x-enum-description: - Payment made using a Credit or Debit card. - Payment made using PayPal. - Payment made using Automated Clearing House (ACH) transfer. - Payment made using Apple Pay. example: CARD BaseAppliedTax: type: object properties: id: type: string format: uuid description: Unique identifier of the applied tax. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 tax_id: type: string format: uuid description: Unique identifier of the tax. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 tax_name: type: string description: Name of the tax. example: TVA tax_code: type: string description: >- Unique code used to identify the tax associated with the API request. example: french_standard_vat tax_rate: type: number description: The percentage rate of the tax example: 20 tax_description: type: string description: Internal description of the taxes example: French standard VAT amount: $ref: '#/components/schemas/Amount' description: Amount of the tax example: value: 20 currency_code: USD created_at: $ref: '#/components/schemas/DateTimeWithZone' description: >- The date and time when the applied tax was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the applied tax was initially created. example: '2022-09-14T16:35:31Z' AmountNoCurrency: type: object required: - value properties: value: type: number format: decimal description: >- The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY). example: 120.35 minimum: 0 nullable: false default: 0 ErrorDetail: type: object properties: field: type: string value: type: string location: type: string issue: type: string description: type: string Amount: allOf: - $ref: '#/components/schemas/AmountNoCurrency' - type: object required: - currency_code properties: currency_code: $ref: '#/components/schemas/Currency' AmountBreakdown: type: object properties: fees: description: The total amount of fees applied to the invoice. allOf: - $ref: '#/components/schemas/Amount' credit_notes: description: The total amount of credit notes applied to the invoice. allOf: - $ref: '#/components/schemas/Amount' sub_total_excluding_taxes: description: The subtotal amount of the invoice excluding taxes. allOf: - $ref: '#/components/schemas/Amount' taxes: description: The total amount of taxes applied to the invoice. allOf: - $ref: '#/components/schemas/Amount' sub_total_including_taxes: description: The subtotal amount of the invoice including taxes. allOf: - $ref: '#/components/schemas/Amount' prepaid_credit: description: The total amount of prepaid credits applied to the invoice. allOf: - $ref: '#/components/schemas/Amount' progressive_billing_credit: description: >- The total amount of progressive billing credits applied to the invoice. allOf: - $ref: '#/components/schemas/Amount' Customer: title: Customer description: >- A customer represents an individual or organization that can be billed for services. It includes personal information, contact details, and metadata. type: object required: - name - email - external_id properties: name: type: string nullable: false minLength: 1 maxLength: 512 description: Full name of the customer example: John Doe external_id: type: string minLength: 1 maxLength: 64 description: >- External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens. pattern: ^[a-zA-Z0-9_-]*$ example: ext_cust_12345 email: $ref: '#/components/schemas/EmailAddress' billing_entity_code: $ref: '#/components/schemas/BillingEntityCode' address: $ref: '#/components/schemas/Address' phone: type: string format: phone description: >- Primary phone number of the customer, including country code if available. example: +1-234-567-8900 payment_method_token: allOf: - $ref: '#/components/schemas/PaymentMethodToken' description: >- Token representing the customer's saved payment method in PayPal Vault. example: 03t59758xv4247939 payment_method_type: $ref: '#/components/schemas/PaymentMethodType' taxes: type: array description: List of tax entities configured for the customer. items: $ref: '#/components/schemas/TaxResponse' metadata: type: array items: $ref: '#/components/schemas/CustomerMetadata' Currency: type: string description: Currency code in ISO 4217 format. example: USD minLength: 3 maxLength: 3 pattern: ^[A-Z]{3}$ EmailAddress: type: string description: The internationalized email address. minLength: 3 maxLength: 254 pattern: ^.+@[^"\-].+$ example: abc@test.com Address: description: Address of the customer or party. type: object properties: line1: type: string nullable: false minLength: 1 maxLength: 254 description: First line of the address. example: 123 Main St line2: type: string minLength: 1 maxLength: 512 description: >- Second line of the address (optional). This can include apartment, suite, or unit numbers. example: Apt 4B city: type: string nullable: false minLength: 1 maxLength: 512 description: City of the customer or party. example: New York state: type: string nullable: false minLength: 1 maxLength: 512 description: State or region of the customer or party. example: NY postal_code: type: string nullable: false minLength: 1 maxLength: 512 description: >- Postal or ZIP code of the customer or party. Typically required for countries with a postal code or an equivalent. example: '10001' country: type: string nullable: false pattern: ^[A-Z]{2}$ minLength: 2 maxLength: 2 description: >- Country of the customer or party. Use ISO 3166-1 alpha-2 country codes. example: US TaxResponse: description: >- Represents a customizable tax rate that can be applied to invoices and fees type: object allOf: - $ref: '#/components/schemas/TaxBase' - type: object properties: code: $ref: '#/components/schemas/TaxCode' id: type: string format: uuid description: Unique identifier of the tax example: 1a901a90-1a90-1a90-1a90-1a901a901a90 created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' - description: >- The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format example: '2025-06-01T00:00:00Z' CustomerMetadata: type: object description: >- Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format required: - key - value - display_in_invoice properties: key: type: string example: Purchase Order description: The metadata object key maxLength: 20 value: type: string example: '123456789' description: The metadata object value maxLength: 100 display_in_invoice: type: boolean example: true description: >- Determines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice. TaxBase: description: Base schema for tax request/response objects type: object required: - name properties: name: type: string description: Name of the tax example: TVA rate: type: string pattern: >- ^(?!0+(?:\.0+)?$)(?:0?\.\d{1,2}|[1-9]\d?(?:\.\d{1,2})?|100(?:\.0{1,2})?)$ description: >- The percentage rate of the tax applied to transactions. A decimal amount from 0.01 to 100.00 inclusive, always with exactly two decimal places, no leading zeros except 0.xx. example: '20.00' description: type: string description: Detailed description of the tax for internal reference example: French standard VAT TaxCode: type: string description: >- Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens. pattern: ^[a-zA-Z0-9_-]*$ example: standard_vat responses: Forbidden: description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: '#/components/schemas/Error' example: name: NOT_AUTHORIZED message: Authorization failed due to insufficient permissions. debug_id: 565f78f101498 details: - issue: PERMISSION_DENIED description: >- You do not have permission to access or perform operations on this resource. InternalServerError: description: Internal Server Error - An unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/Error' example: name: INTERNAL_SERVER_ERROR message: An internal server error has occurred. debug_id: 90957fca61718 securitySchemes: BearerAuth: type: oauth2 description: >- Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header. flows: clientCredentials: tokenUrl: https://api-m.sandbox.paypal.com/v1/oauth2/token scopes: read: Read access write: Write access ````