lago_types/models/
subscription.rs

1use chrono::{DateTime, NaiveDate, Utc};
2use serde::{Deserialize, Serialize};
3use strum_macros::EnumString;
4use uuid::Uuid;
5
6/// Represents a subscription in the Lago billing system.
7///
8/// A subscription links a customer to a plan, defining their billing cycle
9/// and the charges they will be invoiced for.
10#[derive(Debug, Clone, Serialize, Deserialize)]
11pub struct Subscription {
12    /// Unique identifier for the subscription in Lago.
13    pub lago_id: Uuid,
14    /// External unique identifier for the subscription.
15    pub external_id: String,
16    /// Lago ID of the associated customer.
17    pub lago_customer_id: Uuid,
18    /// External ID of the associated customer.
19    pub external_customer_id: String,
20    /// Determines when recurring billing cycles occur.
21    pub billing_time: SubscriptionBillingTime,
22    /// Optional display name for the subscription.
23    pub name: Option<String>,
24    /// Code of the associated plan.
25    pub plan_code: String,
26    /// Current status of the subscription.
27    pub status: SubscriptionStatus,
28    /// When the subscription was created.
29    pub created_at: DateTime<Utc>,
30    /// When the subscription was canceled (if applicable).
31    pub canceled_at: Option<DateTime<Utc>>,
32    /// When the subscription started.
33    pub started_at: Option<DateTime<Utc>>,
34    /// When the subscription will end.
35    pub ending_at: Option<DateTime<Utc>>,
36    /// The subscription date.
37    pub subscription_at: DateTime<Utc>,
38    /// When the subscription was terminated (if applicable).
39    pub terminated_at: Option<DateTime<Utc>>,
40    /// Code of the previous plan (if changed).
41    pub previous_plan_code: Option<String>,
42    /// Code of the upcoming plan (if scheduled for change).
43    pub next_plan_code: Option<String>,
44    /// Date when a downgrade will take effect.
45    pub downgrade_plan_date: Option<NaiveDate>,
46    /// When the trial period ended.
47    pub trial_ended_at: Option<DateTime<Utc>>,
48    /// Start of the current billing period.
49    pub current_billing_period_started_at: Option<DateTime<Utc>>,
50    /// End of the current billing period.
51    pub current_billing_period_ending_at: Option<DateTime<Utc>>,
52    /// The associated plan details.
53    pub plan: Option<SubscriptionPlan>,
54}
55
56/// Billing time determines when recurring billing cycles occur.
57#[derive(Debug, Clone, Serialize, Deserialize, EnumString, PartialEq, Eq)]
58#[serde(rename_all = "snake_case")]
59#[strum(serialize_all = "snake_case")]
60pub enum SubscriptionBillingTime {
61    /// Billing cycle based on the specific date the subscription started.
62    Anniversary,
63    /// Billing cycle at the first day of the week/month/year.
64    Calendar,
65}
66
67/// Status of a subscription.
68#[derive(Debug, Clone, Serialize, Deserialize, EnumString, PartialEq, Eq)]
69#[serde(rename_all = "snake_case")]
70#[strum(serialize_all = "snake_case")]
71pub enum SubscriptionStatus {
72    /// Subscription is active and billing.
73    Active,
74    /// Subscription has been canceled but not yet terminated.
75    Canceled,
76    /// Subscription is pending activation.
77    Pending,
78    /// Subscription has been terminated.
79    Terminated,
80}
81
82/// Plan details associated with a subscription.
83#[derive(Debug, Clone, Serialize, Deserialize)]
84pub struct SubscriptionPlan {
85    /// Unique identifier for the plan in Lago.
86    pub lago_id: Uuid,
87    /// Name of the plan.
88    pub name: String,
89    /// Display name for invoices.
90    pub invoice_display_name: Option<String>,
91    /// When the plan was created.
92    pub created_at: DateTime<Utc>,
93    /// Unique code for the plan.
94    pub code: String,
95    /// Billing interval (weekly, monthly, quarterly, yearly).
96    pub interval: String,
97    /// Description of the plan.
98    pub description: Option<String>,
99    /// Base amount in cents.
100    pub amount_cents: i64,
101    /// Currency for the amount.
102    pub amount_currency: String,
103    /// Trial period in days.
104    pub trial_period: Option<f64>,
105    /// Whether the plan is billed in advance.
106    pub pay_in_advance: bool,
107    /// Whether charges are billed monthly for yearly plans.
108    pub bill_charges_monthly: Option<bool>,
109}
lago_types/models/subscription.rs

lago_types/models/
subscription.rs
