Preview an invoice

curl --request POST \ --url https://api.getlago.com/api/v1/invoices/preview \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "customer": { "address_line1": "5230 Penfield Ave", "address_line2": null, "city": "Woodland Hills", "country": "US", "external_id": "hooli_1234", "integration_customers": [ { "integration_type": "anrok", "integration_code": "anrok1" } ], "name": "Gavin Belson", "currency": "EUR", "shipping_address": { "address_line1": "5230 Penfield Ave", "address_line2": null, "city": "Woodland Hills", "country": "US", "state": "CA", "zipcode": "91364" }, "state": "CA", "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", "percentage_rate": "<string>", "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" }'

{ "invoice": { "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "billing_entity_code": "acme_corp", "sequential_id": 2, "number": "LAG-1234-001-002", "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": "EUR", "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, "prepaid_credit_amount_cents": 0, "progressive_billing_credit_amount_cents": 0, "total_amount_cents": 100, "version_number": 3, "self_billed": false, "file_url": "https://getlago.com/invoice/file", "created_at": "2022-04-29T08:59:51Z", "updated_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", "address_line2": null, "applicable_timezone": "America/Los_Angeles", "city": "Woodland Hills", "country": "US", "currency": "USD", "email": "dinesh@piedpiper.test", "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, "created_at": "2022-04-29T08:59:51Z", "updated_at": "2022-04-29T08:59:51Z", "finalize_zero_amount_invoice": "inherit", "skip_invoice_custom_sections": false, "billing_configuration": { "invoice_grace_period": 3, "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", "address_line2": null, "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", "external_customer_id": "cus_12345", "sync_with_provider": true, "subsidiary_id": "2", "targeted_object": "contacts", "email": "dinesh@piedpiper.test" } ] }, "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", "invoicing_reason": "subscription_starting" } ], "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", "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "fees_amount_cents": 20000 } ], "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" } } ], "credits": [ { "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "amount_cents": 1200, "amount_currency": "EUR", "before_taxes": false, "item": { "lago_item_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "type": "coupon", "code": "startup_deal", "name": "Startup Deal" }, "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_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_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": "EUR", "taxes_amount_cents": 20, "taxes_precise_amount": "0.20123", "taxes_rate": 20, "units": "0.32", "precise_unit_amount": "312.5", "total_amount_cents": 120, "total_amount_currency": "EUR", "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", "amount_details": { "plan_amount_cents": 10000, "graduated_ranges": [ { "units": "10.0", "from_value": 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", "from_value": 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" }, "self_billed": false, "item": { "type": "subscription", "code": "startup", "name": "Startup", "description": "Startup", "invoice_display_name": "Setup Fee (SF1)", "filter_invoice_display_name": "AWS eu-east-1", "filters": {}, "lago_item_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "item_type": "Subscription", "grouped_by": {} }, "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", "lago_fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90" } ], "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" } } ], "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_time": "anniversary", "name": "Repository A", "plan_code": "premium", "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", "previous_plan_code": null, "next_plan_code": null, "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" } ], "error_details": [ { "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90", "error_code": "tax_error", "details": { "tax_error": "taxDateTooFarInFuture" } } ] } }

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Invoice preview payload

customer

object

required

Show child attributes

plan_code

string

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.

Example:

"startup"

subscription_at

string<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).

Example:

"2022-08-08T00:00:00Z"

billing_time

enum<string>

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).

Available options:

calendar,

anniversary

Example:

"anniversary"

coupons

object[]

Show child attributes

subscriptions

object

Show child attributes

billing_entity_code

string

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:

"acme_corp"

Response

Invoice preview created

invoice

object

required

Show child attributes

API Reference

Authorizations

Body

Response