Pricing Templates
Log in Sign up
Integrations / Stripe / ...

POST /v1/invoices/create_preview

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

Servers

Request headers

Name Type Required Description
Content-Type String Yes The media type of the request body.

Default value: "application/x-www-form-urlencoded"

Request body fields

Name Type Required Description
discounts No

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.
subscription_details Object No

The subscription creation or modification params to apply as a preview. Cannot be used with schedule or schedule_details fields.
subscription_details.cancel_now Boolean No
subscription_details.proration_date Integer No
subscription_details.start_date Integer No
subscription_details.default_tax_rates No
subscription_details.items[] Array No
subscription_details.items[].id String No
subscription_details.items[].discounts No
subscription_details.items[].price String No
subscription_details.items[].clear_usage Boolean No
subscription_details.items[].deleted Boolean No
subscription_details.items[].tax_rates No
subscription_details.items[].billing_thresholds No
subscription_details.items[].price_data Object No
subscription_details.items[].price_data.unit_amount Integer No
subscription_details.items[].price_data.unit_amount_decimal String No
subscription_details.items[].price_data.product String Yes
subscription_details.items[].price_data.recurring Object Yes
subscription_details.items[].price_data.recurring.interval String Yes

Possible values:

  • "month"
  • "day"
  • "week"
  • "year"
subscription_details.items[].price_data.recurring.interval_count Integer No
subscription_details.items[].price_data.tax_behavior String No

Possible values:

  • "inclusive"
  • "unspecified"
  • "exclusive"
subscription_details.items[].price_data.currency String Yes
subscription_details.items[].quantity Integer No
subscription_details.items[].metadata No
subscription_details.cancel_at_period_end Boolean No
subscription_details.resume_at String No

Possible values:

  • "now"
subscription_details.cancel_at No
subscription_details.billing_cycle_anchor No
subscription_details.proration_behavior String No

Possible values:

  • "create_prorations"
  • "always_invoice"
  • "none"
subscription_details.trial_end No
subscription_details.billing_mode Object No
subscription_details.billing_mode.type String Yes

Possible values:

  • "flexible"
  • "classic"
subscription String No

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.
customer_details Object No

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.
customer_details.tax Object No
customer_details.tax.ip_address No
customer_details.shipping No
customer_details.tax_ids[] Array No
customer_details.tax_ids[].type String Yes

Possible values:

  • "br_cnpj"
  • "ng_tin"
  • "my_sst"
  • "bj_ifu"
  • "ca_gst_hst"
  • "tz_vat"
  • "eu_oss_vat"
  • "aw_tin"
  • "ad_nrt"
  • "my_frp"
  • "bo_tin"
  • "kg_tin"
  • "au_arn"
  • "mx_rfc"
  • "pe_ruc"
  • "hk_br"
  • "nz_gst"
  • "sg_uen"
  • "zw_tin"
  • "me_pib"
  • "br_cpf"
  • "au_abn"
  • "ge_vat"
  • "kr_brn"
  • "cd_nif"
  • "eu_vat"
  • "bg_uic"
  • "eg_tin"
  • "al_tin"
  • "sv_nit"
  • "il_vat"
  • "ro_tin"
  • "sg_gst"
  • "jp_rn"
  • "np_pan"
  • "vn_tin"
  • "sa_vat"
  • "ba_tin"
  • "ao_tin"
  • "az_tin"
  • "ca_qst"
  • "ca_pst_mb"
  • "tw_vat"
  • "mk_vat"
  • "bb_tin"
  • "li_uid"
  • "om_vat"
  • "za_vat"
  • "md_vat"
  • "ec_ruc"
  • "tr_tin"
  • "uz_tin"
  • "si_tin"
  • "ma_vat"
  • "bf_ifu"
  • "hr_oib"
  • "bd_bin"
  • "co_nit"
  • "ru_kpp"
  • "no_voec"
  • "ke_pin"
  • "us_ein"
  • "ug_tin"
  • "do_rcn"
  • "th_vat"
  • "mr_nif"
  • "ch_vat"
  • "ar_cuit"
  • "jp_cn"
  • "cn_tin"
  • "rs_pib"
  • "ca_bn"
  • "de_stn"
  • "es_cif"
  • "ua_vat"
  • "ca_pst_bc"
  • "li_vat"
  • "ae_trn"
  • "ph_tin"
  • "id_npwp"
  • "jp_trn"
  • "is_vat"
  • "gb_vat"
  • "hu_tin"
  • "sr_fin"
  • "gn_nif"
  • "zm_tin"
  • "cm_niu"
  • "no_vat"
  • "bs_tin"
  • "ch_uid"
  • "la_tin"
  • "kz_bin"
  • "uz_vat"
  • "ca_pst_sk"
  • "by_tin"
  • "cv_nif"
  • "kh_tin"
  • "bh_vat"
  • "in_gst"
  • "my_itn"
  • "am_tin"
  • "cl_tin"
  • "uy_ruc"
  • "ve_rif"
  • "ru_inn"
  • "sn_ninea"
  • "et_tin"
  • "cr_tin"
  • "tj_tin"
customer_details.tax_ids[].value String Yes
customer_details.address No
customer_details.tax_exempt String No

Possible values:

  • ""
  • "reverse"
  • "exempt"
  • "none"
expand[] Array No

Specifies which fields in the response should be expanded.
automatic_tax Object No

Settings for automatic tax lookup for this invoice preview.
automatic_tax.enabled Boolean Yes
automatic_tax.liability Object No
automatic_tax.liability.account String No
automatic_tax.liability.type String Yes

Possible values:

  • "account"
  • "self"
invoice_items[] Array No

List of invoice items to add or update in the upcoming invoice preview (up to 250).
invoice_items[].discounts No
invoice_items[].price String No
invoice_items[].description String No
invoice_items[].tax_rates No
invoice_items[].tax_code No
invoice_items[].quantity Integer No
invoice_items[].metadata No
invoice_items[].currency String No
invoice_items[].unit_amount Integer No
invoice_items[].period Object No
invoice_items[].period.end Integer Yes
invoice_items[].period.start Integer Yes
invoice_items[].unit_amount_decimal String No
invoice_items[].amount Integer No
invoice_items[].discountable Boolean No
invoice_items[].price_data Object No
invoice_items[].price_data.unit_amount Integer No
invoice_items[].price_data.unit_amount_decimal String No
invoice_items[].price_data.product String Yes
invoice_items[].price_data.tax_behavior String No

Possible values:

  • "inclusive"
  • "unspecified"
  • "exclusive"
invoice_items[].price_data.currency String Yes
invoice_items[].tax_behavior String No

Possible values:

  • "inclusive"
  • "unspecified"
  • "exclusive"
invoice_items[].invoiceitem String No
schedule String No

The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields.
preview_mode String No

Customizes the types of values to include when calculating the invoice. Defaults to next if unspecified.

Possible values:

  • "recurring"
  • "next"
currency String No

The currency to preview this invoice in. Defaults to that of customer if not specified.
on_behalf_of No

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 documentation for details.
customer String No

The identifier of the customer whose upcoming invoice you'd like to retrieve. If automatic_tax is enabled then one of customer, customer_details, subscription, or schedule must be set.
schedule_details Object No

The schedule creation or modification params to apply as a preview. Cannot be used with subscription or subscription_ prefixed fields.
schedule_details.end_behavior String No

Possible values:

  • "cancel"
  • "release"
schedule_details.phases[] Array No
schedule_details.phases[].add_invoice_items[] Array No
schedule_details.phases[].add_invoice_items[].discounts[] Array No
schedule_details.phases[].add_invoice_items[].discounts[].promotion_code String No
schedule_details.phases[].add_invoice_items[].discounts[].coupon String No
schedule_details.phases[].add_invoice_items[].discounts[].discount String No
schedule_details.phases[].add_invoice_items[].price String No
schedule_details.phases[].add_invoice_items[].tax_rates No
schedule_details.phases[].add_invoice_items[].price_data Object No
schedule_details.phases[].add_invoice_items[].price_data.unit_amount Integer No
schedule_details.phases[].add_invoice_items[].price_data.unit_amount_decimal String No
schedule_details.phases[].add_invoice_items[].price_data.product String Yes
schedule_details.phases[].add_invoice_items[].price_data.tax_behavior String No

Possible values:

  • "inclusive"
  • "unspecified"
  • "exclusive"
schedule_details.phases[].add_invoice_items[].price_data.currency String Yes
schedule_details.phases[].add_invoice_items[].quantity Integer No
schedule_details.phases[].application_fee_percent Number No
schedule_details.phases[].discounts No
schedule_details.phases[].description No
schedule_details.phases[].automatic_tax Object No
schedule_details.phases[].automatic_tax.enabled Boolean Yes
schedule_details.phases[].automatic_tax.liability Object No
schedule_details.phases[].automatic_tax.liability.account String No
schedule_details.phases[].automatic_tax.liability.type String Yes

Possible values:

  • "account"
  • "self"
schedule_details.phases[].items[] Array Yes
schedule_details.phases[].items[].discounts No
schedule_details.phases[].items[].price String No
schedule_details.phases[].items[].tax_rates No
schedule_details.phases[].items[].billing_thresholds No
schedule_details.phases[].items[].price_data Object No
schedule_details.phases[].items[].price_data.unit_amount Integer No
schedule_details.phases[].items[].price_data.unit_amount_decimal String No
schedule_details.phases[].items[].price_data.product String Yes
schedule_details.phases[].items[].price_data.recurring Object Yes
schedule_details.phases[].items[].price_data.recurring.interval String Yes

Possible values:

  • "month"
  • "day"
  • "week"
  • "year"
schedule_details.phases[].items[].price_data.recurring.interval_count Integer No
schedule_details.phases[].items[].price_data.tax_behavior String No

Possible values:

  • "inclusive"
  • "unspecified"
  • "exclusive"
schedule_details.phases[].items[].price_data.currency String Yes
schedule_details.phases[].items[].quantity Integer No
schedule_details.phases[].items[].metadata Object No
schedule_details.phases[].metadata Object No
schedule_details.phases[].proration_behavior String No

Possible values:

  • "create_prorations"
  • "always_invoice"
  • "none"
schedule_details.phases[].collection_method String No

Possible values:

  • "send_invoice"
  • "charge_automatically"
schedule_details.phases[].on_behalf_of String No
schedule_details.phases[].default_payment_method String No
schedule_details.phases[].iterations Integer No
schedule_details.phases[].trial Boolean No
schedule_details.phases[].start_date No
schedule_details.phases[].default_tax_rates No
schedule_details.phases[].end_date No
schedule_details.phases[].billing_thresholds No
schedule_details.phases[].billing_cycle_anchor String No

Possible values:

  • "phase_start"
  • "automatic"
schedule_details.phases[].trial_end No
schedule_details.phases[].transfer_data Object No
schedule_details.phases[].transfer_data.destination String Yes
schedule_details.phases[].transfer_data.amount_percent Number No
schedule_details.phases[].invoice_settings Object No
schedule_details.phases[].invoice_settings.days_until_due Integer No
schedule_details.phases[].invoice_settings.account_tax_ids No
schedule_details.phases[].invoice_settings.issuer Object No
schedule_details.phases[].invoice_settings.issuer.account String No
schedule_details.phases[].invoice_settings.issuer.type String Yes

Possible values:

  • "account"
  • "self"
schedule_details.proration_behavior String No

Possible values:

  • "create_prorations"
  • "always_invoice"
  • "none"
schedule_details.billing_mode Object No
schedule_details.billing_mode.type String Yes

Possible values:

  • "flexible"
  • "classic"
issuer Object No

The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
issuer.account String No
issuer.type String Yes

Possible values:

  • "account"
  • "self"

How to start integrating

  1. Add HTTP Task to your workflow definition.
  2. Search for the API you want to integrate with and click on the name.
    • This loads the API reference documentation and prepares the Http request settings.
  3. Click Test request to test run your request to the API and see the API's response.
All third party trademarks (including logos and icons) are the property of their respective owners, which do not sponsor, authorize, or endorse this website.
Pricing Templates Integrations Blog Contact Us Help
© 2025 SimWorkflow
Terms of Service Privacy Policy