lago-javascript-client
Version:
Lago JavaScript API Client
1,337 lines • 433 kB
TypeScript
/** @example "USD" */
export type Currency = "AED" | "AFN" | "ALL" | "AMD" | "ANG" | "AOA" | "ARS" | "AUD" | "AWG" | "AZN" | "BAM" | "BBD" | "BDT" | "BGN" | "BIF" | "BMD" | "BND" | "BOB" | "BRL" | "BSD" | "BWP" | "BYN" | "BZD" | "CAD" | "CDF" | "CHF" | "CLF" | "CLP" | "CNY" | "COP" | "CRC" | "CVE" | "CZK" | "DJF" | "DKK" | "DOP" | "DZD" | "EGP" | "ETB" | "EUR" | "FJD" | "FKP" | "GBP" | "GEL" | "GHS" | "GIP" | "GMD" | "GNF" | "GTQ" | "GYD" | "HKD" | "HNL" | "HRK" | "HTG" | "HUF" | "IDR" | "ILS" | "INR" | "ISK" | "JMD" | "JPY" | "KES" | "KGS" | "KHR" | "KMF" | "KRW" | "KYD" | "KZT" | "LAK" | "LBP" | "LKR" | "LRD" | "LSL" | "MAD" | "MDL" | "MGA" | "MKD" | "MMK" | "MNT" | "MOP" | "MRO" | "MUR" | "MVR" | "MWK" | "MXN" | "MYR" | "MZN" | "NAD" | "NGN" | "NIO" | "NOK" | "NPR" | "NZD" | "PAB" | "PEN" | "PGK" | "PHP" | "PKR" | "PLN" | "PYG" | "QAR" | "RON" | "RSD" | "RUB" | "RWF" | "SAR" | "SBD" | "SCR" | "SEK" | "SGD" | "SHP" | "SLL" | "SOS" | "SRD" | "STD" | "SZL" | "THB" | "TJS" | "TOP" | "TRY" | "TTD" | "TWD" | "TZS" | "UAH" | "UGX" | "USD" | "UYU" | "UZS" | "VND" | "VUV" | "WST" | "XAF" | "XCD" | "XOF" | "XPF" | "YER" | "ZAR" | "ZMW";
/** @example "US" */
export type Country = "AD" | "AE" | "AF" | "AG" | "AI" | "AL" | "AM" | "AO" | "AQ" | "AR" | "AS" | "AT" | "AU" | "AW" | "AX" | "AZ" | "BA" | "BB" | "BD" | "BE" | "BF" | "BG" | "BH" | "BI" | "BJ" | "BL" | "BM" | "BN" | "BO" | "BQ" | "BR" | "BS" | "BT" | "BV" | "BW" | "BY" | "BZ" | "CA" | "CC" | "CD" | "CF" | "CG" | "CH" | "CI" | "CK" | "CL" | "CM" | "CN" | "CO" | "CR" | "CU" | "CV" | "CW" | "CX" | "CY" | "CZ" | "DE" | "DJ" | "DK" | "DM" | "DO" | "DZ" | "EC" | "EE" | "EG" | "EH" | "ER" | "ES" | "ET" | "FI" | "FJ" | "FK" | "FM" | "FO" | "FR" | "GA" | "GB" | "GD" | "GE" | "GF" | "GG" | "GH" | "GI" | "GL" | "GM" | "GN" | "GP" | "GQ" | "GR" | "GS" | "GT" | "GU" | "GW" | "GY" | "HK" | "HM" | "HN" | "HR" | "HT" | "HU" | "ID" | "IE" | "IL" | "IM" | "IN" | "IO" | "IQ" | "IR" | "IS" | "IT" | "JE" | "JM" | "JO" | "JP" | "KE" | "KG" | "KH" | "KI" | "KM" | "KN" | "KP" | "KR" | "KW" | "KY" | "KZ" | "LA" | "LB" | "LC" | "LI" | "LK" | "LR" | "LS" | "LT" | "LU" | "LV" | "LY" | "MA" | "MC" | "MD" | "ME" | "MF" | "MG" | "MH" | "MK" | "ML" | "MM" | "MN" | "MO" | "MP" | "MQ" | "MR" | "MS" | "MT" | "MU" | "MV" | "MW" | "MX" | "MY" | "MZ" | "NA" | "NC" | "NE" | "NF" | "NG" | "NI" | "NL" | "NO" | "NP" | "NR" | "NU" | "NZ" | "OM" | "PA" | "PE" | "PF" | "PG" | "PH" | "PK" | "PL" | "PM" | "PN" | "PR" | "PS" | "PT" | "PW" | "PY" | "QA" | "RE" | "RO" | "RS" | "RU" | "RW" | "SA" | "SB" | "SC" | "SD" | "SE" | "SG" | "SH" | "SI" | "SJ" | "SK" | "SL" | "SM" | "SN" | "SO" | "SR" | "SS" | "ST" | "SV" | "SX" | "SY" | "SZ" | "TC" | "TD" | "TF" | "TG" | "TH" | "TJ" | "TK" | "TL" | "TM" | "TN" | "TO" | "TR" | "TT" | "TV" | "TW" | "TZ" | "UA" | "UG" | "UM" | "US" | "UY" | "UZ" | "VA" | "VC" | "VE" | "VG" | "VI" | "VN" | "VU" | "WF" | "WS" | "YE" | "YT" | "ZA" | "ZM" | "ZW";
/** @example "America/Los_Angeles" */
export type Timezone = "UTC" | "Africa/Algiers" | "Africa/Cairo" | "Africa/Casablanca" | "Africa/Harare" | "Africa/Johannesburg" | "Africa/Monrovia" | "Africa/Nairobi" | "America/Argentina/Buenos_Aires" | "America/Bogota" | "America/Caracas" | "America/Chicago" | "America/Chihuahua" | "America/Denver" | "America/Guatemala" | "America/Guyana" | "America/Halifax" | "America/Indiana/Indianapolis" | "America/Juneau" | "America/La_Paz" | "America/Lima" | "America/Los_Angeles" | "America/Mazatlan" | "America/Mexico_City" | "America/Monterrey" | "America/Montevideo" | "America/New_York" | "America/Nuuk" | "America/Phoenix" | "America/Puerto_Rico" | "America/Regina" | "America/Santiago" | "America/Sao_Paulo" | "America/St_Johns" | "America/Tijuana" | "Asia/Almaty" | "Asia/Baghdad" | "Asia/Baku" | "Asia/Bangkok" | "Asia/Chongqing" | "Asia/Colombo" | "Asia/Dhaka" | "Asia/Hong_Kong" | "Asia/Irkutsk" | "Asia/Jakarta" | "Asia/Jerusalem" | "Asia/Kabul" | "Asia/Kamchatka" | "Asia/Karachi" | "Asia/Kathmandu" | "Asia/Kolkata" | "Asia/Krasnoyarsk" | "Asia/Kuala_Lumpur" | "Asia/Kuwait" | "Asia/Magadan" | "Asia/Muscat" | "Asia/Novosibirsk" | "Asia/Riyadh" | "Asia/Seoul" | "Asia/Shanghai" | "Asia/Singapore" | "Asia/Srednekolymsk" | "Asia/Taipei" | "Asia/Tashkent" | "Asia/Tbilisi" | "Asia/Tehran" | "Asia/Tokyo" | "Asia/Ulaanbaatar" | "Asia/Urumqi" | "Asia/Vladivostok" | "Asia/Yakutsk" | "Asia/Yangon" | "Asia/Yekaterinburg" | "Asia/Yerevan" | "Atlantic/Azores" | "Atlantic/Cape_Verde" | "Atlantic/South_Georgia" | "Australia/Adelaide" | "Australia/Brisbane" | "Australia/Darwin" | "Australia/Hobart" | "Australia/Melbourne" | "Australia/Perth" | "Australia/Sydney" | "Europe/Amsterdam" | "Europe/Athens" | "Europe/Belgrade" | "Europe/Berlin" | "Europe/Bratislava" | "Europe/Brussels" | "Europe/Bucharest" | "Europe/Budapest" | "Europe/Copenhagen" | "Europe/Dublin" | "Europe/Helsinki" | "Europe/Istanbul" | "Europe/Kaliningrad" | "Europe/Kyiv" | "Europe/Lisbon" | "Europe/Ljubljana" | "Europe/London" | "Europe/Madrid" | "Europe/Minsk" | "Europe/Moscow" | "Europe/Paris" | "Europe/Prague" | "Europe/Riga" | "Europe/Rome" | "Europe/Samara" | "Europe/Sarajevo" | "Europe/Skopje" | "Europe/Sofia" | "Europe/Stockholm" | "Europe/Tallinn" | "Europe/Vienna" | "Europe/Vilnius" | "Europe/Volgograd" | "Europe/Warsaw" | "Europe/Zagreb" | "Europe/Zurich" | "GMT+12" | "Pacific/Apia" | "Pacific/Auckland" | "Pacific/Chatham" | "Pacific/Fakaofo" | "Pacific/Fiji" | "Pacific/Guadalcanal" | "Pacific/Guam" | "Pacific/Honolulu" | "Pacific/Majuro" | "Pacific/Midway" | "Pacific/Noumea" | "Pacific/Pago_Pago" | "Pacific/Port_Moresby" | "Pacific/Tongatapu";
/** Billing entity object */
export interface BillingEntityObject {
/**
* A unique identifier for the billing entity in the Lago application
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_id: string;
/**
* The unique code of the billing entity
* @example "acme_corp"
*/
code: string;
/**
* The name of the billing entity
* @example "Acme Corp"
*/
name: string;
/**
* The default currency of the billing entity
* @example "USD"
*/
default_currency: Currency;
/**
* The language of the documents generated for this billing entity
* @example "en"
*/
document_locale: string;
/**
* The type of document numbering for this billing entity:
* - `per_customer`: document numbers are unique per customer
* - `per_billing_entity`: document numbers are unique per billing entity
* @example "per_customer"
*/
document_numbering: "per_customer" | "per_billing_entity";
/**
* The prefix used in document numbers for this billing entity
* @example "ABC-123"
*/
document_number_prefix?: string | null;
/**
* Whether to finalize invoices with zero amount for this billing entity
* @example true
*/
finalize_zero_amount_invoice: boolean;
/**
* The footer text to be displayed on invoices for this billing entity
* @example "Thank you for your business"
*/
invoice_footer?: string | null;
/**
* The grace period (in days) for invoice finalization
* @example 0
*/
invoice_grace_period: number;
/**
* Whether this billing entity is the default billing entity for the organization. Default billing entity will be used as fallback in services if no billing entity is specified when billing_entity is not provided. Default billing entity is the billing entity that will be used to generate invoices if no billing entity is specified when invoice is created. is the oldest active billing entity and this flag cannot be changed
* @example false
*/
is_default?: boolean;
/**
* The net payment term (in days) for this billing entity
* @example 0
*/
net_payment_term: number;
/**
* The first line of the billing address
* @example "5230 Penfield Ave"
*/
address_line1?: string | null;
/**
* The second line of the billing address
* @example "Suite 100"
*/
address_line2?: string | null;
/**
* The city of the billing address
* @example "Woodland Hills"
*/
city?: string | null;
/**
* The state of the billing address
* @example "CA"
*/
state?: string | null;
/** The country code of the billing address */
country?: Country | null;
/**
* The zipcode of the billing address
* @example "91364"
*/
zipcode?: string | null;
/**
* The email address of the billing entity
* @format email
* @example "billing@acme.com"
*/
email?: string | null;
/**
* The legal name of the billing entity
* @example "Acme Corporation"
*/
legal_name?: string | null;
/**
* The legal registration number of the billing entity
* @example "US123456789"
*/
legal_number?: string | null;
/**
* The tax identification number of the billing entity
* @example "EU123456789"
*/
tax_identification_number?: string | null;
/**
* The timezone of the billing entity
* @example "UTC"
*/
timezone: Timezone;
/** The email notification settings for this billing entity */
email_settings?: ("invoice.finalized" | "credit_note.created" | "payment_receipt.created")[];
/**
* Whether EU tax management is enabled for this billing entity
* @example false
*/
eu_tax_management?: boolean;
/**
* The URL of the billing entity's logo
* @format uri
* @example "https://getlago.com/logo.png"
*/
logo_url?: string | null;
/**
* The date and time when the billing entity was created
* @format date-time
* @example "2022-04-29T08:59:51Z"
*/
created_at: string;
/**
* The date and time when the billing entity was last updated
* @format date-time
* @example "2022-04-29T08:59:51Z"
*/
updated_at: string;
}
export interface ApiErrorUnauthorized {
/**
* @format int32
* @example 401
*/
status: number;
/** @example "Unauthorized" */
error: string;
}
export interface ApiErrorUnprocessableEntity {
/**
* @format int32
* @example 422
*/
status: number;
/** @example "Unprocessable entity" */
error: string;
/** @example "validation_errors" */
code: string;
error_details: object;
}
/** Billing entity create input */
export interface BillingEntityCreateInput {
billing_entity: {
/**
* The unique code of the billing entity
* @example "acme_corp"
*/
code: string;
/**
* The name of the billing entity
* @example "Acme Corp"
*/
name: string;
/**
* The default currency of the billing entity
* @example "USD"
*/
default_currency?: Currency;
/**
* The type of document numbering for this billing entity:
* - `per_customer`: document numbers are unique per customer
* - `per_billing_entity`: document numbers are unique per billing entity
*/
document_numbering?: "per_customer" | "per_billing_entity";
/**
* The prefix used in document numbers for this billing entity
* @example "ABC-123"
*/
document_number_prefix?: string | null;
/**
* Whether to finalize invoices with zero amount for this billing entity
* @example true
*/
finalize_zero_amount_invoice?: boolean;
billing_configuration?: {
/**
* The footer text to be displayed on invoices for this billing entity
* @example "Thank you for your business"
*/
invoice_footer?: string;
/**
* The language of the documents generated for this billing entity
* @example "en"
*/
document_locale?: string;
/**
* The grace period (in days) for invoice finalization
* @example 0
*/
invoice_grace_period?: number;
};
/**
* The net payment term (in days) for this billing entity
* @example 0
*/
net_payment_term?: number;
/**
* The first line of the billing address
* @example "5230 Penfield Ave"
*/
address_line1?: string | null;
/**
* The second line of the billing address
* @example "Suite 100"
*/
address_line2?: string | null;
/**
* The city of the billing address
* @example "Woodland Hills"
*/
city?: string | null;
/**
* The state of the billing address
* @example "CA"
*/
state?: string | null;
/** The country code of the billing address */
country?: Country | null;
/**
* The zipcode of the billing address
* @example "91364"
*/
zipcode?: string | null;
/**
* The email address of the billing entity
* @format email
* @example "billing@acme.com"
*/
email?: string | null;
/**
* The legal name of the billing entity
* @example "Acme Corporation"
*/
legal_name?: string | null;
/**
* The legal registration number of the billing entity
* @example "US123456789"
*/
legal_number?: string | null;
/**
* The tax identification number of the billing entity
* @example "EU123456789"
*/
tax_identification_number?: string | null;
/**
* The timezone of the billing entity
* @example "UTC"
*/
timezone?: Timezone;
/** The email notification settings for this billing entity */
email_settings?: ("invoice.finalized" | "credit_note.created")[];
/**
* Whether EU tax management is enabled for this billing entity
* @example false
*/
eu_tax_management?: boolean;
/**
* The base64 encoded logo image for the billing entity
* @format uri
* @example "data:image/png;base64,..."
*/
logo?: string | null;
};
}
export interface ApiErrorBadRequest {
/**
* @format int32
* @example 400
*/
status: number;
/** @example "Bad request" */
error: string;
}
export interface ApiErrorForbidden {
/**
* @format int32
* @example 403
*/
status: number;
/** @example "Forbidden" */
error: string;
/** @example "feature_unavailable" */
code: string;
}
export interface TaxObject {
/**
* Unique identifier of the tax, created by Lago.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_id: string;
/**
* Name of the tax.
* @example "TVA"
*/
name: string;
/**
* Unique code used to identify the tax associated with the API request.
* @example "french_standard_vat"
*/
code: string;
/**
* Internal description of the tax
* @example "French standard VAT"
*/
description?: string | null;
/**
* The percentage rate of the tax
* @example 20
*/
rate: number;
/**
* This field is deprecated and will be removed in a future version. When set to true, it applies the tax to the organization's default billing entity. To apply or remove a tax from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead.
* @deprecated
* @example true
*/
applied_to_organization: boolean;
/**
* Creation date of the tax.
* @format date-time
* @example "2023-07-06T14:35:58Z"
*/
created_at: string;
}
export interface InvoiceCustomSectionObject {
/**
* Unique identifier for the invoice custom section in the Lago application, generated by Lago to ensure record uniqueness within the system.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_id: string;
/**
* Name of the invoice custom section.
* @example "EU Bank Details"
*/
name: string;
/**
* Unique code identifying the invoice custom section for the API request.
* @example "eu_bank_details"
*/
code: string;
/**
* Internal description of the invoice custom section.
* @example "This section contains the bank details for EU customers."
*/
description?: string;
/**
* The value shown on the invoice PDF.
* @example "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143"
*/
details?: string;
/**
* The name of the invoice custom section displayed on the invoice.
* @example "Bank Details:"
*/
display_name?: string;
/**
* This field is deprecated and will be removed in a future version. When set to true, it applies the invoice custom section to the organization's default billing entity. To apply or remove an invoice custom section from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead.
* @deprecated
* @example true
*/
applied_to_organization?: boolean;
/**
* Unique identifier for the organization associated with the invoice custom section.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
organization_id?: string;
/**
* Creation date of the tax.
* @format date-time
* @example "2023-07-06T14:35:58Z"
*/
created_at?: string;
}
export type BillingEntityObjectExtended = BillingEntityObject & {
taxes?: TaxObject[];
selected_invoice_custom_sections?: InvoiceCustomSectionObject[];
};
export interface ApiErrorNotFound {
/**
* @format int32
* @example 404
*/
status: number;
/** @example "Not Found" */
error: string;
/** @example "object_not_found" */
code: string;
}
/**
* List of unique code used to identify the taxes.
* @example ["french_standard_vat"]
*/
export type TaxCodes = string[];
/** Billing entity update input */
export interface BillingEntityUpdateInput {
/**
* The name of the billing entity
* @example "Acme Corp"
*/
name?: string;
/**
* The default currency of the billing entity
* @example "USD"
*/
default_currency?: Currency;
/**
* The type of document numbering for this billing entity:
* - `per_customer`: document numbers are unique per customer
* - `per_billing_entity`: document numbers are unique per billing entity
*/
document_numbering?: "per_customer" | "per_billing_entity";
/**
* The prefix used in document numbers for this billing entity
* @example "ABC-123"
*/
document_number_prefix?: string | null;
/**
* Whether to finalize invoices with zero amount for this billing entity
* @example true
*/
finalize_zero_amount_invoice?: boolean;
billing_configuration?: {
/**
* The footer text to be displayed on invoices for this billing entity
* @example "Thank you for your business"
*/
invoice_footer?: string;
/**
* The language of the documents generated for this billing entity
* @example "en"
*/
document_locale?: string;
/**
* The grace period (in days) for invoice finalization
* @example 0
*/
invoice_grace_period?: number;
};
/**
* The net payment term (in days) for this billing entity
* @example 0
*/
net_payment_term?: number;
/**
* The first line of the billing address
* @example "5230 Penfield Ave"
*/
address_line1?: string | null;
/**
* The second line of the billing address
* @example "Suite 100"
*/
address_line2?: string | null;
/**
* The city of the billing address
* @example "Woodland Hills"
*/
city?: string | null;
/**
* The state of the billing address
* @example "CA"
*/
state?: string | null;
/** The country code of the billing address */
country?: Country | null;
/**
* The zipcode of the billing address
* @example "91364"
*/
zipcode?: string | null;
/**
* The email address of the billing entity
* @format email
* @example "billing@acme.com"
*/
email?: string | null;
/**
* The legal name of the billing entity
* @example "Acme Corporation"
*/
legal_name?: string | null;
/**
* The legal registration number of the billing entity
* @example "US123456789"
*/
legal_number?: string | null;
/**
* The tax identification number of the billing entity
* @example "EU123456789"
*/
tax_identification_number?: string | null;
/**
* The timezone of the billing entity
* @example "UTC"
*/
timezone?: Timezone;
/** The tax codes that should be associated with this billing entity */
tax_codes?: TaxCodes;
/** The email notification settings for this billing entity */
email_settings?: ("invoice.finalized" | "credit_note.created")[];
/**
* Whether EU tax management is enabled for this billing entity
* @example false
*/
eu_tax_management?: boolean;
/**
* The base64 encoded logo image for the billing entity. Sending "null" will remove the logo, if any exist.
* @format uri
* @example "data:image/png;base64,..."
*/
logo?: string | null;
/**
* The codes of the invoice custom section that should be associated with this billing entity
* @example ["custom_section_1","custom_section_2"]
*/
invoice_custom_section_codes?: string[];
}
export interface ActivityLogObject {
/**
* Unique identifier assigned to the activity log within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the activity log record within the Lago system
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
activity_id: string;
/**
* The email of the user who performed the activity
* @format email
* @example "dinesh@piedpiper.test"
*/
user_email?: string | null;
/**
* This field stores the actitivy action that was performed to the activity_object.
* @example "billing_metric.created"
*/
activity_type: string;
/**
* This field represents the source of the activity log, the interaction source that triggered the action.
* @example "api"
*/
activity_source: "api" | "front" | "system";
/**
* This field represents the final state of the object that the action was applied.
* @format object
* @example {"lago_id":"dad68bc7-c01a-4ad8-a87b-13e78693a5bc","plan_id":"b9155544-e261-4e92-b54e-f65d7609294c"}
*/
activity_object?: object | null;
/**
* @format object
* @example {"plan_id":[null,"b9155544-e261-4e92-b54e-f65d7609294c"]}
*/
activity_object_changes?: object | null;
/**
* The customer external unique identifier (provided by your own application)
* @example "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"
*/
external_customer_id?: string | null;
/**
* Unique identifier assigned to the subscription in your application.
* @example "external_id"
*/
external_subscription_id?: string | null;
/**
* The resource id of the object that the action was applied.
* @format uuid
* @example "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"
*/
resource_id: string;
/**
* The resource type of the resource_id record.
* @example "BillableMetric"
*/
resource_type: string;
/**
* Unique identifier for the organization associated with the activity log.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
organization_id: string;
/**
* The logged date of the activity, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
* @format date-time
* @example "2025-03-31T12:31:44Z"
*/
logged_at: string;
/**
* The creation date of the activity record in the Lago application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
* @format date-time
* @example "2022-04-29T08:59:51Z"
*/
created_at: string;
}
export interface PaginationMeta {
/**
* Current page.
* @example 2
*/
current_page: number;
/**
* Next page.
* @example 3
*/
next_page?: number | null;
/**
* Previous page.
* @example 1
*/
prev_page?: number | null;
/**
* Total number of pages.
* @example 4
*/
total_pages: number;
/**
* Total number of records.
* @example 70
*/
total_count: number;
}
export interface ActivityLogsPaginated {
activity_logs: ActivityLogObject[];
meta: PaginationMeta;
}
export interface ActivityLog {
activity_log: ActivityLogObject;
}
export interface AddOnObject {
/**
* Unique identifier of the add-on, created by Lago.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_id: string;
/**
* The name of the add-on.
* @example "Setup Fee"
*/
name: string;
/**
* Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name.
* @example "Setup Fee (SF1)"
*/
invoice_display_name: string | null;
/**
* Unique code used to identify the add-on.
* @example "setup_fee"
*/
code: string;
/**
* The cost of the add-on in cents, excluding any applicable taxes, that is billed to a customer. By creating a one-off invoice, you will be able to override this value.
* @example 50000
*/
amount_cents: number;
/**
* The currency of the add-on.
* @example "USD"
*/
amount_currency: Currency;
/**
* The description of the add-on.
* @example "Implementation fee for new customers."
*/
description: string | null;
/**
* The date and time when the add-on was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the add-on was initially created.
* @format date-time
* @example "2022-04-29T08:59:51Z"
*/
created_at: string;
/** All taxes applied to the add-on. */
taxes?: TaxObject[];
}
export interface AddOnsPaginated {
add_ons: AddOnObject[];
meta: PaginationMeta;
}
export interface AddOnBaseInput {
/**
* The name of the add-on.
* @example "Setup Fee"
*/
name?: string;
/**
* Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name.
* @example "Setup Fee (SF1)"
*/
invoice_display_name?: string | null;
/**
* Unique code used to identify the add-on.
* @example "setup_fee"
*/
code?: string;
/**
* The cost of the add-on in cents, excluding any applicable taxes, that is billed to a customer. By creating a one-off invoice, you will be able to override this value.
* @example 50000
*/
amount_cents?: number;
/**
* The currency of the add-on.
* @example "USD"
*/
amount_currency?: Currency;
/**
* The description of the add-on.
* @example "Implementation fee for new customers."
*/
description?: string | null;
/** List of unique code used to identify the taxes. */
tax_codes?: TaxCodes;
}
export interface AddOnCreateInput {
add_on: AddOnBaseInput;
}
export interface AddOn {
add_on: AddOnObject;
}
export interface AddOnUpdateInput {
add_on: AddOnBaseInput;
}
export interface ApiLogObject {
/**
* Lago API version used in the request.
* @example "v1"
*/
api_version: string;
/**
* The client used to make the request to the API.
* @example "Lago Ruby v1.26.0"
*/
client: string;
/**
* This field represents the HTTP method of the request.
* @example "post"
*/
http_method: "post" | "put" | "delete";
/**
* This field represents the HTTP status of the requests.
* @example 200
*/
http_status: number;
/**
* The logged date of the api log, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
* @format date-time
* @example "2025-03-31T12:31:44Z"
*/
logged_at: string;
/**
* @format object
* @example "{ "billable_metric": { "name": "Storage", "code": "storage" } }"
*/
request_body: string;
/**
* This field represents the API origin of the requested URL
* @example "https://app.lago.dev/"
*/
request_origin: string;
/**
* This field represents the API path of the requested URL
* @example "/billable_metrics"
*/
request_path: string;
/**
* The creation date of the api log record in the Lago application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application
* @format date-time
* @example "2022-04-29T08:59:51Z"
*/
created_at: string;
/**
* Unique identifier for the api log.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
request_id: string;
/**
* @format object
* @example "{ "lago_id": "b9155544-e261-4e92-b54e-f65d7609294c", ... }"
*/
request_response?: string;
}
export interface ApiLogsPaginated {
api_logs: ApiLogObject[];
meta: PaginationMeta;
}
export interface ApiLog {
api_log: ApiLogObject;
}
export interface GrossRevenueObject {
/**
* Identifies the month to analyze revenue.
* @example "2023-11-01T00:00:00.000Z"
*/
month: string;
/**
* The total amount of revenue for a period, expressed in cents.
* @example 50000
*/
amount_cents: number;
/**
* The currency of revenue analytics. Format must be ISO 4217.
* @example "USD"
*/
currency: Currency;
/**
* Contains invoices count.
* @example 10
*/
invoices_count: number;
}
export interface GrossRevenues {
gross_revenues: GrossRevenueObject[];
}
export interface InvoiceCollectionObject {
/**
* Identifies the month to analyze revenue.
* @example "2023-11-01T00:00:00.000Z"
*/
month: string;
/**
* The payment status of the invoices.
* @example "succeeded"
*/
payment_status?: "pending" | "succeeded" | "failed";
/**
* Contains invoices count.
* @example 10
*/
invoices_count: number;
/**
* The total amount of revenue for a period, expressed in cents.
* @example 50000
*/
amount_cents?: number;
/**
* The currency of revenue analytics. Format must be ISO 4217.
* @example "USD"
*/
currency?: Currency;
}
export interface InvoiceCollections {
invoice_collections: InvoiceCollectionObject[];
}
export interface InvoicedUsageObject {
/**
* Identifies the month to analyze revenue.
* @example "2023-11-01T00:00:00.000Z"
*/
month: string;
/**
* The code of the usage-based billable metrics.
* @example "code1"
*/
code?: string;
/**
* The total amount of revenue for a period, expressed in cents.
* @example 50000
*/
amount_cents: number;
/**
* The currency of revenue analytics. Format must be ISO 4217.
* @example "USD"
*/
currency: Currency;
}
export interface InvoicedUsages {
invoiced_usages: InvoicedUsageObject[];
}
export interface MrrObject {
/**
* Identifies the month to analyze MRR.
* @example "2023-11-01T00:00:00.000Z"
*/
month: string;
/**
* The total amount of MRR, expressed in cents.
* @example 50000
*/
amount_cents: number;
/**
* The currency of MRR analytics. Format must be ISO 4217.
* @example "USD"
*/
currency: Currency;
}
export interface Mrrs {
mrrs: MrrObject[];
}
export interface OverdueBalanceObject {
/**
* Identifies the month to analyze revenue.
* @example "2023-11-01T00:00:00.000Z"
*/
month: string;
/**
* The total amount of revenue for a period, expressed in cents.
* @example 50000
*/
amount_cents: number;
/**
* The currency of revenue analytics. Format must be ISO 4217.
* @example "USD"
*/
currency: Currency;
/**
* The Lago invoice IDs associated with the revenue.
* @example ["5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"]
*/
lago_invoice_ids: string[];
}
export interface OverdueBalances {
overdue_balances: OverdueBalanceObject[];
}
export interface UsageObject {
/**
* The unique identifier of the organization for which the usage analytics is calculated.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
organization_id: string;
/**
* The start date of the period for which the usage analytics is calculated.
* @format date
* @example "2023-11-01"
*/
start_of_period_dt?: string;
/**
* The end date of the period for which the usage analytics is calculated.
* @format date
* @example "2023-11-30"
*/
end_of_period_dt?: string;
/**
* The currency of usage analytics. Format must be ISO 4217.
* @example "USD"
*/
amount_currency: Currency;
/**
* The total amount for usages for a period, expressed in cents.
* @example 50000
*/
amount_cents: number;
/**
* The code of the usage-based billable metrics.
* @example "code1"
*/
billable_metric_code?: string;
/**
* The total number of units for the usage-based billable metrics.
* @pattern ^[0-9]+.?[0-9]*$
* @example "1.0"
*/
units?: string;
/**
* Indicates whether the billable metric associated with the usage is deleted.
* @example false
*/
is_billable_metric_deleted?: boolean;
}
export interface Usages {
usages: UsageObject[];
}
/** @example "USD" */
export type CurrencyOrNull = "AED" | "AFN" | "ALL" | "AMD" | "ANG" | "AOA" | "ARS" | "AUD" | "AWG" | "AZN" | "BAM" | "BBD" | "BDT" | "BGN" | "BIF" | "BMD" | "BND" | "BOB" | "BRL" | "BSD" | "BWP" | "BYN" | "BZD" | "CAD" | "CDF" | "CHF" | "CLF" | "CLP" | "CNY" | "COP" | "CRC" | "CVE" | "CZK" | "DJF" | "DKK" | "DOP" | "DZD" | "EGP" | "ETB" | "EUR" | "FJD" | "FKP" | "GBP" | "GEL" | "GIP" | "GMD" | "GNF" | "GTQ" | "GYD" | "HKD" | "HNL" | "HRK" | "HTG" | "HUF" | "IDR" | "ILS" | "INR" | "ISK" | "JMD" | "JPY" | "KES" | "KGS" | "KHR" | "KMF" | "KRW" | "KYD" | "KZT" | "LAK" | "LBP" | "LKR" | "LRD" | "LSL" | "MAD" | "MDL" | "MGA" | "MKD" | "MMK" | "MNT" | "MOP" | "MRO" | "MUR" | "MVR" | "MWK" | "MXN" | "MYR" | "MZN" | "NAD" | "NGN" | "NIO" | "NOK" | "NPR" | "NZD" | "PAB" | "PEN" | "PGK" | "PHP" | "PKR" | "PLN" | "PYG" | "QAR" | "RON" | "RSD" | "RUB" | "RWF" | "SAR" | "SBD" | "SCR" | "SEK" | "SGD" | "SHP" | "SLL" | "SOS" | "SRD" | "STD" | "SZL" | "THB" | "TJS" | "TOP" | "TRY" | "TTD" | "TWD" | "TZS" | "UAH" | "UGX" | "USD" | "UYU" | "UZS" | "VND" | "VUV" | "WST" | "XAF" | "XCD" | "XOF" | "XPF" | "YER" | "ZAR" | "ZMW";
export interface AppliedCouponObject {
/**
* Unique identifier of the applied coupon, created by Lago.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_id: string;
/**
* Unique identifier of the coupon, created by Lago.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_coupon_id: string;
/**
* Unique code used to identify the coupon.
* @example "startup_deal"
*/
coupon_code: string;
/**
* The name of the coupon.
* @example "Startup Deal"
*/
coupon_name: string;
/**
* Unique identifier of the customer, created by Lago.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_customer_id: string;
/**
* The customer external unique identifier (provided by your own application)
* @example "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"
*/
external_customer_id: string;
/**
* The status of the coupon. Can be either `active` or `terminated`.
* @example "active"
*/
status: "active" | "terminated";
/**
* The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type.
* @example 2000
*/
amount_cents?: number | null;
/**
* The remaining amount in cents for a `fixed_amount` coupon with a frequency set to `once`. This field indicates the remaining balance or value that can still be utilized from the coupon.
* @example 50
*/
amount_cents_remaining?: number | null;
/**
* The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
* @example "EUR"
*/
amount_currency?: CurrencyOrNull;
/**
* The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
* @pattern ^[0-9]+.?[0-9]*$
* @example null
*/
percentage_rate?: string | null;
/**
* The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`.
*
* - If set to `once`, the coupon is applicable only for a single use.
* - If set to `recurring`, the coupon can be used multiple times for recurring billing periods.
* - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.
* @example "recurring"
*/
frequency: "once" | "recurring" | "forever";
/**
* Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type
* @example 3
*/
frequency_duration?: number | null;
/**
* The remaining number of billing periods to which the coupon is applicable. This field determines the remaining usage or availability of the coupon based on the remaining billing periods.
* @example 1
*/
frequency_duration_remaining?: number | null;
/**
* The date and time after which the coupon will stop applying to customer's invoices. Once the expiration date is reached, the coupon will no longer be applicable, and any further invoices generated for the customer will not include the coupon discount.
* @format date-time
* @example "2022-04-29T08:59:51Z"
*/
expiration_at?: string | null;
/**
* The date and time when the coupon was assigned to a customer. It is expressed in UTC format according to the ISO 8601 datetime standard.
* @format date-time
* @example "2022-04-29T08:59:51Z"
*/
created_at: string;
/**
* This field indicates the specific moment when the coupon amount is fully utilized or when the coupon is removed from the customer's coupon list. It is expressed in UTC format according to the ISO 8601 datetime standard.
* @format date-time
* @example "2022-04-29T08:59:51Z"
*/
terminated_at?: string | null;
}
export interface CreditObject {
/**
* Unique identifier assigned to the credit within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the credit's item record within the Lago system.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_id: string;
/**
* The amount of credit associated with the invoice, expressed in cents.
* @example 1200
*/
amount_cents: number;
/**
* The currency of the credit.
* @example "EUR"
*/
amount_currency: Currency;
/**
* Indicates whether the credit is applied on the amount before taxes (coupons) or after taxes (credit notes). This flag helps determine the order in which credits are applied to the invoice calculation
* @example false
*/
before_taxes: boolean;
/** The item attached to the credit. */
item: {
/**
* Unique identifier assigned to the credit item within the Lago application.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_item_id: string;
/**
* The type of credit applied. Possible values are `coupon`, `credit_note` or `invoice` (for `progressive_billing` invoice).
* @example "coupon"
*/
type: "coupon" | "credit_note" | "invoice";
/**
* The code of the credit applied. It can be the code of the coupon attached to the credit, the credit note's number or the `progressive_billing` invoice number.
* @example "startup_deal"
*/
code: string;
/**
* The name of the credit applied. It can be the name of the coupon attached to the credit, the initial invoice's number linked to the credit note or the `progressive_billing` invoice number.
* @example "Startup Deal"
*/
name: string;
};
invoice: {
/**
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_id: string;
/** @example "succeeded" */
payment_status: "pending" | "succeeded" | "failed";
};
}
export type AppliedCouponObjectExtended = AppliedCouponObject & {
credits: CreditObject[];
};
export interface AppliedCouponsPaginated {
applied_coupons: AppliedCouponObjectExtended[];
meta: PaginationMeta;
}
export interface AppliedCouponInput {
applied_coupon: {
/**
* The customer external unique identifier (provided by your own application)
* @example "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"
*/
external_customer_id: string;
/**
* Unique code used to identify the coupon.
* @example "startup_deal"
*/
coupon_code: string;
/**
* The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`.
*
* - If set to `once`, the coupon is applicable only for a single use.
* - If set to `recurring`, the coupon can be used multiple times for recurring billing periods.
* - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.
* @example "recurring"
*/
frequency?: "once" | "recurring" | "forever";
/**
* Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type
* @example 3
*/
frequency_duration?: number | null;
/**
* The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type.
* @example 2000
*/
amount_cents?: number | null;
/**
* The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
* @example "EUR"
*/
amount_currency?: CurrencyOrNull;
/**
* The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
* @pattern ^[0-9]+.?[0-9]*$
* @example null
*/
percentage_rate?: string | null;
};
}
export interface AppliedCoupon {
applied_coupon: AppliedCouponObject;
}
/** Values used to apply differentiated pricing based on additional event properties. */
export interface BillableMetricFilterObject {
/**
* Filter key to add to the event properties payload
* @example "region"
*/
key: string;
/** List of possible filter values */
values: string[];
}
export interface BillableMetricObject {
/**
* Unique identifier of the billable metric created by Lago.
* @format uuid
* @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
*/
lago_id: string;
/**
* Name of the billable metric.
* @example "Storage"
*/
name: string;
/**
* Unique code used to identify the billable metric associated with the API request. This code associates each event with the correct metric.
* @example "storage"
*/
code: string;
/**
* Internal description of the billable metric.
* @example "GB of storage used in my application"
*/
description?: string | null;
/**
* Defines if the billable metric is persisted billing period over billing period.
*
* - If set to `true`: the accumulated number of units calculated from the previous billing period is persisted to the next billing period.
* - If set to `false`: the accumulated number of units is reset to 0 at the end of the billing period.
* - If not defined in the request, default value is `false`.
* @example false
*/
recurring: boolean;
/**
* Refers to the numeric value or mathematical expression that will be rounded based on the calculated number of billing units. Possible values are `round`, `ceil` and `floor`.
* @example "round"
*/
rounding_function?: "ceil" | "floor" | "round";
/**
* Specifies the number of decimal places to which the `rounding_function` will be rounded. It can be a positive or negative value.
* @example 2
*/
rounding_precision?: number | null;
/**
* Creation date of the billable metric.
* @format date-time
* @example "2022-09-14T16:35:31Z"
*/
created_at: string;
/**
* Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units.
* @example "round((ended_at - started_at) * units)"
*/
expression?: string;
/**
* Property of the billable metric used for aggregating usage data. This field is not required for `count_agg`.
* @example "gb"
*/
field_name?: string | null;
/**
* Aggregation method used to compute usage for this billable metric.
* @example "sum_agg"
*/
aggregation_type: "count_agg" | "sum_agg" | "max_agg" | "unique_count_agg" | "weighted_sum_agg" | "latest_agg";
/**
* Parameter exclusively utilized in conjunction with the `weighted_sum` aggregation type. It serves to adjust the aggregation result by assigning weights and proration to the result based on time intervals. When this field is not provided, the default time interval is assumed to be in `seconds`.
* @example "seconds"
*/
weighted_interval?: "seconds";
filters?: BillableMetricFilterObject[];
}
export interface BillableMetricsPaginated {
billable_metrics: BillableMetricObject[];
meta: PaginationMeta;
}
/** Values used to apply differentiated pricing based on additional event properties. */
export interface BillableMetricFilterInput {
/**
* Filter key to add to the event properties payload
* @example "region"
*/
key: string;
/** List of possible filter values */
values: string[];
}
export interface BillableMetricBaseInput {
/**
* Name of the billable metric.
* @example "Storage"
*/
name?: string;
/**
* Unique code used to identify the billable metric associated with the API request. This code associates each event with the correct metric.
* @example "storage"
*/
code?: string;
/**
* Internal description of the billable metric.
* @example "GB of storage used in my application"
*/
description?: string | null;
/**
* Defines if the billable metric is persisted billing period over billing period.
*
* - If set to `true`: the accumulated number of units calculated from the previous billing period is persisted to the next billing period.
* - If set to `false`: the accumulated number of units is reset to 0 at the end of the billing period.
* - If not defined in the request, default value is `false`.
* @example false
*/
recurring?: boolean;
/**
* Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units.
* Accepted function are `ceil`, `concat` and `round` as well as `+`, `-`, `\` and `*` operations.
* Round is accepting an optional second parameter to specify the number of decimal.
* @example "round((ended_at - started_at) * units)"
*/
expression?: string | null;
/**
* Refers to the numeric value or mathematical expression that will be rounded based on the calculated number of billing units. Possible values are `round`, `ceil` and `floor`.
* @example "round"
*/
rounding_function?: "ceil" | "floor" | "round";
/**
* Specifies the number of decimal places to which the `rounding_function` will be rounded. It can be a positive or negative value.
* @example 2
*/
rounding_precision?: number | nul