lago_types/models/
invoice.rs

1use chrono::{DateTime, Utc};
2use serde::{Deserialize, Serialize};
3use strum_macros::EnumString;
4use uuid::Uuid;
5
6use super::customer::Customer;
7use super::usage_threshold::UsageThreshold;
8
9/// Represents an invoice in the Lago billing system.
10///
11/// This struct contains all information about an invoice, including amounts,
12/// payment status, billing periods, and associated metadata.
13#[derive(Debug, Clone, Serialize, Deserialize)]
14pub struct Invoice {
15    pub lago_id: Option<Uuid>,
16    pub billing_entity_code: Option<String>,
17    pub sequential_id: Option<i32>,
18    pub number: String,
19    pub issuing_date: String,
20    pub invoice_type: InvoiceType,
21    pub status: InvoiceStatus,
22    pub payment_status: InvoicePaymentStatus,
23    pub currency: String,
24    pub fees_amount_cents: i64,
25    pub coupons_amount_cents: i64,
26    pub credit_notes_amount_cents: i64,
27    pub sub_total_excluding_taxes_amount_cents: i64,
28    pub taxes_amount_cents: i64,
29    pub sub_total_including_taxes_amount_cents: i64,
30    pub prepaid_credit_amount_cents: i64,
31    pub progressive_billing_credit_amount_cents: i64,
32    pub total_amount_cents: i64,
33    pub version_number: Option<i32>,
34    pub created_at: DateTime<Utc>,
35    pub updated_at: DateTime<Utc>,
36    pub payment_dispute_lost_at: Option<DateTime<Utc>>,
37    pub payment_due_date: Option<String>,
38    pub payment_overdue: Option<bool>,
39    pub net_payment_term: Option<i32>,
40    pub self_billed: Option<bool>,
41    pub file_url: Option<String>,
42    pub customer: Option<Customer>,
43    pub billing_periods: Option<Vec<InvoiceBillingPeriod>>,
44    pub metadata: Option<Vec<InvoiceMetadata>>,
45    pub applied_taxes: Vec<InvoiceAppliedTax>,
46    pub applied_usage_thresholds: Option<Vec<InvoiceAppliedUsageThreshold>>,
47    /// Fees associated with this invoice (included when fetching a single invoice)
48    pub fees: Option<Vec<Fee>>,
49}
50
51/// Represents a fee line item on an invoice.
52#[derive(Debug, Clone, Serialize, Deserialize)]
53pub struct Fee {
54    /// Unique identifier for the fee in Lago
55    pub lago_id: Uuid,
56    /// Reference to the charge that generated this fee
57    pub lago_charge_id: Option<Uuid>,
58    /// Reference to the invoice this fee belongs to
59    pub lago_invoice_id: Option<Uuid>,
60    /// Reference to the subscription
61    pub lago_subscription_id: Option<Uuid>,
62    /// Reference to the customer
63    pub lago_customer_id: Option<Uuid>,
64    /// External customer ID
65    pub external_customer_id: Option<String>,
66    /// External subscription ID
67    pub external_subscription_id: Option<String>,
68    /// Fee amount in cents (excluding taxes)
69    pub amount_cents: i64,
70    /// Currency for the amount
71    pub amount_currency: String,
72    /// Precise amount as string for decimal precision
73    pub precise_amount: Option<String>,
74    /// Total amount including taxes in cents
75    pub total_amount_cents: i64,
76    /// Currency for total amount
77    pub total_amount_currency: String,
78    /// Precise total amount as string
79    pub precise_total_amount: Option<String>,
80    /// Tax amount in cents
81    pub taxes_amount_cents: i64,
82    /// Precise tax amount as string
83    pub taxes_precise_amount: Option<String>,
84    /// Tax rate percentage
85    pub taxes_rate: f64,
86    /// Number of units
87    pub units: String,
88    /// Precise unit amount as string
89    pub precise_unit_amount: Option<String>,
90    /// Total aggregated units
91    pub total_aggregated_units: Option<String>,
92    /// Number of events that contributed to this fee
93    pub events_count: Option<i64>,
94    /// Payment status of the fee
95    pub payment_status: FeePaymentStatus,
96    /// Whether this fee is paid in advance
97    pub pay_in_advance: Option<bool>,
98    /// Whether this fee is invoiceable
99    pub invoiceable: Option<bool>,
100    /// Start date of the billing period
101    pub from_date: Option<String>,
102    /// End date of the billing period
103    pub to_date: Option<String>,
104    /// When the fee was created
105    pub created_at: DateTime<Utc>,
106    /// When payment succeeded
107    pub succeeded_at: Option<DateTime<Utc>>,
108    /// When payment failed
109    pub failed_at: Option<DateTime<Utc>>,
110    /// When refunded
111    pub refunded_at: Option<DateTime<Utc>>,
112    /// Fee item details
113    pub item: Option<FeeItem>,
114}
115
116/// Payment status of a fee
117#[derive(Debug, Clone, Serialize, Deserialize, EnumString, PartialEq, Eq)]
118#[serde(rename_all = "snake_case")]
119#[strum(serialize_all = "snake_case")]
120pub enum FeePaymentStatus {
121    Pending,
122    Succeeded,
123    Failed,
124    Refunded,
125}
126
127/// Fee item details
128#[derive(Debug, Clone, Serialize, Deserialize)]
129pub struct FeeItem {
130    /// Type of fee item (charge, add_on, subscription, credit, commitment)
131    #[serde(rename = "type")]
132    pub item_type: String,
133    /// Code identifying the item
134    pub code: String,
135    /// Display name
136    pub name: String,
137    /// Description of the item
138    pub description: Option<String>,
139}
140
141#[derive(Debug, Clone, Serialize, Deserialize, EnumString)]
142#[serde(rename_all = "snake_case")]
143#[strum(serialize_all = "snake_case")]
144pub enum InvoiceType {
145    Subscription,
146    AddOn,
147    Credit,
148    OneOff,
149    ProgressiveBilling,
150}
151
152/// Defines the current status of an invoice.
153#[derive(Debug, Clone, Serialize, Deserialize, EnumString)]
154#[serde(rename_all = "snake_case")]
155#[strum(serialize_all = "snake_case")]
156pub enum InvoiceStatus {
157    Draft,
158    Finalized,
159    Voided,
160    Pending,
161    Failed,
162}
163
164/// Defines the payment status of an invoice.
165#[derive(Debug, Clone, Serialize, Deserialize, EnumString)]
166#[serde(rename_all = "snake_case")]
167#[strum(serialize_all = "snake_case")]
168pub enum InvoicePaymentStatus {
169    Pending,
170    Succeeded,
171    Failed,
172}
173
174/// Represents a billing period associated with an invoice.
175///
176/// This struct contains information about the subscription and charge periods
177/// that this invoice covers.
178#[derive(Debug, Clone, Serialize, Deserialize)]
179pub struct InvoiceBillingPeriod {
180    pub lago_subscription_id: Uuid,
181    pub external_subscription_id: String,
182    pub subscription_from_datetime: DateTime<Utc>,
183    pub subscription_to_datetime: DateTime<Utc>,
184    pub charges_from_datetime: DateTime<Utc>,
185    pub charges_to_datetime: DateTime<Utc>,
186    pub invoicing_reason: InvoiceInvoicingReason,
187    pub lago_plan_id: Uuid,
188}
189
190/// Defines the reason for invoice generation.
191#[derive(Debug, Clone, Serialize, Deserialize, EnumString)]
192#[serde(rename_all = "snake_case")]
193#[strum(serialize_all = "snake_case")]
194pub enum InvoiceInvoicingReason {
195    SubscriptionStarting,
196    SubscriptionPeriodic,
197    SubscriptionTerminating,
198    InAdvanceCharge,
199    InAdvanceChargePeriodic,
200    ProgressiveBilling,
201}
202
203/// Represents custom metadata associated with an invoice.
204#[derive(Debug, Clone, Serialize, Deserialize)]
205pub struct InvoiceMetadata {
206    pub lago_id: Uuid,
207    pub key: String,
208    pub value: String,
209    pub created_at: DateTime<Utc>,
210}
211
212/// Represents a tax applied to an invoice.
213///
214/// This struct contains information about taxes that have been applied
215/// to the invoice, including the tax details and amounts.
216#[derive(Debug, Clone, Serialize, Deserialize)]
217pub struct InvoiceAppliedTax {
218    pub lago_invoice_id: Uuid,
219    pub fee_amount_cents: Option<i64>,
220    pub lago_id: Uuid,
221    pub lago_tax_id: Uuid,
222    pub tax_name: String,
223    pub tax_code: String,
224    pub tax_rate: f32,
225    pub tax_description: String,
226    pub amount_cents: i64,
227    pub amount_currency: String,
228    pub created_at: DateTime<Utc>,
229}
230
231/// Represents a usage threshold applied to an invoice.
232///
233/// This struct contains information about usage thresholds that have been
234/// triggered and applied to the invoice.
235#[derive(Debug, Clone, Serialize, Deserialize)]
236pub struct InvoiceAppliedUsageThreshold {
237    pub lifetime_usage_amount_cents: Option<i64>,
238    pub created_at: DateTime<Utc>,
239    pub usage_threshold: UsageThreshold,
240}
lago_types/models/invoice.rs

lago_types/models/
invoice.rs
