How to add new retail invoice vendors to PayPulse Cloud.
Adding a new vendor requires two steps: creating a JSON config file and optionally adding a prompt config for the Gemini parser. No Lambda code changes are needed.
1
Create the vendor config JSON
Create a new file at vendor_configs/{sub_type}/{vendor_id}.json. The vendor_id must be lowercase and unique across all vendors — it is used as the DynamoDB partition key and as the S3 path segment.
Place the file in the subdirectory that matches the invoice_sub_type value (e.g. vendor_configs/clothing/ for clothing vendors).
2
Upload the config to DynamoDB
Run the upload script from the vendor_configs/ directory. The script iterates over all */*.json files and uploads each one using aws dynamodb put-item with a attribute_not_exists(vendor_id) condition, so existing records are never overwritten.
To improve parsing accuracy, add an entry to lambda_layers/gemini_parsers/python/vendor_prompt_configs/{sub_type}.py.
"vendor_id": { "vendor_desc": "Short description of the vendor", "is_email_in_swedish": False, "items_desc": "what the items are (e.g. electronics)", # optional "header_info": 'Look for "Order confirmation" header.', # optional "field_translations": { # optional, Swedish vendors only "Ordernummer": "Order number", "Totalt": "Total", },},
The vendor_id key must exactly match the vendor_id value in the JSON config. This step can be skipped — the parser will still run, but with less context.
4
Test the new vendor
Trigger a retail invoice fetch for your account by calling the ingest endpoint. You can scope the request to a specific date range to avoid re-fetching old data:
#!/bin/bash# Script to upload vendor configurations to DynamoDB VendorConfig table# Usage: ./upload_vendors.sh# Color codes for outputGREEN='\033[0;32m'RED='\033[0;31m'YELLOW='\033[1;33m'NC='\033[0m' # No ColorTABLE_NAME="VendorConfig"SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"echo "========================================="echo "Uploading vendor configs to DynamoDB"echo "Table: $TABLE_NAME"echo "========================================="echo ""# Counter for statisticstotal=0success=0already_exists=0failed=0# Iterate over all JSON files in subdirectoriesfor config_file in "$SCRIPT_DIR"/*/*.json; do # Check if any JSON files exist if [ ! -f "$config_file" ]; then echo -e "${YELLOW}No JSON files found in $SCRIPT_DIR subdirectories${NC}" exit 1 fi filename=$(basename "$config_file") vendor_id=$(echo "$filename" | sed 's/.json$//') total=$((total + 1)) echo -n "Uploading $filename ... " # Run the put-item command with condition expression if aws dynamodb put-item \ --table-name "$TABLE_NAME" \ --item "file://$config_file" \ --condition-expression "attribute_not_exists(vendor_id)" \ --no-cli-pager \ 2>&1 | grep -q "ConditionalCheckFailedException"; then echo -e "${YELLOW}ALREADY EXISTS${NC}" already_exists=$((already_exists + 1)) elif [ ${PIPESTATUS[0]} -eq 0 ]; then echo -e "${GREEN}SUCCESS${NC}" success=$((success + 1)) else echo -e "${RED}FAILED${NC}" failed=$((failed + 1)) fidoneecho ""echo "========================================="echo "Upload Summary"echo "========================================="echo "Total files: $total"echo -e "${GREEN}Successful: $success${NC}"echo -e "${YELLOW}Already existed: $already_exists${NC}"echo -e "${RED}Failed: $failed${NC}"echo "========================================="# Exit with error code if any failedif [ $failed -gt 0 ]; then exit 1fi
The script uses a conditional write (attribute_not_exists(vendor_id)) so running it multiple times is safe — existing records are never silently overwritten. If you need to update an existing vendor’s configuration, use aws dynamodb update-item or delete and re-upload the record.
Set active to false to disable a vendor without deleting its record. The get_active_vendors() function filters on active = true, so the vendor will be excluded from all fetch runs until you re-enable it.
default_email_patterns and default_subject_keywords must be specific. A broad sender address like noreply@gmail.com or a generic subject keyword like Order will match promotional and transactional emails that are not invoices, causing the parser to process irrelevant content and producing noise in the invoice store.