# Invoice Generator Input (`moving_beacon-owner1/invoice-generator-input`) Actor

A flexible and developer-friendly tool to generate professional invoices from structured input data. Supports line items, tax, discounts, and optional HTML output.

- **URL**: https://apify.com/moving\_beacon-owner1/invoice-generator-input.md
- **Developed by:** [Jamshaid Arif](https://apify.com/moving_beacon-owner1) (community)
- **Categories:** Automation, Developer tools, Other
- **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## 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

## 🧾 Invoice Generator

A flexible and developer-friendly tool to generate professional invoices from structured input data. Supports line items, tax, discounts, and optional HTML output.

***

### 🚀 Features

- 🧩 Structured invoice generation from JSON input
- 📦 Supports multiple line items with quantity and pricing
- 💰 Automatic subtotal, tax, discount, and total calculation
- 🌐 Optional HTML invoice generation
- 🛡️ Strong input validation with strict schema
- 🔌 Easy integration into APIs, automation tools, and workflows

***

### 📥 Input Schema

| Field              | Type    | Required | Description |
|-------------------|--------|----------|-------------|
| `invoiceNumber`   | string | ❌ No    | Unique invoice ID (default: INV-001) |
| `issueDate`       | string | ❌ No    | Format: YYYY-MM-DD (defaults to today) |
| `dueDate`         | string | ❌ No    | Format: YYYY-MM-DD (defaults to +30 days) |
| `fromName`        | string | ✅ Yes   | Sender name or company |
| `fromAddress`     | string | ❌ No    | Sender address |
| `fromEmail`       | string | ❌ No    | Sender email |
| `toName`          | string | ✅ Yes   | Recipient name or company |
| `toAddress`       | string | ❌ No    | Recipient address |
| `toEmail`         | string | ❌ No    | Recipient email |
| `items`           | array  | ✅ Yes   | List of invoice items |
| `taxRate`         | number | ❌ No    | Tax percentage (0–100) |
| `discountPercent` | number | ❌ No    | Discount percentage (0–100) |
| `currency`        | string | ❌ No    | Currency symbol (default: $) |
| `notes`           | string | ❌ No    | Notes or payment terms |
| `generateHTML`    | boolean| ❌ No    | Generate HTML invoice (default: true) |

***

### 📦 Line Item Format

Each item in the `items` array must follow:

```json
{
  "description": "Web development service",
  "quantity": 2,
  "unitPrice": 150
}
```

***

### ⚙️ How It Works

#### 💵 Calculations

1. **Subtotal**

```
subtotal = sum(quantity × unitPrice)
```

2. **Discount**

```
discount = subtotal × (discountPercent / 100)
```

3. **Tax**

```
tax = (subtotal - discount) × (taxRate / 100)
```

4. **Total**

```
total = subtotal - discount + tax
```

***

### 🧮 Example

#### Input

```json
{
  "fromName": "Umar Tech",
  "toName": "Client Inc.",
  "items": [
    { "description": "API Development", "quantity": 1, "unitPrice": 500 },
    { "description": "Hosting", "quantity": 2, "unitPrice": 50 }
  ],
  "taxRate": 10,
  "discountPercent": 5
}
```

#### Output

```json
{
  "subtotal": 600,
  "discount": 30,
  "tax": 57,
  "total": 627
}
```

***

### 🏗️ Use Cases

- Freelancers generating invoices
- SaaS billing systems
- Automation pipelines (Apify, scripts, etc.)
- Backend invoice services
- Client billing dashboards

***

### 🌐 HTML Output

If `generateHTML` is enabled, the tool returns a **ready-to-use invoice template** that can be:

- Rendered in a browser
- Converted to PDF
- Sent via email

***

### ⚡ Notes

- If dates are not provided, defaults are automatically applied
- At least one item is required in the invoice
- Discounts are applied **before tax calculation**
- Currency symbol is customizable

***

### 🛠️ Example Logic (Pseudo Code)

```python
subtotal = sum(item["quantity"] * item["unitPrice"] for item in items)
discount = subtotal * (discountPercent / 100)
tax = (subtotal - discount) * (taxRate / 100)
total = subtotal - discount + tax
```

***

### 📄 License

MIT License

# Actor input Schema

## `invoiceNumber` (type: `string`):

Unique identifier for the invoice.

## `issueDate` (type: `string`):

Invoice issue date in YYYY-MM-DD format. Defaults to today if empty.

## `dueDate` (type: `string`):

Payment due date in YYYY-MM-DD format. Defaults to 30 days from issue date if empty.

## `fromName` (type: `string`):

Sender name or company issuing the invoice.

## `fromAddress` (type: `string`):

Sender address details.

## `fromEmail` (type: `string`):

Sender contact email address.

## `toName` (type: `string`):

Recipient name or company being billed.

## `toAddress` (type: `string`):

Recipient address details.

## `toEmail` (type: `string`):

Recipient contact email address.

## `items` (type: `array`):

List of invoice items with description, quantity, and unit price.

## `taxRate` (type: `number`):

Tax percentage applied to subtotal.

## `discountPercent` (type: `number`):

Discount percentage applied before tax.

## `currency` (type: `string`):

Currency symbol used in the invoice (e.g., $, €, ₹).

## `notes` (type: `string`):

Additional notes or payment terms.

## `generateHTML` (type: `boolean`):

If enabled, generates an HTML version of the invoice.

## Actor input object example

```json
{
  "invoiceNumber": "INV-001",
  "issueDate": "",
  "dueDate": "",
  "fromName": "Your Company Name",
  "fromAddress": "Your Address",
  "fromEmail": "you@example.com",
  "toName": "Client Name",
  "toAddress": "Client Address",
  "toEmail": "client@example.com",
  "items": [
    {
      "description": "Web Development Service",
      "quantity": 1,
      "unitPrice": 500
    },
    {
      "description": "Hosting (1 year)",
      "quantity": 2,
      "unitPrice": 50
    }
  ],
  "taxRate": 0,
  "discountPercent": 0,
  "currency": "$",
  "notes": "Payment due within 30 days.",
  "generateHTML": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "invoiceNumber": "INV-001",
    "issueDate": "",
    "dueDate": "",
    "fromName": "Your Company Name",
    "fromAddress": "Your Address",
    "fromEmail": "you@example.com",
    "toName": "Client Name",
    "toAddress": "Client Address",
    "toEmail": "client@example.com",
    "items": [
        {
            "description": "Web Development Service",
            "quantity": 1,
            "unitPrice": 500
        },
        {
            "description": "Hosting (1 year)",
            "quantity": 2,
            "unitPrice": 50
        }
    ],
    "taxRate": 0,
    "discountPercent": 0,
    "currency": "$",
    "notes": "Payment due within 30 days.",
    "generateHTML": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("moving_beacon-owner1/invoice-generator-input").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 = {
    "invoiceNumber": "INV-001",
    "issueDate": "",
    "dueDate": "",
    "fromName": "Your Company Name",
    "fromAddress": "Your Address",
    "fromEmail": "you@example.com",
    "toName": "Client Name",
    "toAddress": "Client Address",
    "toEmail": "client@example.com",
    "items": [
        {
            "description": "Web Development Service",
            "quantity": 1,
            "unitPrice": 500,
        },
        {
            "description": "Hosting (1 year)",
            "quantity": 2,
            "unitPrice": 50,
        },
    ],
    "taxRate": 0,
    "discountPercent": 0,
    "currency": "$",
    "notes": "Payment due within 30 days.",
    "generateHTML": True,
}

# Run the Actor and wait for it to finish
run = client.actor("moving_beacon-owner1/invoice-generator-input").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "invoiceNumber": "INV-001",
  "issueDate": "",
  "dueDate": "",
  "fromName": "Your Company Name",
  "fromAddress": "Your Address",
  "fromEmail": "you@example.com",
  "toName": "Client Name",
  "toAddress": "Client Address",
  "toEmail": "client@example.com",
  "items": [
    {
      "description": "Web Development Service",
      "quantity": 1,
      "unitPrice": 500
    },
    {
      "description": "Hosting (1 year)",
      "quantity": 2,
      "unitPrice": 50
    }
  ],
  "taxRate": 0,
  "discountPercent": 0,
  "currency": "$",
  "notes": "Payment due within 30 days.",
  "generateHTML": true
}' |
apify call moving_beacon-owner1/invoice-generator-input --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=moving_beacon-owner1/invoice-generator-input",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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