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

lago_types/models/
invoice.rs
