> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# Taxes

Paygent supports **percentage** and **fixed-amount** taxes applied automatically when invoices are generated. Define tax rules once under Settings, attach them to orders, and every billing run calculates tax lines on the invoice subtotal.

---

## Create a tax

**Settings → Taxes** → **Create Tax**

| Field           | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| **Name**        | Display name on invoices (e.g. "GST", "VAT", "Sales Tax")   |
| **Description** | Optional internal notes                                     |
| **Type**        | `percentage` or `fixed`                                     |
| **Value**       | Rate or amount (e.g. `18` for 18%, or `5.00` for \$5 fixed) |
| **Active**      | Inactive taxes cannot be selected on new orders             |

### Percentage tax

Applied to the invoice **subtotal** (all line items before tax):

```
tax_amount = subtotal × (value / 100)
total      = subtotal + tax_amount
```

Example: 18% GST on $1,000 subtotal → $180 tax → \$1,180 total.

### Fixed tax

A flat amount added once per invoice:

```
total = subtotal + value
```

Example: \$5 processing fee on every invoice.

---

## Attach taxes to an order

Taxes are selected when creating or editing an order:

1. **Orders → Create Order** → Step 2 **Order details**
2. Under **Taxes**, select one or more active tax rules
3. Save and activate the order

You can also set **customer tax defaults** on the customer record — applicable taxes may pre-fill when the customer is selected.

> **Info**
>
> Multiple taxes on one order are supported. Each tax generates a separate line on the invoice with name, type, rate, and computed amount.

---

## How taxes appear on invoices

When the billing job generates an invoice:

1. Line items are summed → **subtotal**
2. Each attached tax is fetched and calculated
3. **Tax lines** are appended with `taxName`, `taxType`, `taxValue`, and amount
4. **Total** = subtotal + sum of tax amounts

Tax lines appear on the PDF and in the invoice editor. Unknown or inactive tax IDs on an order are skipped with a logged warning — the invoice still generates without that tax.

---

## Edit taxes on unpaid invoices

Open an invoice → **Edit Invoice**:

* Adjust tax lines manually if needed
* Update customer GSTIN / tax ID, billing address, or place of supply
* Modify line items — subtotal changes recalculate tax on regeneration

> **Warning**
>
> **Paid invoices are locked.** Verify tax lines before marking an invoice as paid. Paid invoices cannot be edited.

---

## Taxes with credits and wallets

Taxes apply to the **USD invoice subtotal**, including:

* Platform fees and seat fees
* Activity/outcome usage charges
* External cost line items
* Postpaid wallet accruals (converted via conversion rate)

Credit wallet debits happen at usage time; taxes apply when the invoice is generated for monetary line items.

---

## Example: Indian GST setup

1. **Settings → Taxes** → create "GST 18%" — type percentage, value `18`
2. Customer record: billing address in India, GSTIN filled
3. Order: select GST 18% on Step 2
4. Invoice generates: subtotal + 18% GST line
5. Send PDF to customer or mark paid to release prepaid credits

---

## API and orders

When creating orders via API, pass `taxIds` as an array of tax document IDs. The billing service validates tax IDs belong to your organization.

See [Orders API](/api-reference/orders-api) for order creation fields.

---

## Checklist

* ✓ Tax rules created and marked active
* ✓ Taxes attached to order (or customer defaults configured)
* ✓ Customer billing address and tax IDs complete
* ✓ Order activated
* ✓ Invoice shows expected tax lines before sending to customer

**Related:** [Orders & Invoicing](/documentation/introduction/orders-and-invoicing) · [Orders API](/api-reference/orders-api)