# Create a preview invoice

At any time, you can preview the upcoming invoice for a subscription or subscription schedule. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice.

You can also preview the effects of creating or updating a subscription or subscription schedule, including a preview of any prorations that will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the `subscription_details.proration_date` parameter when doing the actual subscription update.

The recommended way to get only the prorations being previewed on the invoice is to consider line items where `parent.subscription_item_details.proration` is `true`.

Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer’s discount.

Note: Currency conversion calculations use the latest exchange rates. Exchange rates may vary between the time of the preview and the time of the actual invoice creation. [Learn more](https://docs.stripe.com/currencies/conversions.md)

## Prerequisites

Before you can run the following code snippet, you need to call these APIs with the provided parameters to set up the prerequisite API object(s).

1. createCustomer
POST /v1/customers {"name":"Jenny Rosen","email":"jennyrosen@example.com"}

## Request

```curl
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "<<YOUR_SECRET_KEY>>" \
  -d customer={{CUSTOMER_ID}}
```

### Response

```json
{
  "id": "upcoming_in_1MtHbELkdIwHu7ixl4OzzPMv",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Stripe Docs",
  "account_tax_ids": null,
  "amount_due": 0,
  "amount_paid": 0,
  "amount_overpaid": 0,
  "amount_remaining": 0,
  "amount_shipping": 0,
  "application": null,
  "application_fee_amount": null,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "automatic_tax": {
    "enabled": false,
    "status": null
  },
  "billing_reason": "manual",
  "collection_method": "charge_automatically",
  "created": 1680644467,
  "currency": "usd",
  "custom_fields": null,
  "customer": "cus_NeZwdNtLEOXuvB",
  "customer_address": null,
  "customer_email": "jennyrosen@example.com",
  "customer_name": "Jenny Rosen",
  "customer_phone": null,
  "customer_shipping": null,
  "customer_tax_exempt": "none",
  "customer_tax_ids": [],
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discounts": [],
  "due_date": null,
  "ending_balance": null,
  "footer": null,
  "from_invoice": null,
  "hosted_invoice_url": null,
  "invoice_pdf": null,
  "last_finalization_error": null,
  "latest_revision": null,
  "lines": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines"
  },
  "livemode": false,
  "metadata": {},
  "next_payment_attempt": null,
  "number": null,
  "on_behalf_of": null,
  "parent": null,
  "payment_settings": {
    "default_mandate": null,
    "payment_method_options": null,
    "payment_method_types": null
  },
  "period_end": 1680644467,
  "period_start": 1680644467,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "receipt_number": null,
  "shipping_cost": null,
  "shipping_details": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "status": "draft",
  "status_transitions": {
    "finalized_at": null,
    "marked_uncollectible_at": null,
    "paid_at": null,
    "voided_at": null
  },
  "subtotal": 0,
  "subtotal_excluding_tax": 0,
  "test_clock": null,
  "total": 0,
  "total_discount_amounts": [],
  "total_excluding_tax": 0,
  "total_taxes": [],
  "webhooks_delivered_at": 1680644467
}
```

## Returns

Returns an invoice if valid customer information is provided. Raises [an error](https://docs.stripe.com/api/errors.md) otherwise.

## Parameters

- [`automatic_tax`](https://docs.stripe.com/api/invoices/create_preview.md?query=automatic_tax) (object, optional)
  Settings for automatic tax lookup for this invoice preview.

- `currency` (enum, optional)
  The currency to preview this invoice in. Defaults to that of `customer` if not specified.

- `customer` (string, optional)
  The identifier of the customer whose upcoming invoice you’re retrieving. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set.

- `customer_account` (string, optional)
  The identifier of the account representing the customer whose upcoming invoice you’re retrieving. If `automatic_tax` is enabled then one of `customer`, `customer_account`, `customer_details`, `subscription`, or `schedule` must be set.

- [`customer_details`](https://docs.stripe.com/api/invoices/create_preview.md?query=customer_details) (object, optional)
  Details about the customer you want to invoice or overrides for an existing customer. If `automatic_tax` is enabled then one of `customer`, `customer_details`, `subscription`, or `schedule` must be set.

- [`discounts`](https://docs.stripe.com/api/invoices/create_preview.md?query=discounts) (array of objects, optional)
  The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts.

- [`invoice_items`](https://docs.stripe.com/api/invoices/create_preview.md?query=invoice_items) (array of objects, optional)
  List of invoice items to add or update in the upcoming invoice preview (up to 250).

- [`issuer`](https://docs.stripe.com/api/invoices/create_preview.md?query=issuer) (object, optional)
  The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

- `on_behalf_of` (string, optional)
  The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the [Invoices with Connect](https://docs.stripe.com/billing/invoices/connect.md) documentation for details.

- `preview_mode` (enum, optional)
  Customizes the types of values to include when calculating the invoice. Defaults to `next` if unspecified.
Possible enum values:
  - `next`
    Will calculate the next invoice for the customer or subscription, factoring in all one-time and recurring items.

  - `recurring`
    Will calculate an invoice that is an estimate of the subscription’s long-term recurring bill. The invoice lines will only include recurring subscription items, taxes, and coupons with `duration=repeating` or `duration=forever`.

    To calculate a recurring estimate, you must provide at least one of `subscription` or `subscription_details.items`. Prorations, subscription cancellations, trials, and pauses are not supported with recurring estimates.

- `schedule` (string, optional)
  The identifier of the schedule whose upcoming invoice you’d like to retrieve. Cannot be used with subscription or subscription fields.

- [`schedule_details`](https://docs.stripe.com/api/invoices/create_preview.md?query=schedule_details) (object, optional)
  The schedule creation or modification params to apply as a preview. Cannot be used with `subscription` or `subscription_` prefixed fields.

- `subscription` (string, optional)
  The identifier of the subscription for which you’d like to retrieve the upcoming invoice. If not provided, but a `subscription_details.items` is provided, you will preview creating a subscription with those items. If neither `subscription` nor `subscription_details.items` is provided, you will retrieve the next upcoming invoice from among the customer’s subscriptions.

- [`subscription_details`](https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details) (object, optional)
  The subscription creation or modification params to apply as a preview. Cannot be used with `schedule` or `schedule_details` fields.