> ## 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 a single invoice by ID



## OpenAPI

````yaml /api-reference/ubb_openapi_inline.json get /invoices/{invoice_id}
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/{invoice_id}:
    get:
      tags:
        - Invoices
      summary: Get a single invoice by ID
      operationId: GetInvoiceById
      parameters:
        - $ref: '#/components/parameters/invoice_id'
      responses:
        '200':
          description: A single invoice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceWithId'
              example:
                id: 9cf09b3f-9e52-434c-b3f4-3675739795fa
                sequential_id: 3
                status: FINALIZED
                payment_status: PENDING
                amount:
                  total_amount:
                    value: 500.11
                    currency_code: USD
                fees:
                  - id: f3c91be7-85ba-4f41-857b-f844749e4f1b
                    total_amount:
                      value: 500
                      currency_code: USD
                  - id: e58684ef-8e26-4339-a2ba-b243beffc3f1
                    total_amount:
                      value: 0.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: Test Plan Override Customer
                  external_id: 5eb02857-a71e-4ea2-bcf9-1752783445
                  email: dsadiaj@bert.com
                  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'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    invoice_id:
      name: invoice_id
      in: path
      required: true
      description: The unique identifier of the invoice
      schema:
        type: string
      example: 27986ceb-bb27-461d-82b1-f044646e192d
  schemas:
    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'
    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
    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
    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
    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)$
    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.
    NotFound:
      description: Resource Not Found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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

````