# Invoice Generator API

We created a simple API at Invoice-Generator.com to generate invoice PDFs on the fly. This service has been used internally by us for some time. We believe this could be helpful in your project as well.

The API has a primary endpoint that returns a PDF given details of an invoice. We don't store any of your invoice data.

In addition to PDF, the API can also generate e-invoices in UBL (Universal Business Language) with the invoice PDF embedded. This is useful as the world shifts to e-invoicing because UBL invoices are tricky to generate.

### Use Cases
- Creating invoices for VAT compliance
- Generate a PDF of an invoice that you have the details to (recipient, line items, etc)
- Produce invoices for B2B buyers from an order or receipt
- Selling products or services on credit terms
- Creating e-invoices in UBL (Universal Business Language)

## Getting Started

In order to begin using the Invoice-Generator.com API, you first need to create an API key. The process for obtaining an API key is as follows.

1. Create a free Invoice-Generator.com account [here](https://invoice-generator.com/signup), or sign in if you already have one.
2. Go to the [Developer Settings](https://invoice-generator.com/app/settings/developers) page (**Settings** > **Developer**).
3. In the "API Keys" section, click **New** to generate an API key.

Now you have an API key and are ready to start invoicing!

A machine-readable [OpenAPI specification](/openapi.yaml) is available and can be imported into API clients such as Postman, Insomnia, or Bruno.

**The free API plan has a limit of 100 invoices per month. In order to generate more invoices you will need to purchase an API subscription.**

## Examples

### Simple Invoice

```bash
curl https://invoice-generator.com \
  -H "Authorization: Bearer myApiKey" \
  -d from="Nikolaus Ltd" \
  -d to="Acme, Corp." \
  -d logo="https://example.com/img/logo-invoice.png" \
  -d number=1 \
  -d date="Feb 9, 2015" \
  -d due_date="Feb 16, 2015" \
  -d "items[0][name]"="Starter plan monthly" \
  -d "items[0][quantity]"=1 \
  -d "items[0][unit_cost]"=99 \
  -d notes="Thanks for being an awesome customer\!" \
  -d terms="Please pay by the due date." \
> invoice.pdf
```

### VAT Invoice

Here's a simple cURL example for generating invoices with VAT:

```bash
curl https://invoice-generator.com \
  -H "Authorization: Bearer myApiKey" \
  -d from="Nikolaus Ltd%0AVAT ID: 1234" \
  -d to="Foster Moen%0AVAT ID: 4567" \
  -d logo="https://example.com/img/logo-invoice.png" \
  -d number=1 \
  -d date="Feb 9, 2015" \
  -d payment_terms="Charged - Do Not Pay" \
  -d "items[0][name]"="Starter Plan Monthly" \
  -d "items[0][quantity]"=1 \
  -d "items[0][unit_cost]"=99 \
  -d tax_title="VAT" \
  -d "fields[tax]"="%" \
  -d tax=8 \
  -d notes="Thanks for being an awesome customer\!" \
  -d terms="No need to submit payment. You will be auto-billed for this invoice." \
> invoice.vat.pdf
```

### JSON Input

JSON input is also accepted with the `Content-Type` header set to `application/json`

```bash
curl https://invoice-generator.com \
  -H "Authorization: Bearer myApiKey" \
  -H "Content-Type: application/json" \
  -d '{"from":"Nikolaus Ltd","to":"Acme, Corp.","logo":"https://example.com/img/logo-invoice.png","number":1,"items":[{"name":"Starter plan","quantity":1,"unit_cost":99}],"notes":"Thanks for your business!"}' \
> invoice.pdf
```

### Localization

It is possible to change the localization used to generate the invoice by supplying a locale in the `Accept-Language` header. The default locale is `en-US`.

```bash
curl https://invoice-generator.com \
  -H "Authorization: Bearer myApiKey" \
  -H "Accept-Language: fr-FR" \
  -d from="Nikolaus Ltd" \
  -d to="Acme Corp." \
  -d logo="https://example.com/img/logo-invoice.png" \
  -d number=1 \
  -d currency=eur \
  -d date="Feb 9, 2015" \
  -d due_date="Feb 16, 2015" \
  -d "items[0][name]"="Starter plan monthly" \
  -d "items[0][quantity]"=1 \
  -d "items[0][unit_cost]"=99 \
> invoice.pdf
```

#### Supported Languages

We currently have translations available in English, French, German, Spanish, and Thai.

### Custom Fields

```bash
curl https://invoice-generator.com \
  -H "Authorization: Bearer myApiKey" \
  -d from="Nikolaus Ltd" \
  -d to="My Customer" \
  -d ship_to="Shipping Address" \
  -d logo="https://example.com/img/logo-invoice.png" \
  -d number=1 \
  -d date="Feb 9, 2015" \
  -d "custom_fields[0][name]"="My Custom Field" \
  -d "custom_fields[0][value]"="Some Value" \
  -d "items[0][name]"="Starter Plan Monthly" \
  -d "items[0][quantity]"=1 \
  -d "items[0][unit_cost]"=99 \
> invoice.custom_fields.pdf
```

### Theme

Invoice appearance can be `classic` (default) or `slate`.

```bash
curl https://invoice-generator.com \
  -H "Authorization: Bearer myApiKey" \
  -d from="Nikolaus Ltd" \
  -d to="Acme, Corp." \
  -d theme=slate \
  -d number=1 \
  -d "items[0][name]"="Starter plan monthly" \
  -d "items[0][quantity]"=1 \
  -d "items[0][unit_cost]"=99 \
> invoice.slate.pdf
```

### E-invoice

Here's a simple cURL example for generating e-invoices in UBL XML:

```bash
curl https://invoice-generator.com/ubl \
  -H "Authorization: Bearer myApiKey" \
  -d from="Nikolaus Ltd%0AVAT ID: 1234" \
  -d to="Foster Moen%0AVAT ID: 4567" \
  -d logo="https://example.com/img/logo-invoice.png" \
  -d number=1 \
  -d date="Feb 9, 2015" \
  -d date="Mar 9, 2015" \
  -d payment_terms="NET 30" \
  -d "items[0][name]"="Starter Plan Monthly" \
  -d "items[0][quantity]"=1 \
  -d "items[0][unit_cost]"=99 \
  -d tax_title="VAT" \
  -d "fields[tax]"="%" \
  -d tax=8 \
  -d notes="Thanks for being an awesome customer\!" \
> invoice.xml
```

************

## API Reference

All document types use the same endpoint. Send `type` to choose the document. When `type` is omitted, the API creates an invoice.

```text
POST https://invoice-generator.com
```

### Shared Parameters

These fields apply to every document type. When a value is null or zero, the field will not be shown. The exception to this are the required fields `from`, `to`, `date`, and `items`.

|Parameter|Description|Default Value
|:--------|:----------|:------------
`theme`|Invoice appearance: `classic` or `slate`|classic
`logo`|URL of your logo|*null*
`from`|Your organization billing address and contact info|*null*
`to`|Entity being billed - multiple lines ok|*null*
`ship_to`|Shipping address - multiple lines ok|*null*
`number`|Document number|*null*
`currency`|ISO 4217 3-digit currency code|USD
`custom_fields`|Array of objects - see [Custom Field Parameters](#custom-field-parameters)|*[]*
`date`|Document date|current date
`items`|Array of objects - see [Line Item Parameters](#line-item-parameters)|`[]`
`fields`|Object - see [Subtotal Line Parameters](#subtotal-line-parameters)|`{"tax":"%","discounts":false,"shipping":false}`
`discounts`|Subtotal discounts - numbers only|0
`tax`|Tax - numbers only|0
`shipping`|Shipping - numbers only|0
`notes`|Notes - any extra information not included elsewhere|*null*
`terms`|Terms and conditions - all the details|*null*

#### Line Item Parameters

Line items are represented as an array of objects. Here's an example:

```json
{
  "items": [
    {
      "name": "Gizmo",
      "quantity": 10,
      "unit_cost": 99.99,
      "description": "The best gizmos there are around."
    },
    {
      "name": "Gizmo v2",
      "quantity": 5,
      "unit_cost": 199.99
    }
  ]
}
```

Optional line item fields `date`, `reference`, and `payment` may also be sent.

#### Subtotal Line Parameters

The `fields` object toggles the `discounts`, `tax`, and `shipping` subtotal lines. Each setting can have a value of `%`, `true`, or `false`. For example to add a percent tax rate and flat shipping to your invoice you would send this:

```json
{
  "fields": {
    "tax": "%",
    "discounts": false,
    "shipping": true
  },
  "tax": 7,
  "shipping": 15
}
```

#### Custom Field Parameters

Custom fields allow you to add additional fields to the invoice details in the top-right. Here's an example:

```json
{
  "custom_fields": [
    {
      "name": "Gizmo",
      "value": "PO-1234"
    },
    {
      "name": "Account Number",
      "value": "CUST-456"
    }
  ]
}
```

#### Template Parameters

These parameters control the titles of the fields on the template. If localization is used, the default values are translated to the specified language. Any template parameter given will override the localized default. Type-specific titles are listed on each create section below.

|Parameter|Default Value
|:--------|:------------
`header`|INVOICE
`to_title`|Bill To
`ship_to_title`|Ship To
`number_title`|#
`date_title`|Date
`payment_terms_title`|Payment Terms
`due_date_title`|Due Date
`purchase_order_title`|Purchase Order
`quantity_header`|Quantity
`item_header`|Item
`unit_cost_header`|Rate
`amount_header`|Amount
`subtotal_title`|Subtotal
`discounts_title`|Discounts
`tax_title`|Tax
`shipping_title`|Shipping
`total_title`|Total
`amount_paid_title`|Amount Paid
`balance_title`|Balance
`terms_title`|Terms
`notes_title`|Notes

### Create Invoice

```text
POST https://invoice-generator.com
```

`type` defaults to `invoice` and can be omitted. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`purchase_order`|Purchase order number|*null*
`payment_terms`|Payment terms summary (i.e. NET 30)|*null*
`due_date`|Invoice due date|*null*
`amount_paid`|Amount paid - numbers only|0
`payment_methods`|Array of payment method objects. UBL uses `{ "type": "url", "name": "...", "url": "..." }`. Not shown on the PDF.|`[]`

```json
{
  "type": "invoice",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "number": 1,
  "purchase_order": "PO-1234",
  "items": [{"name": "Starter plan", "quantity": 1, "unit_cost": 99}]
}
```

### Create Receipt

```text
POST https://invoice-generator.com
```

Set `type` to `receipt`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`purchase_order`|Referenced invoice number|*null*
`payment_terms`|Payment method summary|*null*
`due_date`|Date paid|*null*
`amount_paid`|Amount received - numbers only|0
`payment_methods`|Array of payment method objects. UBL uses `{ "type": "url", "name": "...", "url": "..." }`. Not shown on the PDF.|`[]`

|Parameter|Default Value
|:--------|:------------
`header`|RECEIPT
`number_title`|Receipt #
`to_title`|Received From
`due_date_title`|Date Paid
`amount_paid_title`|Amount Received
`payment_terms_title`|Payment Method
`purchase_order_title`|Referenced Invoice

```json
{
  "type": "receipt",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "number": 1,
  "amount_paid": 99,
  "items": [{"name": "Starter plan", "quantity": 1, "unit_cost": 99}]
}
```

### Create Credit Note

```text
POST https://invoice-generator.com
```

Set `type` to `credit_note`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`purchase_order`|Referenced invoice number|*null*
`amount_refunded`|Amount refunded - numbers only|0

This type does not accept `due_date`, `payment_terms`, `amount_paid`, or `payment_methods`.

|Parameter|Default Value
|:--------|:------------
`header`|CREDIT NOTE
`number_title`|#
`amount_paid_title`|Refunded
`purchase_order_title`|Referenced Invoice

```json
{
  "type": "credit_note",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "number": "CN-1",
  "purchase_order": "1",
  "amount_refunded": 25,
  "items": [{"name": "Unused time", "quantity": 1, "unit_cost": 25}]
}
```

### Create Quote

```text
POST https://invoice-generator.com
```

Set `type` to `quote`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`purchase_order`|Purchase order number|*null*
`payment_terms`|Payment terms summary|*null*

|Parameter|Default Value
|:--------|:------------
`header`|QUOTE
`number_title`|Quote #

```json
{
  "type": "quote",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "number": 1,
  "payment_terms": "Valid for 30 days",
  "items": [{"name": "Website redesign", "quantity": 1, "unit_cost": 2500}]
}
```

### Create Estimate

```text
POST https://invoice-generator.com
```

Set `type` to `estimate`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`purchase_order`|Purchase order number|*null*
`payment_terms`|Valid-until summary|*null*

|Parameter|Default Value
|:--------|:------------
`header`|ESTIMATE
`number_title`|Estimate #
`payment_terms_title`|Valid Until

```json
{
  "type": "estimate",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "number": 1,
  "payment_terms": "30 days",
  "items": [{"name": "Repair work", "quantity": 4, "unit_cost": 75}]
}
```

### Create Pro Forma Invoice

```text
POST https://invoice-generator.com
```

Set `type` to `proforma_invoice`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`purchase_order`|Purchase order number|*null*
`payment_terms`|Payment terms summary|*null*

|Parameter|Default Value
|:--------|:------------
`header`|PROFORMA INVOICE
`number_title`|Proforma #

```json
{
  "type": "proforma_invoice",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "number": 1,
  "items": [{"name": "Deposit", "quantity": 1, "unit_cost": 500}]
}
```

### Create Purchase Order

```text
POST https://invoice-generator.com
```

Set `type` to `purchase_order`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`payment_terms`|Payment terms summary|*null*
`due_date`|Required-by date|*null*

This type does not accept a `purchase_order` value field.

|Parameter|Default Value
|:--------|:------------
`header`|PURCHASE ORDER
`number_title`|Purchase Order #
`due_date_title`|Required By

```json
{
  "type": "purchase_order",
  "from": "Acme, Corp.",
  "to": "Nikolaus Ltd",
  "number": 1,
  "due_date": "Mar 1, 2015",
  "items": [{"name": "Office chairs", "quantity": 4, "unit_cost": 120}]
}
```

### Create Statement

```text
POST https://invoice-generator.com
```

Set `type` to `statement`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`purchase_order`|Purchase order number|*null*
`payment_terms`|Period start|*null*
`due_date`|Period end|*null*
`amount_paid`|Opening balance - numbers only|0
`payment_methods`|Array of payment method objects. Not shown on the PDF.|`[]`

Line items should include `date`, `reference`, and `payment` where relevant.

|Parameter|Default Value
|:--------|:------------
`header`|STATEMENT
`number_title`|Statement #
`to_title`|Statement To
`payment_terms_title`|Period Start
`due_date_title`|Period End
`amount_paid_title`|Opening Balance
`subtotal_title`|Total Charges
`item_header`|Description
`amount_header`|Balance
`date_header`|Date
`reference_header`|Reference
`charges_header`|Charges
`payments_header`|Payments
`payments_title`|Total Payments

```json
{
  "type": "statement",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "number": 1,
  "payment_terms": "Jan 1, 2015",
  "due_date": "Jan 31, 2015",
  "items": [
    {"name": "Invoice 12", "date": "Jan 8, 2015", "reference": "12", "unit_cost": 99, "quantity": 1, "payment": 0}
  ]
}
```

### Create Timesheet

```text
POST https://invoice-generator.com
```

Set `type` to `timesheet`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`purchase_order`|Purchase order number|*null*
`payment_terms`|Period start|*null*
`due_date`|Period end|*null*
`amount_paid`|Amount paid - numbers only|0
`payment_methods`|Array of payment method objects. Not shown on the PDF.|`[]`

Line items typically use `date` and treat `quantity` as hours.

|Parameter|Default Value
|:--------|:------------
`header`|TIMESHEET
`number_title`|Timesheet #
`to_title`|Timesheet To
`payment_terms_title`|Period Start
`due_date_title`|Period End
`quantity_header`|Hours
`item_header`|Description
`subtotal_title`|Total Hours
`date_header`|Date

```json
{
  "type": "timesheet",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "number": 1,
  "items": [
    {"name": "Development", "date": "Jan 8, 2015", "quantity": 6, "unit_cost": 85}
  ]
}
```

### Create Work Order

```text
POST https://invoice-generator.com
```

Set `type` to `work_order`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`ship_to`|Job site address - multiple lines ok|*null*
`payment_terms`|Technician|*null*
`due_date`|Scheduled date|*null*

This type does not accept a `purchase_order` value field.

|Parameter|Default Value
|:--------|:------------
`header`|WORK ORDER
`number_title`|Work Order #
`ship_to_title`|Job Site
`payment_terms_title`|Technician
`due_date_title`|Scheduled Date
`terms_title`|Authorization

```json
{
  "type": "work_order",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "ship_to": "123 Job Site Rd\nAustin, TX",
  "number": 1,
  "payment_terms": "Alex Rivera",
  "due_date": "Mar 1, 2015",
  "items": [{"name": "HVAC repair", "quantity": 2, "unit_cost": 95}],
  "notes": "This work order authorizes the listed work. It is not an invoice."
}
```

### Create Packing Slip

```text
POST https://invoice-generator.com
```

Set `type` to `packing_slip`. Uses [Shared Parameters](#shared-parameters) plus:

|Parameter|Description|Default Value
|:--------|:----------|:------------
`purchase_order`|Related invoice number|*null*

This type does not accept `due_date`, `payment_terms`, `amount_paid`, `payment_methods`, tax, discounts, or shipping. Line items use `name`, `description`, and `quantity` only (`unit_cost` is ignored).

|Parameter|Default Value
|:--------|:------------
`header`|PACKING SLIP
`number_title`|Packing Slip #
`purchase_order_title`|Invoice #

```json
{
  "type": "packing_slip",
  "from": "Nikolaus Ltd",
  "to": "Acme, Corp.",
  "ship_to": "Warehouse 4\nAustin, TX",
  "number": 1,
  "purchase_order": "INV-88",
  "items": [{"name": "Office chairs", "quantity": 4}]
}
```

### Create E-invoice

```text
POST https://invoice-generator.com/ubl
```

Uses the same parameters as the matching PDF create section. UBL is supported for `invoice`, `receipt` (Invoice XML), and `credit_note` only. Other types return an error.