> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parceltracer.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List merchant invoices

> Retrieve a paginated list of the merchant's invoices, newest first, each with a financial summary (COD, delivery fee, net due to merchant), its status, and the number of orders on it. This returns invoice metadata only, for building a grouped overview; use the retrieve endpoint to get the orders on a specific invoice.

Use the `year` and `month` filters to fetch the invoices issued in a single period.



## OpenAPI

````yaml /api-reference/schema.yaml get /invoices/
openapi: 3.0.3
info:
  title: ''
  version: 0.0.0
servers:
  - url: https://api.parceltracer.com/v1/external/
    description: Parcel Tracer api endpoint
security: []
paths:
  /invoices/:
    get:
      tags:
        - Invoices
      summary: List merchant invoices
      description: >-
        Retrieve a paginated list of the merchant's invoices, newest first, each
        with a financial summary (COD, delivery fee, net due to merchant), its
        status, and the number of orders on it. This returns invoice metadata
        only, for building a grouped overview; use the retrieve endpoint to get
        the orders on a specific invoice.


        Use the `year` and `month` filters to fetch the invoices issued in a
        single period.
      operationId: list_invoices
      parameters:
        - in: query
          name: month
          schema:
            type: integer
          description: >-
            Return only invoices issued in this month (1-12). Combine with
            `year`.
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
        - in: query
          name: year
          schema:
            type: integer
          description: Return only invoices issued in this year, e.g. 2026.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedExternalInvoiceListItemList'
              examples:
                InvoiceListing:
                  value:
                    count: 123
                    next: http://api.example.org/accounts/?page=4
                    previous: http://api.example.org/accounts/?page=2
                    results:
                      - - number: 214
                          status: PAID
                          status_display: Paid
                          issued_at: '2026-07-03T09:15:00Z'
                          order_count: 12
                          cod:
                            - - USD
                              - '240.00'
                          delivery_fee:
                            - - USD
                              - '36.00'
                          net_due_to_merchant:
                            - - USD
                              - '204.00'
                        - number: 213
                          status: PENDING_PAYMENT
                          status_display: Pending Payment
                          issued_at: '2026-06-28T14:02:00Z'
                          order_count: 5
                          cod:
                            - - USD
                              - '95.00'
                          delivery_fee:
                            - - USD
                              - '15.00'
                          net_due_to_merchant:
                            - - USD
                              - '80.00'
                  summary: A page of invoice metadata, newest first.
          description: A page of invoice metadata.
      security:
        - MerchantAPIKey: []
components:
  schemas:
    PaginatedExternalInvoiceListItemList:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/ExternalInvoiceListItem'
    ExternalInvoiceListItem:
      type: object
      description: >-
        Invoice metadata for listing and grouping, without the per-order
        breakdown.


        order_count is read from an `order_count` annotation on the queryset,
        and the money

        totals come from the cached MoneyAmount purposes, so the listing
        queryset must both

        annotate the count and prefetch `money_amounts` to avoid a query per
        invoice.
      properties:
        number:
          type: integer
        status:
          type: string
        status_display:
          type: string
        issued_at:
          type: string
          format: date-time
        order_count:
          type: integer
        cod:
          type: array
          items:
            type: array
            items:
              type: string
            maxItems: 2
            minItems: 2
          readOnly: true
        delivery_fee:
          type: array
          items:
            type: array
            items:
              type: string
            maxItems: 2
            minItems: 2
          readOnly: true
        net_due_to_merchant:
          type: array
          items:
            type: array
            items:
              type: string
            maxItems: 2
            minItems: 2
          readOnly: true
      required:
        - cod
        - delivery_fee
        - issued_at
        - net_due_to_merchant
        - number
        - order_count
        - status
        - status_display
  securitySchemes:
    MerchantAPIKey:
      type: apiKey
      in: header
      name: X-Api-Key

````