invoices

Void an invoice

Changed on Nov 5, 2026

This endpoint is used for voiding an invoice. • When no body parameters are provided, the invoice can be voided only if it is in a finalized status and its payment status is NOT succeeded. • When generate_credit_note is provided (optionally with refund_amount and/or credit_amount), this validation is bypassed: the invoice is forcibly voided and a credit note is generated. If the specified refund/credit amounts do not cover the full invoice total, the remainder is issued on a second credit note that is created and immediately voided.

post/invoices/{lago_id}/void

Request

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

Path parameters

lago_idstring uuid required

Example:1a901a90-1a90-1a90-1a90-1a901a901a90

Unique identifier assigned to the invoice within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system.

Request body

generate_credit_noteboolean

Set to true to force voiding the invoice and generate a credit note.

refund_amountinteger

Portion of the invoice amount (in cents) to be refunded to the customer in the generated credit note.

credit_amountinteger

Portion of the invoice amount (in cents) to be credited to the customer's balance in the generated credit note.

Example request

{
  "generate_credit_note": true,
  "refund_amount": 2000,
  "credit_amount": 1150
}

Response

Invoice voided

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 non-success response with the status
- 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