# Source: https://getlago.com/docs/guide/invoicing/previews.md

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

# Preview an invoice

> With Lago, you can preview invoices even if the customer doesn't exist yet, for pending subscriptions, or for active subscriptions.

<Info>✨ This feature is only available via a premium licence. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

By using the `/invoices/preview` endpoint, you can generate a preview of an invoice for a potential purchase or to estimate the dry-run invoice of an active subscription.
This preview calculates the total invoice amount, itemizes each charge, and applies any relevant taxes or discounts.
By creating a preview, you can share the projected payment details without generating or finalizing an invoice.

Lago returns an invoice payload detailing all line items, applying any eligible discounts, and calculating the total amount.

## Simple invoice preview

To create a basic invoice preview for an existing customer, provide the appropriate customer `external_id` along with the relevant subscription or plan details.
Lago will then generate a preview invoice on-demand, prorating all line items based on the `billing_time` (calendar or anniversary).

```bash  theme={"dark"}
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/preview" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
        "external_id": "hooli_1234"
      },
      "plan_code": "premium",
      "billing_time": "calendar"
    }'
```

## Preview an invoice for a specific date

Additionally, you can request an invoice preview for a specific date by including the `subscription_at` field.
This instructs Lago to calculate and prorate all line items according to the date you specify.

```bash {13} theme={"dark"}
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/preview" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
        "external_id": "hooli_1234"
      },
      "plan_code": "premium",
      "billing_time": "calendar",
      "subscription_at": "2025-01-25"
    }'
```

## Preview an invoice for a pending subscription

You can preview an invoice for a subscription that has already been created but hasn't started yet (status: `pending`). This is useful when you've created a subscription with a future `subscription_at` date and want to estimate the upcoming charges.

This method supports **subscriptions with price overrides**, making it ideal when your plans use zero pricing with subscription-level overrides.

```bash  theme={"dark"}
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/invoices/preview" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "external_id": "hooli_1234"
    },
    "subscriptions": {
      "external_ids": [
        "subscription_external_id_1"
      ]
    }
  }'
```

## Preview for non-existing customers

You can generate an invoice preview for a customer who isn't yet registered in your system or created in Lago.
This is especially useful for showing estimated costs to potential customers evaluating your product. In this scenario, you won't pass a customer `external_id`; instead, provide all relevant customer information you wish to capture.

```bash {8-18} theme={"dark"}
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/preview" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
      "name": "Gavin Belson",
      "tax_identification_number": "1234567890",
      "customer_type": "company",
      "shipping_address": {
          "address_line1": "100 Hooli Street",
          "city": "San Francisco",
          "zipcode": "998828",
          "country": "US"
        }
      },
      "plan_code": "premium",
      "billing_time": "calendar",
      "subscription_at": "2025-01-25"
    }'
```

## Include taxes in invoice previews

If you have an external tax setup, you can include tax details in the invoice preview payload. Lago will then calculate and apply taxes accordingly.
If Lago is integrated with a tax provider (e.g., Anrok), you only need to pass the relevant integration data in the customer integration payload.

```bash {18-23} theme={"dark"}
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/preview" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
      "name": "Gavin Belson",
      "tax_identification_number": "1234567890",
      "customer_type": "company",
      "shipping_address": {
          "address_line1": "100 Hooli Street",
          "city": "San Francisco",
          "zipcode": "998828",
          "country": "US"
        },
        "integration_customers": [
          {
            "integration_type": "anrok",
            "integration_code": "anrok_prod"
          }
        ]
      },
      "plan_code": "premium",
      "billing_time": "calendar",
      "subscription_at": "2025-01-25"
    }'
```

## Include discounts in invoice previews

You can include discounts in an invoice preview through either of these methods:

1. **Apply an existing coupon or a prepaid credit to the customer:** When a coupon or credit is already associated with the customer, Lago automatically applies the discount to the invoice preview; or
2. **Provide coupon details in the request payload:** Pass your own coupon information directly in the invoice preview payload, and Lago will apply the discount accordingly.

```bash {22-30} theme={"dark"}
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/preview" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
      "name": "Gavin Belson",
      "tax_identification_number": "1234567890",
      "customer_type": "company",
      "shipping_address": {
          "address_line1": "100 Hooli Street",
          "city": "San Francisco",
          "zipcode": "998828",
          "country": "US"
        }
      },
      "plan_code": "premium",
      "billing_time": "calendar",
      "subscription_at": "2025-01-25",
      "coupons": [
        {
          "code": "discount_01",
          "name": "Discount 01",
          "coupon_type": "fixed_amount",
          "amount_cents": 1200,
          "amount_currency": "USD"
        }
      ]
    }'
```

## Dry-run invoices for active subscriptions

You can preview or estimate the total amount and all applicable fees for active subscriptions.
This returns the price that customers will be charged in the next billing period, including fees, taxes and any applicable discounts.

```bash {19-21} theme={"dark"}
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/preview" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
        "external_id": "customer_001",
        "name": "test 1",
        "shipping_address": {
            "address_line1": "77 rue du Chemin Vert",
            "city": "Rome",
            "zipcode": "75011",
            "country": "IT"
        },
        "tax_identification_number": "1234567890"
      },
      "subscriptions": {
          "external_ids": ["e372c4e4-99ec-41a4-a51b-7c165eb5cb88"]
      }
    }'
```

## Preview an invoice for subscription termination

You can preview an invoice associated with terminating a subscription by including the `terminated_at` field in the request payload.

```bash {19-22} theme={"dark"}
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/preview" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
        "external_id": "customer_001",
        "name": "test 1",
        "shipping_address": {
            "address_line1": "77 rue du Chemin Vert",
            "city": "Rome",
            "zipcode": "75011",
            "country": "IT"
        },
        "tax_identification_number": "1234567890"
      },
      "subscriptions": {
          "external_ids": ["e372c4e4-99ec-41a4-a51b-7c165eb5cb88"],
          "terminated_at": "2025-03-01T00:00:00Z"
      }
    }'
```

## Preview an invoice for upgrades and downgrades

To preview invoices generated by upgrading or downgrading an active subscription, include a new `plan_code` in the request payload:

```bash {19-22} theme={"dark"}
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/preview" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
        "external_id": "customer_001",
        "name": "test 1",
        "shipping_address": {
            "address_line1": "77 rue du Chemin Vert",
            "city": "Rome",
            "zipcode": "75011",
            "country": "IT"
        },
        "tax_identification_number": "1234567890"
      },
      "subscriptions": {
          "external_ids": ["e372c4e4-99ec-41a4-a51b-7c165eb5cb88"],
		      "plan_code": "new_plan",
      }
    }'
```