# Receipt Scanner (`confidential_sand/receipt-scanner`) Actor

Extract store name, date, total, items and more from receipt images or PDFs using AI-powered OCR. Ideal for expense tracking, finance automation, and data extraction workflows. Handles messy real-world formats with high accuracy.

- **URL**: https://apify.com/confidential\_sand/receipt-scanner.md
- **Developed by:** [Artur Malev](https://apify.com/confidential_sand) (community)
- **Categories:** AI, E-commerce, Automation
- **Stats:** 18 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Receipt Scanner

**Receipt Scanner is a service for automatic extraction of structured data exclusively from receipts and invoices. Processing of other document types is not guaranteed. Upload is possible only via an image URL; direct file upload is not supported.**

Receipt Scanner is a universal tool for automatically extracting structured data from receipt images using modern AI providers (OpenAI and OpenRouter). The service is designed for quick integration into any business process where receipt, invoice, or document recognition and analysis are required.

### Purpose and Advantages

- **Automation of routine tasks**: Instantly extract information from receipts without manual input.
- **Flexible architecture**: Supports multiple AI providers and is easily extendable.
- **High accuracy**: Utilizes state-of-the-art models for text and document structure recognition.
- **Easy integration**: API and Python interface for rapid embedding.
- **Scalability**: Supports both single and batch processing with configurable concurrency.
- **Enhanced data extraction**: Extracts specialized receipt data including loyalty program information, return policies, warranty details, gift receipt indicators, and promotional codes.

### How It Works

1. The user provides a URL (or several URLs for batch processing) to an image of a receipt or invoice (only URL, direct file upload is not supported).
2. Receipt Scanner determines the provider (OpenAI or OpenRouter) and sends a request for analysis.
3. For batch processing, requests are executed in parallel with a configurable concurrency limit.
4. The AI model extracts key data: store, date, items, amounts, taxes, and currency.
5. Results are cached to speed up repeated processing of the same receipts.
6. The result is returned in a standardized JSON format.

### Usage Costs

The service is provided free of charge during the testing period.

In the future, the cost will be determined according to Apify's pricing. Current prices can be found on the [Apify pricing page](https://apify.com/pricing).

- **OpenAI**: Pricing according to [OpenAI official pricing](https://openai.com/pricing).
- **OpenRouter**: Alternative provider, see prices at [openrouter.ai/pricing](https://openrouter.ai/pricing).
- The final cost depends on the volume and complexity of images, selected model, and provider.

### Quick Start

#### 1. Install Dependencies

```bash
pip install -r requirements.txt
```

#### 2. Configure Environment Variables

```bash
export OPENAI_API_KEY=your_key
export OPENROUTER_API_KEY=your_alternative_key
## Optionally for caching
export REDIS_URL=redis://localhost:6379/0
export CACHE_TTL_SECONDS=86400
```

#### 3. Use in Python Code

##### Processing a single URL (backward compatibility)

```python
from src.utils import process_receipt_url
result = process_receipt_url("https://example.com/receipt.jpg")
print(result)
```

##### Batch processing of multiple URLs

```python
from src.utils import process_receipt_urls
urls = [
    "https://example.com/receipt1.jpg",
    "https://example.com/receipt2.jpg",
    "https://example.com/receipt3.jpg"
]
results = process_receipt_urls(urls, max_concurrent=5)
for result in results:
    print(f"URL: {result['url']}")
    print(f"Cached: {result.get('cached', False)}")
    if 'data' in result:
        data = result['data']
        print(f"Store: {data.get('store', {}).get('name')}")
        print(f"Total: {data.get('totals', {}).get('total')}")
        
        # Access enhanced data fields
        if 'loyalty' in data:
            print(f"Loyalty Program: {data['loyalty'].get('program_name')}")
            print(f"Points Earned: {data['loyalty'].get('points_earned')}")
        
        if 'return_policy' in data:
            print(f"Return Period: {data['return_policy'].get('days_allowed')} days")
        
        if 'promotions' in data and 'promo_codes' in data['promotions']:
            print(f"Promo Codes: {', '.join(data['promotions']['promo_codes'])}")
        
        if 'gift_receipt' in data and data['gift_receipt'].get('is_gift_receipt'):
            print("This is a gift receipt")
    elif 'error' in result:
        print(f"Error: {result['error']}")
```

#### 4. API Usage

```bash
curl -X POST http://localhost:3000/api/v1/process \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/receipt.jpg"}'
```

##### Batch Processing of Multiple URLs

```bash
curl -X POST http://localhost:3000/api/v1/process-batch \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/receipt1.jpg", "https://example.com/receipt2.jpg"]}'
```

### API Usage

#### Input Schema

The Receipt Scanner expects a JSON object as input with the following fields:

- `receiptUrls` (array of strings, required): Array of receipt image URLs to be scanned. Example:

```json
{
  "receiptUrls": [
    "https://example.com/receipt1.jpg",
    "https://example.com/receipt2.jpg"
  ],
  "maxConcurrent": 5
}
```

- `maxConcurrent` (integer, optional): Maximum number of concurrent requests for batch processing. Default is 5. Minimum is 1, maximum is 20.

##### Example Input

```json
{
  "receiptUrls": [
    "https://example.com/receipt1.jpg",
    "https://example.com/receipt2.jpg"
  ],
  "maxConcurrent": 3
}
```

##### Example Output (Success)

```json
[
  {
    "url": "https://example.com/receipt1.jpg",
    "cached": false,
    "data": {
      "store": "Walmart",
      "date": "2024-06-01",
      "items": [
        {"name": "Milk", "price": 2.99, "qty": 1},
        {"name": "Bread", "price": 1.49, "qty": 2}
      ],
      "total": 5.97,
      "currency": "USD"
    }
  },
  {
    "url": "https://example.com/receipt2.jpg",
    "cached": true,
    "data": {
      "store": "Target",
      "date": "2024-06-02",
      "items": [
        {"name": "Eggs", "price": 3.49, "qty": 1}
      ],
      "total": 3.49,
      "currency": "USD"
    }
  }
]
```

##### Example Output (Error)

```json
[
  {
    "url": "https://example.com/invalid.jpg",
    "cached": false,
    "error": {
      "code": "INVALID_URL",
      "message": "Invalid or missing URL provided."
    }
  }
]
```

#### Example Response (Single Receipt)

```json
{
  "store": {
    "name": "Sample Store",
    "address": "Moscow, Example St., 1",
    "date": "2024-06-01",
    "time": "14:23",
    "currency": "RUB"
  },
  "items": [
    {
      "name": "Apple",
      "category": "food",
      "quantity": 3,
      "unit_price": 0.5,
      "total_price": 1.5
    }
  ],
  "totals": {
    "subtotal": 1.5,
    "tax": 0.15,
    "total": 1.65,
    "currency": "RUB"
  },
  "loyalty": {
    "program_name": "Store Rewards",
    "member_id": "12345678",
    "points_earned": 15,
    "points_balance": 230,
    "tier_status": "Gold",
    "expiration_date": "2025-12-31"
  },
  "return_policy": {
    "days_allowed": 30,
    "conditions": "Items must be in original packaging",
    "receipt_required": true,
    "restocking_fee": 0,
    "exceptions": "Sale items are final sale"
  },
  "warranty": {
    "duration": "1 year",
    "coverage": "Parts and labor",
    "contact_info": "support@example.com",
    "conditions": "Valid with receipt only",
    "product_registration": "Register at example.com/warranty"
  },
  "gift_receipt": {
    "is_gift_receipt": false
  },
  "promotions": {
    "promo_codes": ["SUMMER10", "NEXT5OFF"],
    "future_discounts": ["10% off next purchase"],
    "special_offers": ["Buy 2 Get 1 Free on all produce next week"],
    "expiration_dates": ["2024-07-15"],
    "conditions": "Cannot be combined with other offers"
  }
}
```

#### Example Response (Batch Processing)

```json
[
  {
    "url": "https://example.com/receipt1.jpg",
    "data": {
      "store": { "name": "Store 1", "date": "2024-06-01" },
      "items": [ { "name": "Item 1", "total_price": 10.5 } ],
      "totals": { "total": 10.5 },
      "loyalty": { 
        "program_name": "Store Rewards", 
        "points_earned": 10 
      },
      "return_policy": { 
        "days_allowed": 30 
      },
      "promotions": {
        "promo_codes": ["SUMMER10"]
      }
    },
    "cached": false
  },
  {
    "url": "https://example.com/receipt2.jpg",
    "data": {
      "store": { "name": "Store 2", "date": "2024-06-02" },
      "items": [ { "name": "Item 2", "total_price": 15.75 } ],
      "totals": { "total": 15.75 },
      "gift_receipt": {
        "is_gift_receipt": true,
        "gift_message": "Happy Birthday!"
      }
    },
    "cached": true
  },
  {
    "url": "https://example.com/invalid.jpg",
    "error": {
      "code": "PROCESSING_ERROR",
      "message": "Failed to process receipt image"
    }
  }
]
```

### Features

- Text recognition on receipt and invoice images (including handwritten and blurry ones).
- Item categorization.
- Support for various currencies and languages.
- Flexible error handling and data validation.
- Simple integration into third-party services via API.
- **Batch processing** — Ability to process multiple receipt URLs simultaneously.
- **Result caching** — Storing processed results by image hash to avoid redundant processing.
- **Parallel execution** — Configurable concurrency limits for optimal performance.
- **Enhanced data extraction** — Extracts specialized receipt data including:
  - **Loyalty program information** — Program name, member ID, points earned/balance, tier status
  - **Return policy details** — Return period, conditions, receipt requirements
  - **Warranty information** — Duration, coverage, contact information
  - **Gift receipt identification** — Detects if the receipt is a gift receipt
  - **Promotional codes** — Future discounts, special offers, expiration dates

### Limitations

- Recognition quality depends on the image quality and the selected model.
- Valid API keys are required for operation.
- Providers may impose rate and volume limits.
- Processing is possible only for receipts and invoices. Other document types are not supported or guaranteed.

### Testing

```bash
pytest tests/
```

### Cloudflare Worker

An example Worker implementation is available in the `cloudflare/` directory. It
handles the same JSON payloads as the Python service and can cache results in a
KV namespace. Deploy it with `wrangler`:

```bash
npm install -g wrangler
wrangler kv:namespace create receipt-scanner-cache
wrangler secret put OPENAI_API_KEY # and other keys as needed
wrangler deploy
```

Set `RECEIPT_ANALYSIS_PROVIDER` and `CACHE_TTL_SECONDS` (or `CACHE_TTL`) to match the Python configuration. Other secrets like `OPENROUTER_API_KEY` and `OPENAI_ASSISTANT_ID` are optional depending on the provider.

If the KV binding is not configured, the worker still functions but without
caching.

### Useful Links

- [OpenAI Documentation](https://platform.openai.com/docs)
- [OpenRouter Documentation](https://openrouter.ai/docs)
- [Apify Web Scraping 101](https://docs.apify.com/web-scraping-101)
- [Crawlee — scraping library](https://crawlee.dev)

### License

MIT

# Actor input Schema

## `receiptUrls` (type: `array`):

Array of receipt image URLs to be scanned.

## `maxConcurrent` (type: `integer`):

Maximum number of concurrent requests for batch processing.

## Actor input object example

```json
{
  "receiptUrls": [
    "https://example.com/receipt.jpg"
  ],
  "maxConcurrent": 5
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "receiptUrls": [
        "https://example.com/receipt.jpg"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("confidential_sand/receipt-scanner").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "receiptUrls": ["https://example.com/receipt.jpg"] }

# Run the Actor and wait for it to finish
run = client.actor("confidential_sand/receipt-scanner").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "receiptUrls": [
    "https://example.com/receipt.jpg"
  ]
}' |
apify call confidential_sand/receipt-scanner --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,confidential_sand/receipt-scanner"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ndTIC4v2UWPrfvPUO/builds/u2yaC9fazuwXkH6JS/openapi.json