Receipt Processing API Documentation

Endpoint

Upload a receipt image and receive structured JSON data with merchant information, line items, totals, taxes, and payment details. The API automatically validates that the uploaded image contains a valid receipt.

AI-Powered Receipt Validation

How Validation Works

Receipt Types Supported

The AI validation recognizes receipts from:

Request Format

// JavaScript/TypeScript Example
const formData = new FormData();
formData.append('image', fileInput.files[0]);

const response = await fetch('/api/receipt/process', {
  method: 'POST',
  body: formData,
});

const receipt = await response.json();

# cURL Example
curl -X POST https://your-domain.com/api/receipt/process \
  -F "image=@receipt.jpg"

Response Format

Success Response (200)

Returns a ParsedReceipt object with the following structure:

{
  // Merchant Information
  "merchantName": "Fresh Market Grocery",
  "merchantAddress": "123 Main Street, Springfield, IL 62701",
  "merchantPhone": "(555) 123-4567",
  "merchantTaxId": "12-3456789",
  
  // Transaction Details
  "transactionId": "TXN-1234567890-ABCDEF123",
  "date": "2024-01-15",
  "timestamp": "2024-01-15T14:30:00.000Z",
  
  // Line Items
  "items": [
    {
      "name": "Organic Bananas",
      "quantity": 1.5,
      "unitPrice": 0.69,
      "totalPrice": 1.04,
      "category": "Produce",
      "sku": "PROD-001",
      "discounted": false
    },
    {
      "name": "Whole Milk (1 gal)",
      "quantity": 1,
      "unitPrice": 4.99,
      "totalPrice": 4.99,
      "category": "Dairy"
    }
  ],
  
  // Financial Summary
  "subtotal": 23.45,
  "discount": 2.35,
  "taxes": [
    {
      "name": "Sales Tax",
      "rate": 8.25,
      "amount": 1.74
    }
  ],
  "tip": 0,
  "total": 22.84,
  
  // Payment Information
  "payments": [
    {
      "method": "Credit Card",
      "cardLast4": "4532",
      "amount": 22.84
    }
  ],
  "amountTendered": null,
  "changeGiven": null,
  
  // Additional Details
  "currency": "USD",
  "cashierName": "John D.",
  "registerNumber": "REG-1",
  
  // Processing Metadata
  "metadata": {
    "processedAt": "2024-01-15T14:35:00.000Z",
    "confidence": 0.92,
    "imageFormat": "JPEG",
    "imageSize": 2457600,
    "isMockData": false
  }
}

Error Responses

{
  "error": "Invalid file type",
  "status": 400,
  "details": "Supported formats: JPEG, PNG, WebP, HEIC. Received: image/gif"
}

{
  "error": "Invalid receipt image",
  "status": 400,
  "details": "Not a valid receipt: insufficient receipt indicators found"
}

{
  "error": "Failed to process receipt image",
  "status": 500,
  "details": "OCR service unavailable"
}

TypeScript Types

Import the types from the API module for full type safety:

import type {
  ParsedReceipt, 
  ReceiptItem,
  ReceiptTax,
  ReceiptPayment,
  ReceiptProcessError 
} from '@/types/receipt/types'

// Use in your code
const processReceipt = async (file: File): Promise<ParsedReceipt> => {
  const formData = new FormData()
  formData.append('image', file)
  
  const response = await fetch('/api/receipt/process', {
    method: 'POST',
    body: formData,
  })
  
  if (!response.ok) {
    const error: ReceiptProcessError = await response.json()
    throw new Error(error.error)
  }
  
  return await response.json()
}

Best Practices

• ✓
  Image Quality: Use well-lit, clear images with the entire receipt visible for best results.
• ✓
  File Size: Compress images before upload to reduce processing time and bandwidth usage.
• ✓
  Error Handling: Always check the response status and handle errors gracefully.
• ✓
  Validation: Validate the confidence score in metadata before trusting the extracted data.
• ✓
  Privacy: Handle receipt images securely as they may contain sensitive personal or financial information.

Production Considerations