> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/azfar-imtiaz/PayPulse-Cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Get invoices

> Retrieve rental or retail invoices for the authenticated user.

## Authentication

All requests to this endpoint must include a valid JWT in the `Authorization` header.

```
Authorization: Bearer <token>
```

## Path parameters

<ParamField path="type" type="string" required>
  Invoice type. Must be `rental` or `retail`.
</ParamField>

## Query parameters

The following query parameters are supported **for retail invoices only** (`type=retail`). They are not valid when `type=rental`.

<ParamField query="subtype" type="string">
  Filter by retail invoice sub-type. Valid values: `food-delivery`, `clothing`, `technology`, `subscriptions`, `grocery`, `utility`, `miscellaneous`, `travel`.
</ParamField>

<ParamField query="invoice-id" type="string">
  Retrieve the parsed detail record for a specific retail invoice. Requires `subtype` to also be set.
</ParamField>

<ParamField query="counts" type="boolean">
  When `true`, return invoice counts instead of invoice records. Can be combined with `subtype` to count a specific category. Cannot be used together with `invoice-id`.
</ParamField>

## Behavior by mode

<Tabs>
  <Tab title="Rental invoices">
    `GET /v1/invoices/rental`

    Returns all rental invoices for the user from the `RentalInvoices` DynamoDB table, grouped by year. No query parameters are supported for rental invoices.

    **Response `data`:**

    * `invoiceCount` — total number of invoices
    * `invoices` — object keyed by year (e.g. `"2025"`), each value an array of invoice objects

    ```bash theme={null}
    curl --request GET \
      --url https://api.paypulse.io/v1/invoices/rental \
      --header 'Authorization: Bearer <token>'
    ```
  </Tab>

  <Tab title="All retail invoices">
    `GET /v1/invoices/retail`

    Returns all retail invoices for the user from the `RetailInvoices` base table (summary records only).

    **Response `data`:**

    * `invoiceCount` — total number of retail invoices
    * `invoices` — array of invoice summary objects

    ```bash theme={null}
    curl --request GET \
      --url https://api.paypulse.io/v1/invoices/retail \
      --header 'Authorization: Bearer <token>'
    ```
  </Tab>

  <Tab title="Retail by sub-type">
    `GET /v1/invoices/retail?subtype=food-delivery`

    Returns retail invoices filtered to a specific category using the `sub_type-invoice_date-index` GSI.

    ```bash theme={null}
    curl --request GET \
      --url 'https://api.paypulse.io/v1/invoices/retail?subtype=food-delivery' \
      --header 'Authorization: Bearer <token>'
    ```
  </Tab>

  <Tab title="Retail invoice details">
    `GET /v1/invoices/retail?subtype=food-delivery&invoice-id=retail_invoice_abc123`

    Returns the full parsed detail record from the category detail table (e.g. `FoodDeliveryInvoices`) for a specific invoice. Both `subtype` and `invoice-id` are required together.

    **Response `data`:**

    * `invoiceDetails` — the full detail record from the category-specific DynamoDB table

    ```bash theme={null}
    curl --request GET \
      --url 'https://api.paypulse.io/v1/invoices/retail?subtype=clothing&invoice-id=retail_invoice_abc123' \
      --header 'Authorization: Bearer <token>'
    ```
  </Tab>

  <Tab title="Invoice counts">
    `GET /v1/invoices/retail?counts=true`

    Returns the count of retail invoices per sub-type for the user. Add `subtype` to count only one category.

    ```bash theme={null}
    # All categories
    curl --request GET \
      --url 'https://api.paypulse.io/v1/invoices/retail?counts=true' \
      --header 'Authorization: Bearer <token>'

    # Single category
    curl --request GET \
      --url 'https://api.paypulse.io/v1/invoices/retail?subtype=grocery&counts=true' \
      --header 'Authorization: Bearer <token>'
    ```
  </Tab>
</Tabs>

## Response (rental invoices)

<ResponseField name="message" type="string">
  Example: `"Rental invoices retrieved successfully!"`
</ResponseField>

<ResponseField name="code" type="number">
  `200` on success.
</ResponseField>

<ResponseField name="data" type="object | null">
  `null` when no invoices exist. Otherwise:

  <Expandable title="properties" defaultOpen>
    <ResponseField name="invoiceCount" type="number">
      Total number of rental invoices found.
    </ResponseField>

    <ResponseField name="invoices" type="object">
      Invoices grouped by year (e.g., `"2024"`, `"2025"`). Each value is an array of invoice objects.

      <Expandable title="invoice object">
        <ResponseField name="InvoiceID" type="string">
          Unique invoice identifier.
        </ResponseField>

        <ResponseField name="UserID" type="string">
          ID of the user who owns this invoice.
        </ResponseField>

        <ResponseField name="due_date_month" type="string">
          Month of the invoice due date (e.g., `"3"` for March).
        </ResponseField>

        <ResponseField name="due_date_year" type="string">
          Year of the invoice due date (e.g., `"2025"`).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Error code              | Description                                                                                                                                                                           |
| ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `INVALID_REQUEST`       | The `type` path parameter is not `rental` or `retail`, an invalid `subtype` value was provided, `invoice-id` was given without `subtype`, or `counts` and `invoice-id` were combined. |
| `401`  | `INVALID_CREDENTIALS`   | The `Authorization` header is missing or the token is invalid.                                                                                                                        |
| `401`  | `TOKEN_EXPIRED`         | The JWT has expired.                                                                                                                                                                  |
| `404`  | `INVALID_REQUEST`       | Invoice not found (when using `invoice-id`).                                                                                                                                          |
| `502`  | `DEPENDENCY_FAILURE`    | A downstream dependency (DynamoDB) returned an error.                                                                                                                                 |
| `500`  | `INTERNAL_SERVER_ERROR` | An unexpected server-side error occurred.                                                                                                                                             |

<ResponseExample>
  ```json 200 (rental) theme={null}
  {
    "message": "Rental invoices retrieved successfully!",
    "code": 200,
    "data": {
      "invoiceCount": 2,
      "invoices": {
        "2025": [
          {
            "InvoiceID": "inv_abc123",
            "UserID": "user_xyz789",
            "due_date_month": "3",
            "due_date_year": "2025"
          }
        ],
        "2024": [
          {
            "InvoiceID": "inv_def456",
            "UserID": "user_xyz789",
            "due_date_month": "12",
            "due_date_year": "2024"
          }
        ]
      }
    }
  }
  ```

  ```json 200 (no invoices) theme={null}
  {
    "message": "No rental invoices found for this user.",
    "code": 200,
    "data": null
  }
  ```

  ```json 400 (invalid type) theme={null}
  {
    "error": {
      "code": "INVALID_REQUEST",
      "message": "Invalid invoice type 'unknown'. Must be 'rental' or 'retail'"
    }
  }
  ```

  ```json 400 (invalid subtype) theme={null}
  {
    "error": {
      "code": "INVALID_REQUEST",
      "message": "Invalid retail sub-type 'xyz'. Valid options: food-delivery, clothing, technology, subscriptions, grocery, utility, miscellaneous, travel"
    }
  }
  ```
</ResponseExample>