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

# Invoices

> How invoices are generated, paid, and managed.

## Overview

Every payment in StartMyVPN is backed by an **Invoice**. Invoices are created when a customer orders a plan or renews a service.

## Invoice states

| Status      | Description                                     |
| ----------- | ----------------------------------------------- |
| `pending`   | Invoice created, payment not yet received       |
| `paid`      | Payment confirmed; service activated/renewed    |
| `cancelled` | Invoice voided (e.g. customer chose not to pay) |
| `refunded`  | Payment was refunded                            |

## Invoice fields

| Field      | Description                                        |
| ---------- | -------------------------------------------------- |
| UUID       | Unique identifier used in URLs and API             |
| User       | The customer this invoice is for                   |
| Service    | The subscription being billed                      |
| Plan Cycle | The billing cycle (determines amount and duration) |
| Amount     | Total charged                                      |
| Currency   | Currency code (e.g. USD)                           |
| Gateway    | Which payment gateway was used                     |
| Promo      | Applied promo code (if any)                        |
| Discount   | Discount amount applied                            |
| Due Date   | When payment is expected                           |
| Paid At    | Timestamp of confirmed payment                     |

## Payment flow

1. Invoice is created in `pending` state
2. Customer is directed to payment gateway
3. Payment gateway processes the payment
4. Webhook notification arrives at StartMyVPN
5. Invoice status changes to `paid`
6. Service is activated or expiry date extended
7. Receipt email sent to customer

## Getting a payment URL

Customers can retrieve payment links for pending invoices:

* **Web**: `/invoice/{invoice}`
* **API**: `GET /v1/invoices/{invoice}/payment-url`

## Admin view

From **Admin → Invoices** you can:

* View all invoices with filters (status, gateway, date range)
* View individual invoice details
* Manually mark an invoice as paid (for manual/bank transfer payments)
* Record a refund

## Refunds

Recording a refund in StartMyVPN:

1. Open the invoice in **Admin → Invoices → \[Invoice]**
2. Click **Refund**
3. Enter the refund amount and reason
4. The refund is recorded, and the service may be suspended depending on settings

<Note>
  StartMyVPN records refunds for tracking purposes, but does not automatically process the refund via the payment gateway. You must issue the actual refund through Stripe, PayPal, or your crypto exchange manually.
</Note>