Skip to main content
GET
/
credit_notes
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request GET "$LAGO_URL/api/v1/credit_notes?per_page=2&page=1" \
  --header "Authorization: Bearer $API_KEY"

{
  "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",
      "issuing_date": "2022-12-06",
      "credit_status": "available",
      "refund_status": "pending",
      "reason": "other",
      "description": "Free text",
      "currency": "EUR",
      "total_amount_cents": 120,
      "taxes_amount_cents": 20,
      "taxes_rate": 20,
      "sub_total_excluding_taxes_amount_cents": 100,
      "balance_amount_cents": 100,
      "credit_amount_cents": 100,
      "refund_amount_cents": 0,
      "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",
      "items": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "amount_cents": 100,
          "amount_currency": "EUR",
          "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_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_aggregated_units": "0.32",
            "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"
            }
          }
        }
      ],
      "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_credit_note_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "base_amount_cents": 100
        }
      ],
      "self_billed": false,
      "error_details": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "error_code": "tax_error",
          "details": {}
        }
      ]
    }
  ],
  "meta": {
    "current_page": 2,
    "next_page": 3,
    "prev_page": 1,
    "total_pages": 4,
    "total_count": 70
  }
}
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request GET "$LAGO_URL/api/v1/credit_notes?per_page=2&page=1" \
  --header "Authorization: Bearer $API_KEY"

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
page
integer

Page number.

Example:

1

​
per_page
integer

Number of records per page.

Example:

20

​
external_customer_id
string

Unique identifier assigned to the customer in your application.

Example:

"5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"

​
issuing_date_from
string<date>

Filter credit notes starting from a specific date.

Example:

"2022-07-08"

​
issuing_date_to
string<date>

Filter credit notes up to a specific date.

Example:

"2022-08-09"

​
search_term
string

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

Example:

"Jane"

​
currency
string

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

Example:

"EUR"

​
reason
enum<string>

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

Available options:
product_unsatisfactory,
order_change,
order_cancellation,
fraudulent_charge,
duplicated_charge,
other
​
credit_status
enum<string>

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

Available options:
available,
consumed,
voided
​
refund_status
enum<string>

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

Available options:
pending,
succeeded,
failed
​
invoice_number
string

Filter credit notes by their related invoice number.

Example:

"INV-001-002"

​
amount_from
integer

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

Example:

9000

​
amount_to
integer

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

Example:

100000

​
self_billed
boolean

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

Example:

true

​
billing_entity_codes[]
string[]

Filter credit notes by billing entity codes.

Example:
[
  "billing_entity_code_1",
  "billing_entity_code_2"
]

Response

Credit notes

​
credit_notes
object[]
required
​
meta
object
required