Ingest retail invoices

Fetch retail invoice HTML emails from Gmail for all configured vendors and upload them to S3.

POST /v1/invoices/retail/ingest

cURL (automatic date range)

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

curl --request POST \
  --url https://api.paypulse.io/v1/invoices/retail/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_date": "2025-01-01",
    "end_date": "2025-03-21"
  }'

200

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

{
  "message": "No active vendors configured for retail invoice fetching",
  "code": 200,
  "data": {
    "totalEmailsFound": 0,
    "byVendor": {},
    "dateRange": {
      "start": "2025/02/19",
      "end": "2025/03/21"
    }
  }
}

{
  "error": {
    "code": "GMAIL_TOKEN_EXPIRED",
    "message": "Gmail account needs to be re-connected"
  }
}

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 (automatic date range)

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

curl --request POST \
  --url https://api.paypulse.io/v1/invoices/retail/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_date": "2025-01-01",
    "end_date": "2025-03-21"
  }'

200

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

{
  "message": "No active vendors configured for retail invoice fetching",
  "code": 200,
  "data": {
    "totalEmailsFound": 0,
    "byVendor": {},
    "dateRange": {
      "start": "2025/02/19",
      "end": "2025/03/21"
    }
  }
}

{
  "error": {
    "code": "GMAIL_TOKEN_EXPIRED",
    "message": "Gmail account needs to be re-connected"
  }
}