Ingest retail invoices

Authentication

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

Authorization: Bearer <token>

What this endpoint does

This endpoint queries the VendorConfig table for all active vendors, then searches the user’s Gmail account for matching invoice emails within the determined date range. HTML content from matching emails is uploaded to S3. Duplicate emails (already present in S3) are skipped. If no custom date range is provided, the search window is determined automatically:

First fetch: last 30 days.
Subsequent fetches: from the last_retail_invoice_fetch timestamp stored on the user record.

After a successful run, the user’s last_retail_invoice_fetch timestamp is updated. The Gmail account must be connected before calling this endpoint. See Store Gmail tokens.

Request body

The request body is optional. All fields are optional.

start_date

string

Start of the custom search date range, in YYYY-MM-DD format. Must be provided together with end_date.

end_date

string

End of the custom search date range, in YYYY-MM-DD format. Must be provided together with start_date.

vendor_category

string

Optionally restrict processing to a single vendor category. Valid values: food-delivery, clothing, technology, subscriptions, grocery, utility, miscellaneous, travel.

Response

message

string

A human-readable confirmation message. Example: "Retail invoices fetched successfully"

code

number

HTTP status code. 200 on success.

data

object

Hide properties

totalEmailsFound

number

Total number of new retail invoice emails ingested across all vendors.

byVendor

object

A map of vendor ID to the number of new emails ingested for that vendor. Example: {"dominos": 2, "foodora": 3}.

dateRange

object

The date range that was searched.

Show properties

start

string

Start date of the search window in YYYY/MM/DD format.

end

string

End date of the search window in YYYY/MM/DD format.

errors

array

List of per-email or per-vendor errors encountered during processing. Capped at 20 entries. An empty array indicates no errors.

Error responses

Status	Error code	Description
`400`	`MISSING_FIELDS`	Only one of `start_date` / `end_date` was provided, or a required key is missing.
`400`	`INVALID_JSON`	The request body is not valid JSON.
`401`	`INVALID_CREDENTIALS`	The `Authorization` header is missing or the OAuth token is invalid.
`401`	`TOKEN_EXPIRED`	The JWT has expired.
`404`	`USER_NOT_FOUND`	No account exists for the user ID encoded in the token.
`502`	`DEPENDENCY_FAILURE`	The Gmail API returned an error.
`502`	`GMAIL_TOKEN_EXPIRED`	The Gmail OAuth refresh token has expired and the account must be re-connected.
`500`	`INTERNAL_SERVER_ERROR`	An unexpected server-side error occurred.

Error responses follow this structure:

{
  "error": {
    "code": "MISSING_FIELDS",
    "message": "Both start_date and end_date must be provided for custom date range"
  }
}

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

{
  "message": "Retail invoices fetched successfully",
  "code": 200,
  "data": {
    "totalEmailsFound": 5,
    "byVendor": {
      "dominos": 2,
      "foodora": 3
    },
    "dateRange": {
      "start": "2025/02/19",
      "end": "2025/03/21"
    },
    "errors": []
  }
}

Authentication

User

Invoices

Authentication

What this endpoint does

Request body

Response

Error responses

Build docs developers (and LLMs) love

Authentication

User

Invoices

Documentation Index

​Authentication

​What this endpoint does

​Request body

​Response

​Error responses

Build docs developers (and LLMs) love

Authentication

What this endpoint does

Request body

Response

Error responses