> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices

> Every invoices command in the Flexprice CLI, with flags, required fields and examples.

## create

Create one-off invoice

| Flag                      | Type    | Required | Description                                                                                                                                                                                                                                                                                        |
| ------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--amount_due`            | string  | yes      | amount\_due is the total amount that needs to be paid for this invoice                                                                                                                                                                                                                             |
| `--amount_paid`           | string  |          | amount\_paid is the amount that has been paid towards this invoice                                                                                                                                                                                                                                 |
| `--billing_period`        | string  |          | billing\_period is the period this invoice covers (e.g., "monthly", "yearly")                                                                                                                                                                                                                      |
| `--billing_reason`        | string  |          |                                                                                                                                                                                                                                                                                                    |
| `--currency`              | string  | yes      | currency is the three-letter ISO currency code (e.g., USD, EUR) for the invoice                                                                                                                                                                                                                    |
| `--customer_id`           | string  | yes      | customer\_id is the unique identifier of the customer this invoice belongs to                                                                                                                                                                                                                      |
| `--description`           | string  |          | description is an optional text description of the invoice                                                                                                                                                                                                                                         |
| `--due_date`              | string  |          | due\_date is the date by which payment is expected                                                                                                                                                                                                                                                 |
| `--force_sync_invoice`    | boolean |          | force\_sync\_invoice, when true, attempts to synchronously sync this invoice to Moyasar (if enabled) before returning, instead of relying solely on the async Kafka + Temporal vendor-sync pipeline. Only honored by CreateOneOffInvoice. Best-effort: sync failures do not fail invoice creation. |
| `--idempotency_key`       | string  |          | idempotency\_key is an optional key used to prevent duplicate invoice creation                                                                                                                                                                                                                     |
| `--invoice_number`        | string  |          | invoice\_number is an optional human-readable identifier for the invoice                                                                                                                                                                                                                           |
| `--invoice_pdf_url`       | string  |          | invoice\_pdf\_url is the URL where customers can download the PDF version of this invoice                                                                                                                                                                                                          |
| `--invoice_status`        | string  |          |                                                                                                                                                                                                                                                                                                    |
| `--invoice_type`          | string  |          |                                                                                                                                                                                                                                                                                                    |
| `--issue_date`            | string  |          | issue\_date overrides the user-facing date of the invoice. Defaults to created\_at if not provided.                                                                                                                                                                                                |
| `--payment_status`        | string  |          |                                                                                                                                                                                                                                                                                                    |
| `--period_end`            | string  |          | period\_end is the end date of the billing period                                                                                                                                                                                                                                                  |
| `--period_start`          | string  |          | period\_start is the start date of the billing period                                                                                                                                                                                                                                              |
| `--subscription_id`       | string  |          | subscription\_id is the optional unique identifier of the subscription associated with this invoice                                                                                                                                                                                                |
| `--subtotal`              | string  | yes      | subtotal is the amount before taxes and discounts are applied                                                                                                                                                                                                                                      |
| `--total`                 | string  | yes      | total is the total amount of the invoice including taxes and discounts                                                                                                                                                                                                                             |
| `--total_prepaid_applied` | string  |          | total\_prepaid\_applied is the total amount of prepaid applied to this invoice.                                                                                                                                                                                                                    |

<Note>
  These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.

  * `coupons` (array)
  * `invoice_coupons` (array)
  * `line_item_coupons` (array)
  * `line_items` (array)
  * `metadata` (object)
  * `prepared_tax_rates` (array)
  * `tax_rate_overrides` (array)
  * `tax_rates` (array)
</Note>

```sh theme={null}
flexprice invoices create --amount_due=<value> --currency=<value> --customer_id=<value> --subtotal=<value> --total=<value>
```

## customer-summary

Get customer invoice summary

```sh theme={null}
flexprice invoices customer-summary
```

## finalize

Finalize invoice

```sh theme={null}
flexprice invoices finalize
```

## list

Query invoices

| Flag                     | Type    | Required | Description                                                                                                                                                                        |
| ------------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--amount_due_gt`        | number  |          | amount\_due\_gt filters invoices with a total amount due greater than the specified value Useful for finding invoices above a certain threshold or identifying high-value invoices |
| `--amount_remaining_gt`  | number  |          | amount\_remaining\_gt filters invoices with an outstanding balance greater than the specified value Useful for finding invoices that still have significant unpaid amounts         |
| `--billing_reason`       | string  |          |                                                                                                                                                                                    |
| `--currency`             | string  |          | currency filters invoices by their currency (ISO 4217 code, e.g. "usd", "eur"). Matches on the invoices.currency column exactly.                                                   |
| `--customer_id`          | string  |          | customer\_id filters invoices for a specific customer using FlexPrice's internal customer ID This is the ID returned by FlexPrice when creating or retrieving customers            |
| `--end_time`             | string  |          |                                                                                                                                                                                    |
| `--expand`               | string  |          |                                                                                                                                                                                    |
| `--external_customer_id` | string  |          | external\_customer\_id filters invoices for a customer using your system's customer identifier This is the ID you provided when creating the customer in FlexPrice                 |
| `--invoice_type`         | string  |          |                                                                                                                                                                                    |
| `--limit`                | integer |          |                                                                                                                                                                                    |
| `--offset`               | integer |          |                                                                                                                                                                                    |
| `--order`                | string  |          |                                                                                                                                                                                    |
| `--period_end_gte`       | string  |          | period\_end\_gte filters invoices with period\_end >= value                                                                                                                        |
| `--period_end_lte`       | string  |          | period\_end\_lte filters invoices with period\_end \<= value                                                                                                                       |
| `--period_start_gte`     | string  |          | period\_start\_gte filters invoices with period\_start >= value                                                                                                                    |
| `--period_start_lte`     | string  |          | period\_start\_lte filters invoices with period\_start \<= value                                                                                                                   |
| `--skip_line_items`      | boolean |          | SkipLineItems if true, will not include line items in the response                                                                                                                 |
| `--start_time`           | string  |          |                                                                                                                                                                                    |
| `--status`               | string  |          |                                                                                                                                                                                    |
| `--subscription_id`      | string  |          | subscription\_id filters invoices generated for a specific subscription Only returns invoices that were created as part of the specified subscription's billing                    |

<Note>
  These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.

  * `filters` (array)
  * `invoice_ids` (array)
  * `invoice_status` (array)
  * `payment_status` (array)
  * `sort` (array)
  * `subscription_customer_id` (array)
</Note>

```sh theme={null}
flexprice invoices list
```

## payment-attempt

Attempt invoice payment

```sh theme={null}
flexprice invoices payment-attempt
```

## payment-status

Update invoice payment status

| Flag               | Type   | Required | Description                                     |
| ------------------ | ------ | -------- | ----------------------------------------------- |
| `--amount`         | string |          | amount is the optional payment amount to record |
| `--payment_status` | string | yes      |                                                 |

```sh theme={null}
flexprice invoices payment-status --payment_status=<value>
```

## pdf

Get invoice PDF

```sh theme={null}
flexprice invoices pdf
```

## preview

Get invoice preview

| Flag                             | Type    | Required | Description                                                                          |
| -------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------ |
| `--hide_zero_charges_line_items` | boolean |          | hide\_zero\_charges\_line\_items indicates whether to hide line items with zero cost |
| `--period_end`                   | string  |          | period\_end is the optional end date of the period to preview                        |
| `--period_start`                 | string  |          | period\_start is the optional start date of the period to preview                    |
| `--subscription_id`              | string  | yes      | subscription\_id is the unique identifier of the subscription to preview invoice for |

```sh theme={null}
flexprice invoices preview --subscription_id=<value>
```

## recalculate

Recalculate draft invoice (v2)

```sh theme={null}
flexprice invoices recalculate
```

## retrieve

Get invoice

```sh theme={null}
flexprice invoices retrieve
```

## trigger-comms-webhook

Trigger invoice communication webhook

```sh theme={null}
flexprice invoices trigger-comms-webhook
```

## update

Update invoice

| Flag                | Type    | Required | Description                                                                               |
| ------------------- | ------- | -------- | ----------------------------------------------------------------------------------------- |
| `--apply_discount`  | boolean |          | When true, recalculates discount from existing coupon associations (draft invoices only). |
| `--due_date`        | string  |          |                                                                                           |
| `--invoice_pdf_url` | string  |          | invoice\_pdf\_url is the URL where customers can download the PDF version of this invoice |

<Note>
  These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.

  * `metadata` (object)
</Note>

```sh theme={null}
flexprice invoices update
```

## void

Void invoice

```sh theme={null}
flexprice invoices void
```