invoices

Create an invoice preview

Changed on Nov 5, 2026

This endpoint is used for generating invoice preview.

post/invoices/preview

Request

Base URL
https://api.getlago.com/api/v1
Auth
HTTP bearer
TypeScript
https://skmtc.dev/getlago/apis/lago-api-documentation/docs/invoices/preview/post.ts
A function with typed inputs. Its response is checked against the schema.

Request body

plan_codestring

The code of the plan. It serves as a unique identifier associated with a particular plan. The code is typically used for internal or system-level identification purposes, like assigning a subscription, for instance.

subscription_atstring date-time

The anniversary date and time of the initial subscription. This date serves as the basis for billing subscriptions with anniversary billing time. The anniversary_date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).

billing_time'calendar' | 'anniversary'

The billing time for the subscription, which can be set as either anniversary or calendar. If not explicitly provided, it will default to calendar. The billing time determines the timing of recurring billing cycles for the subscription. By specifying anniversary, the billing cycle will be based on the specific date the subscription started (billed fully), while calendar sets the billing cycle at the first day of the week/month/year (billed with proration).

billing_entity_codestring

The code of the billing entity to which will be associated a customer if the external_id is not provided. If billing_entity_code is not provided, default billing_entity of organization will be used.

Example request

{
  "customer": {
    "address_line1": "5230 Penfield Ave",
    "city": "Woodland Hills",
    "country": "US",
    "external_id": "hooli_1234",
    "integration_customers": [
      {
        "integration_type": "anrok",
        "integration_code": "anrok1"
      }
    ],
    "name": "Gavin Belson",
    "currency": "USD",
    "shipping_address": {
      "address_line1": "5230 Penfield Ave",
      "city": "Woodland Hills",
      "country": "US",
      "state": "CA",
      "zipcode": "91364"
    },
    "state": "CA",
    "zipcode": "91364",
    "tax_identification_number": "EU123456789",
    "timezone": "America/Los_Angeles"
  },
  "plan_code": "startup",
  "subscription_at": "2022-08-08T00:00:00Z",
  "billing_time": "anniversary",
  "coupons": [
    {
      "name": "Startup Deal",
      "code": "startup_deal",
      "coupon_type": "fixed_amount",
      "amount_cents": 5000,
      "amount_currency": "USD",
      "frequency": "once",
      "frequency_duration": 6
    }
  ],
  "subscriptions": {
    "external_ids": [
      "441edbe3-9136-4688-a763-e57b6f1dca82"
    ],
    "plan_code": "new_code",
    "terminated_at": "2022-08-08T00:00:00Z"
  },
  "billing_entity_code": "acme_corp"
}

Response

Invoice preview created

Example response

{
  "invoice": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "billing_entity_code": "acme_corp",
    "sequential_id": 2,
    "number": "LAG-1234-001-002",
    "purchase_order_number": "PO-123",
    "issuing_date": "2022-04-30",
    "payment_dispute_lost_at": "2022-09-14T16:35:31Z",
    "payment_due_date": "2022-04-30",
    "payment_overdue": true,
    "net_payment_term": 30,
    "invoice_type": "subscription",
    "status": "finalized",
    "payment_status": "succeeded",
    "currency": "USD",
    "fees_amount_cents": 100,
    "coupons_amount_cents": 10,
    "credit_notes_amount_cents": 10,
    "sub_total_excluding_taxes_amount_cents": 100,
    "taxes_amount_cents": 20,
    "sub_total_including_taxes_amount_cents": 120,
    "total_amount_cents": 100,
    "total_paid_amount_cents": 40,
    "total_offsetted_credit_note_amount_cents": 10,
    "total_due_amount_cents": 50,
    "version_number": 3,
    "file_url": "https://getlago.com/invoice/file",
    "xml_url": "https://getlago.com/invoice/xml",
    "web_url": "https://app.getlago.com/acme/customer/1a901a90-1a90-1a90-1a90-1a901a901a90/invoice/2b012b01-2b01-2b01-2b01-2b012b012b01/overview",
    "created_at": "2022-04-29T08:59:51Z",
    "updated_at": "2022-04-29T08:59:51Z",
    "voided_at": "2022-04-29T08:59:51Z",
    "customer": {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "sequential_id": 1,
      "slug": "LAG-1234-001",
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "billing_entity_code": "acme_corp",
      "address_line1": "5230 Penfield Ave",
      "applicable_timezone": "America/Los_Angeles",
      "city": "Woodland Hills",
      "country": "US",
      "currency": "USD",
      "email": "dinesh@piedpiper.example",
      "legal_name": "Coleman-Blair",
      "legal_number": "49-008-2965",
      "logo_url": "http://hooli.com/logo.png",
      "name": "Gavin Belson",
      "firstname": "Gavin",
      "lastname": "Belson",
      "account_type": "customer",
      "customer_type": "company",
      "phone": "1-171-883-3711 x245",
      "state": "CA",
      "tax_identification_number": "EU123456789",
      "timezone": "America/Los_Angeles",
      "url": "http://hooli.com",
      "zipcode": "91364",
      "net_payment_term": 30,
      "external_salesforce_id": "0015p00001JQx1QAAT",
      "created_at": "2022-04-29T08:59:51Z",
      "updated_at": "2022-04-29T08:59:51Z",
      "finalize_zero_amount_invoice": "inherit",
      "billing_configuration": {
        "invoice_grace_period": 3,
        "subscription_invoice_issuing_date_anchor": "next_period_start",
        "subscription_invoice_issuing_date_adjustment": "keep_anchor",
        "payment_provider": "stripe",
        "payment_provider_code": "stripe-eu-1",
        "provider_customer_id": "cus_12345",
        "sync": true,
        "sync_with_provider": true,
        "document_locale": "fr",
        "provider_payment_methods": [
          "card",
          "sepa_debit",
          "us_bank_account",
          "bacs_debit",
          "link",
          "boleto",
          "crypto",
          "customer_balance"
        ]
      },
      "shipping_address": {
        "address_line1": "5230 Penfield Ave",
        "city": "Woodland Hills",
        "country": "US",
        "state": "CA",
        "zipcode": "91364"
      },
      "metadata": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "key": "Purchase Order",
          "value": "123456789",
          "display_in_invoice": true,
          "created_at": "2022-04-29T08:59:51Z"
        }
      ],
      "integration_customers": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "type": "netsuite",
          "integration_code": "netsuite-eu-1",
          "code": "netsuite-eu-1",
          "is_default": true,
          "category": "accounting",
          "external_customer_id": "cus_12345",
          "sync_with_provider": true,
          "subsidiary_id": "2",
          "targeted_object": "contacts",
          "email": "dinesh@piedpiper.example"
        }
      ]
    },
    "metadata": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "key": "digital_ref_id",
        "value": "INV-0123456-98765",
        "created_at": "2022-04-29T08:59:51Z"
      }
    ],
    "applied_taxes": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_tax_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "tax_name": "TVA",
        "tax_code": "french_standard_vat",
        "tax_rate": 20,
        "tax_description": "French standard VAT",
        "amount_cents": 2000,
        "amount_currency": "USD",
        "created_at": "2022-09-14T16:35:31Z"
      }
    ],
    "applied_invoice_custom_sections": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "code": "eu_bank_details",
        "details": "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143",
        "display_name": "Bank Details:",
        "created_at": "2023-07-06T14:35:58Z"
      }
    ],
    "applied_usage_thresholds": [
      {
        "lifetime_usage_amount_cents": 2000,
        "created_at": "2025-03-31T12:31:44Z",
        "usage_threshold": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "threshold_display_name": "Threshold 1",
          "amount_cents": 10000,
          "recurring": true,
          "created_at": "2023-06-27T19:43:42Z",
          "updated_at": "2023-06-27T19:43:42Z"
        }
      }
    ],
    "billing_periods": [
      {
        "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_subscription_id": "external_id",
        "lago_plan_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "subscription_from_datetime": "2022-04-29T08:59:51Z",
        "subscription_to_datetime": "2022-05-29T08:59:51Z",
        "charges_from_datetime": "2022-04-29T08:59:51Z",
        "charges_to_datetime": "2022-05-29T08:59:51Z",
        "fixed_charges_from_datetime": "2022-04-29T08:59:51Z",
        "fixed_charges_to_datetime": "2022-05-29T08:59:51Z",
        "invoicing_reason": "subscription_starting"
      }
    ],
    "credits": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "amount_cents": 1200,
        "amount_currency": "USD",
        "item": {
          "lago_item_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "type": "coupon",
          "code": "startup_deal",
          "name": "Startup Deal",
          "description": "I am a coupon description"
        },
        "invoice": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "payment_status": "succeeded"
        }
      }
    ],
    "fees": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_charge_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_charge_filter_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_fixed_charge_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_true_up_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_true_up_parent_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_original_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_customer_id": "external_id",
        "external_subscription_id": "external_id",
        "amount_cents": 100,
        "precise_amount": "1.0001",
        "precise_total_amount": "1.0212",
        "amount_currency": "USD",
        "taxes_amount_cents": 20,
        "taxes_precise_amount": "0.20123",
        "taxes_rate": 20,
        "units": "0.32",
        "precise_unit_amount": "312.5",
        "total_aggregated_units": "0.32",
        "total_amount_cents": 120,
        "total_amount_currency": "USD",
        "events_count": 23,
        "pay_in_advance": true,
        "invoiceable": true,
        "from_date": "2022-04-29T08:59:51Z",
        "to_date": "2022-05-29T08:59:51Z",
        "payment_status": "pending",
        "created_at": "2022-08-24T14:58:59Z",
        "succeeded_at": "2022-08-24T14:58:59Z",
        "failed_at": "2022-08-24T14:58:59Z",
        "refunded_at": "2022-08-24T14:58:59Z",
        "event_transaction_id": "transaction_1234567890",
        "description": "Fee description",
        "precise_coupons_amount_cents": "0.0",
        "sub_total_excluding_taxes_amount_cents": 100,
        "sub_total_excluding_taxes_precise_amount_cents": "100.0",
        "amount_details": {
          "plan_amount_cents": 10000,
          "graduated_ranges": [
            {
              "units": "10.0",
              "to_value": 10,
              "flat_unit_amount": "1.0",
              "per_unit_amount": "1.0",
              "per_unit_total_amount": "10.0",
              "total_with_flat_amount": "11.0"
            }
          ],
          "graduated_percentage_ranges": [
            {
              "units": "10.0",
              "to_value": 10,
              "flat_unit_amount": "1.0",
              "rate": "1.0",
              "per_unit_total_amount": "10.0",
              "total_with_flat_amount": "11.0"
            }
          ],
          "free_units": "10.0",
          "paid_units": "40.0",
          "per_package_size": 1000,
          "per_package_unit_amount": "0.5",
          "per_unit_total_amount": "10.0",
          "units": "20.0",
          "free_events": 10,
          "rate": "1.0",
          "paid_events": 20,
          "fixed_fee_unit_amount": "1.0",
          "fixed_fee_total_amount": "20.0",
          "min_max_adjustment_total_amount": "20.0",
          "per_unit_amount": "0.5",
          "flat_unit_amount": "10.0"
        },
        "item": {
          "type": "subscription",
          "code": "startup",
          "name": "Startup",
          "description": "Startup",
          "invoice_display_name": "Setup Fee (SF1)",
          "filter_invoice_display_name": "AWS eu-east-1",
          "lago_item_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "item_type": "Subscription"
        },
        "applied_taxes": [
          {
            "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "lago_tax_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "tax_name": "TVA",
            "tax_code": "french_standard_vat",
            "tax_rate": 20,
            "tax_description": "French standard VAT",
            "amount_cents": 2000,
            "amount_currency": "USD",
            "created_at": "2022-09-14T16:35:31Z"
          }
        ],
        "pricing_unit_details": {
          "lago_pricing_unit_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "pricing_unit_code": "credits",
          "short_name": "CR",
          "amount_cents": 200,
          "precise_amount_cents": "200.0",
          "unit_amount_cents": 100,
          "precise_unit_amount": "100.0",
          "conversion_rate": "0.5"
        },
        "presentation_breakdowns": [
          {
            "units": "9.0"
          }
        ]
      }
    ],
    "subscriptions": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "billing_entity_code": "default",
        "billing_time": "anniversary",
        "name": "Repository A",
        "plan_code": "premium",
        "plan_amount_cents": 10000,
        "plan_amount_currency": "USD",
        "status": "active",
        "created_at": "2022-08-08T00:00:00Z",
        "canceled_at": "2022-09-14T16:35:31Z",
        "started_at": "2022-08-08T00:00:00Z",
        "ending_at": "2022-10-08T00:00:00Z",
        "subscription_at": "2022-08-08T00:00:00Z",
        "terminated_at": "2022-09-14T16:35:31Z",
        "downgrade_plan_date": "2022-04-30",
        "trial_ended_at": "2022-08-08T00:00:00Z",
        "current_billing_period_started_at": "2022-08-08T00:00:00Z",
        "current_billing_period_ending_at": "2022-09-08T00:00:00Z",
        "on_termination_credit_note": "credit",
        "on_termination_invoice": "generate",
        "applied_invoice_custom_sections": [
          {
            "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "created_at": "2023-07-06T14:35:58Z",
            "invoice_custom_section_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "invoice_custom_section": {
              "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
              "name": "EU Bank Details",
              "code": "eu_bank_details",
              "description": "This section contains the bank details for EU customers.",
              "details": "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143",
              "display_name": "Bank Details:",
              "applied_to_organization": true,
              "organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
              "created_at": "2023-07-06T14:35:58Z"
            }
          }
        ],
        "payment_method": {
          "payment_method_type": "provider",
          "payment_method_id": "1a901a90-1a90-1a90-1a90-1a901a901a90"
        },
        "consolidate_invoice": true,
        "cancellation_reason": "payment_failed",
        "activated_at": "2022-08-08T00:00:00Z",
        "activation_rules": [
          {
            "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "type": "payment",
            "timeout_hours": 48,
            "status": "pending",
            "expires_at": "2022-08-10T00:00:00Z",
            "created_at": "2022-08-08T00:00:00Z",
            "updated_at": "2022-08-08T00:00:00Z"
          }
        ],
        "purchase_order_number": "PO-123"
      }
    ],
    "error_details": [
      {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "error_code": "tax_error",
        "details": {
          "tax_error": "taxDateTooFarInFuture"
        }
      }
    ]
  }
}

Changes

Nov 5, 2026b216574b9612 Revision changes
- info
  added the optional property ///// to the response with the status
Nov 3, 20265d26657495a3 Revision changes
- breaking
  the response property ///////// became nullable for the status
- breaking
  the response property ///////// became nullable for the status
- breaking
  the response property ///////// became nullable for the status
- breaking
  the response property ///////// became nullable for the status
- breaking
  the response property //////////// became nullable for the status
- breaking
  the response property //////////// became nullable for the status
- breaking
  the response property //////////// became nullable for the status
- breaking
  the response property //////////// became nullable for the status
- breaking
  the response property ////////// became nullable for the status
- breaking
  the response property //// became nullable for the status
- warning
  added the new SYP enum value to the ///////// response property for the response status
- warning
  added the new SYP enum value to the //////////// response property for the response status
- warning
  added the new SYP enum value to the /////////// response property for the response status
- warning
  added the new SYP enum value to the //// response property for the response status
- warning
  added the new SYP enum value to the //// response property for the response status
- warning
  added the new SYP enum value to the ////////// response property for the response status
- warning
  added the new SYP enum value to the //// response property for the response status
- warning
  added the new SYP enum value to the //// response property for the response status
- warning
  added the new TND enum value to the ///////// response property for the response status
- warning
  added the new TND enum value to the //////////// response property for the response status
- warning
  added the new TND enum value to the /////////// response property for the response status
- warning
  added the new TND enum value to the //// response property for the response status
- warning
  added the new TND enum value to the //// response property for the response status
- warning
  added the new TND enum value to the ////////// response property for the response status
- warning
  added the new TND enum value to the //// response property for the response status
- warning
  added the new TND enum value to the //// response property for the response status
- warning
  added the new advance_charges enum value to the ///////// response property for the response status
- warning
  added the new avalara enum value to the ////////// response property for the response status
- warning
  added the new cashfree enum value to the //////////// response property for the response status
- warning
  added the new deleted enum value to the ///////// response property for the response status
- warning
  added the new flutterwave enum value to the //////////// response property for the response status
- warning
  added the new manual enum value to the //// response property for the response status
- warning
  added the new moneyhash enum value to the //////////// response property for the response status
- warning
  added the new undefined enum value to the //////////// response property for the response status
- info
  added the new optional request property //
- info
  added the new optional request property /
- info
  added the new SYP enum value to the request property //
- info
  added the new SYP enum value to the request property /
- info
  added the new TND enum value to the request property //
- info
  added the new TND enum value to the request property /
- info
  added the new avalara enum value to the request property ///
- info
  added the new hubspot enum value to the request property ///
- info
  added the new salesforce enum value to the request property ///
- info
  added the new xero enum value to the request property ///
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  the response property ///////// became required for the status
- info
  the response property ///////// became required for the status
- info
  the response property ///////// became required for the status
- info
  the response property ///////// became required for the status
- info
  the response property ///////// became required for the status
- info
  the response property ///////// became required for the status
- info
  the response property ///////// became required for the status
- info
  the response property ///////// became required for the status
- info
  the response property ///////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property /////////// became required for the status
- info
  the response property ///// became required for the status
- info
  the response property ///// became required for the status
- info
  the response property ///// became required for the status
- info
  the response property ///// became required for the status
- info
  the response property ///// became required for the status
- info
  the response property //// became required for the status
- info
  the response property //// became required for the status
- info
  the response property ////// became required for the status
- info
  the response property //// became required for the status
- info
  the response property //// became required for the status
- info
  the response property //// became required for the status
- info
  the response property //// became required for the status
- info
  the response property //// became required for the status
- info
  added the required property ///////// to the response with the status
- info
  added the required property ///////// to the response with the status
- info
  added the required property ///////// to the response with the status
- info
  added the required property ///////// to the response with the status
- info
  added the required property ///////// to the response with the status
- info
  added the required property ///////// to the response with the status
- info
  added the required property ///////// to the response with the status
- info
  added the required property /////////// to the response with the status
- info
  added the required property ////////// to the response with the status
- info
  added the required property ////////// to the response with the status
- info
  added the required property ////////// to the response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property //// to the response with the status

Operation history