credit_notes

List all credit notes

Changed on Nov 3, 2026

This endpoint lists all existing credit notes.

get/credit_notes

Request

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

Query parameters

pageinteger

Example:1

Page number. Defaults to 1. A value that is not a positive integer, such as 0, returns the first page.

per_pageinteger

Example:20

Number of records per page. Defaults to 100. The maximum is 200, unless another maximum is configured for your organization. A value above the maximum returns a 422 error with value_is_out_of_range on per_page. A value that is not a positive integer, such as 0, returns the default number of records.

external_customer_idstring

Example:5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba

Unique identifier assigned to the customer in your application.

issuing_date_fromstring date

Example:2022-07-08

Filter credit notes starting from a specific date.

issuing_date_tostring date

Example:2022-08-09

Filter credit notes up to a specific date.

search_termstring

Example:Jane

Search credit notes by id, number, customer name, customer external_id or customer email.

currencystring

Example:EUR

Filter credit notes by currency. Possible values ISO 4217 currency codes.

Filter credit notes by reasons. Possible values are product_unsatisfactory, order_change, order_cancellation, fraudulent_charge, duplicated_charge or other.

credit_status'available' | 'consumed' | 'voided'

Filter credit notes by credit status. Possible values are available, consumed or voided.

refund_status'pending' | 'succeeded' | 'failed'

Filter credit notes by refund status. Possible values are pending, succeeded or failed.

invoice_numberstring

Example:INV-001-002

Filter credit notes by their related invoice number.

purchase_order_numberstring

Example:PO-123

Filter by the invoice purchase order number. The match is exact but case-insensitive.

amount_frominteger

Example:9000

Filter credit notes of at least a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.

amount_tointeger

Example:100000

Filter credit notes up to a specific amount. This parameter must be defined in cents to ensure consistent handling for all currency types.

types[]string[]

Filter credit notes by the kind of amount they carry. credit matches credit notes with a credited amount, refund those with a refunded amount and offset those with an amount deducted from the invoice balance. A credit note can match several types.

[
  "credit",
  "refund"
]

self_billedboolean

Example:true

Filter credit notes belonging to a self billed invoice. Possible values are true or false.

billing_entity_codes[]string[]

Filter credit notes by billing entity codes.

[
  "billing_entity_code_1",
  "billing_entity_code_2"
]

Response

Credit notes

Example response

{
  "credit_notes": [
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "billing_entity_code": "acme_corp",
      "sequential_id": 2,
      "number": "LAG-1234-CN2",
      "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "invoice_number": "LAG-1234",
      "purchase_order_number": "PO-123",
      "issuing_date": "2022-12-06",
      "credit_status": "available",
      "refund_status": "pending",
      "reason": "other",
      "description": "Free text",
      "currency": "USD",
      "total_amount_cents": 120,
      "precise_total_amount_cents": "120.0001",
      "taxes_amount_cents": 20,
      "precise_taxes_amount_cents": "20.0001",
      "taxes_rate": 20,
      "sub_total_excluding_taxes_amount_cents": 100,
      "balance_amount_cents": 100,
      "credit_amount_cents": 100,
      "coupons_adjustment_amount_cents": 20,
      "created_at": "2022-09-14T16:35:31Z",
      "updated_at": "2022-09-14T16:35:31Z",
      "file_url": "https://getlago.com/credit_note/file",
      "xml_url": "https://getlago.com/credit_note/xml",
      "items": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "amount_cents": 100,
          "precise_amount_cents": "100.0001",
          "amount_currency": "USD",
          "fee": {
            "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"
              }
            ]
          }
        }
      ],
      "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"
        }
      ],
      "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": {
        "external_id": "ext-123",
        "synced_at": "2024-01-15",
        "source": null
      },
      "error_details": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "error_code": "tax_error"
        }
      ]
    }
  ],
  "meta": {
    "current_page": 2,
    "next_page": 3,
    "prev_page": 1,
    "total_pages": 4,
    "total_count": 70
  }
}

Changes

Nov 3, 20265d26657495a3 Revision changes
- breaking
  the response property ///// became nullable for the status
- breaking
  the // response's property type changed from object to no type for status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with 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 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
- info
  added the new optional query request parameter purchase_order_number
- info
  added the new optional query request parameter types[]
- info
  added the non-success response with the status
- info
  added the optional property ///// to the response with the status
- info
  added subschema #2 to the // response property allOf list for the response 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

Operation history