Get invoices - PayPulse Cloud

Authentication

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

Authorization: Bearer <token>

Path parameters

type

string

required

Invoice type. Must be rental or retail.

Query parameters

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

subtype

string

Filter by retail invoice sub-type. Valid values: food-delivery, clothing, technology, subscriptions, grocery, utility, miscellaneous, travel.

invoice-id

string

Retrieve the parsed detail record for a specific retail invoice. Requires subtype to also be set.

counts

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.

Behavior by mode

Rental invoices
All retail invoices
Retail by sub-type
Retail invoice details
Invoice counts

GET /v1/invoices/rentalReturns 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

curl --request GET \
  --url https://api.paypulse.io/v1/invoices/rental \
  --header 'Authorization: Bearer <token>'

GET /v1/invoices/retailReturns 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

curl --request GET \
  --url https://api.paypulse.io/v1/invoices/retail \
  --header 'Authorization: Bearer <token>'

GET /v1/invoices/retail?subtype=food-deliveryReturns retail invoices filtered to a specific category using the sub_type-invoice_date-index GSI.

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

GET /v1/invoices/retail?subtype=food-delivery&invoice-id=retail_invoice_abc123Returns 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

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

GET /v1/invoices/retail?counts=trueReturns the count of retail invoices per sub-type for the user. Add subtype to count only one category.

# 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>'

Response (rental invoices)

message

string

Example: "Rental invoices retrieved successfully!"

code

number

200 on success.

data

object | null

null when no invoices exist. Otherwise:

Hide properties

invoiceCount

number

Total number of rental invoices found.

invoices

object

Invoices grouped by year (e.g., "2024", "2025"). Each value is an array of invoice objects.

Show invoice object

InvoiceID

string

Unique invoice identifier.

UserID

string

ID of the user who owns this invoice.

due_date_month

string

Month of the invoice due date (e.g., "3" for March).

due_date_year

string

Year of the invoice due date (e.g., "2025").

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.

{
  "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"
        }
      ]
    }
  }
}

Authentication

User

Invoices

Documentation Index

​Authentication

​Path parameters

​Query parameters

​Behavior by mode

​Response (rental invoices)

​Error responses

Build docs developers (and LLMs) love

Authentication

Path parameters

Query parameters

Behavior by mode

Response (rental invoices)

Error responses