> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/premium-addons/invoice.md).

# Invoice

## <mark style="color:blue;">Overview</mark>

The **Invoice** addon lets your staff create PayPal invoices directly from Discord, share payment links or QR codes, and track payment status without leaving the server. It supports optional partial payments, fee handling, and webhook-driven status updates.

***

## <mark style="color:blue;">Table of Contents</mark>

1. **Features**
2. **Installation**
3. **How It Works**
4. **Commands**
5. **Webhooks and Logs**

***

## <mark style="color:blue;">Features</mark>

### <mark style="color:yellow;">Invoice Creation</mark>

* <mark style="color:red;">**Create PayPal invoices from Discord:**</mark> Use a slash command to generate invoices with item, price, and customer details
* <mark style="color:red;">**Pay link and QR code:**</mark> Share a direct PayPal pay link and optional QR code
* <mark style="color:red;">**Fee handling:**</mark> Automatically add a percentage fee to invoice totals
* <mark style="color:red;">**Optional partial payments:**</mark> Allow partial payments with an enforced minimum

***

### <mark style="color:yellow;">Status Tracking</mark>

* <mark style="color:red;">**Live status sync:**</mark> Refresh invoice status from PayPal on demand
* <mark style="color:red;">**Paid/partial/ cancelled states:**</mark> Track payment progress and close out invoices automatically
* <mark style="color:red;">**Webhook updates:**</mark> Auto-update invoice status when PayPal sends events

***

### <mark style="color:yellow;">Logging and Visibility</mark>

* <mark style="color:red;">**Dedicated logs channel:**</mark> Log invoice events in a configured Discord channel
* <mark style="color:red;">**Audit-friendly embeds:**</mark> Consistent log entries for created, paid, cancelled, and refunded invoices

***

## <mark style="color:blue;">Installation</mark>

{% hint style="warning" %}
**This is a premium addon!** You must purchase this addon separately and have a valid license.
{% endhint %}

1. Download the Invoice addon files from your purchase
2. Extract all files into the `plugins/` folder of your Athena Bot installation
3. Restart your bot to load the addon
4. Configure the addon using the `invoice.json5` file in your `configuration/` folder

***

## <mark style="color:blue;">How It Works</mark>

### <mark style="color:yellow;">1. Configure PayPal</mark>

Add your PayPal REST API client ID and secret, then choose sandbox or live mode. A PayPal **Business** account is required to create live API credentials. Optional: enable webhooks for automatic status updates.

### <mark style="color:yellow;">2. Create an Invoice</mark>

Use `/invoice create` to generate a PayPal invoice. The bot posts an embed with buttons for:

* Pay link (opens PayPal)
* QR code (for mobile payments)
* Resync (manual status refresh)
* Cancel (close the invoice)

### <mark style="color:yellow;">3. Track Status</mark>

Invoices are stored and can be viewed with `/invoice view`. Status changes are synced via PayPal API or webhooks.

***

## <mark style="color:blue;">Commands</mark>

### <mark style="color:yellow;">Staff Commands</mark>

**/invoice create**

* Create a new invoice
* **Options:** `customer` (user), `price` (1-5000), `item` (text), `email` (optional)

**/invoice view**

* View a previously created invoice
* **Options:** `id` (invoice ID)

**/invoice cancel**

* Cancel an existing invoice
* **Options:** `id` (invoice ID)

***

## <mark style="color:blue;">Webhooks and Logs</mark>

### <mark style="color:yellow;">PayPal Webhooks</mark>

If you enable webhooks, configure PayPal to send events to:

```
http://<host_ip>:<web_api_port>/api/paypal
```

Recommended events:

* `INVOICING.INVOICE.CREATED`
* `INVOICING.INVOICE.PAID`
* `INVOICING.INVOICE.PARTIALLY_PAID`
* `INVOICING.INVOICE.CANCELLED`
* `INVOICING.INVOICE.REFUNDED`

### <mark style="color:yellow;">Discord Logs</mark>

When enabled, the addon logs invoice activity in the `paypal_invoice_logs` channel.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.iynxdev.com/premium-addons/invoice.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.