lago_types/models/plan.rs
1use chrono::{DateTime, Utc};
2use serde::{Deserialize, Serialize};
3use strum_macros::EnumString;
4use uuid::Uuid;
5
6use crate::models::UsageThreshold;
7
8/// Represents a plan in the Lago billing system.
9///
10/// A plan defines pricing configuration that can be assigned to customers
11/// through subscriptions.
12#[derive(Debug, Clone, Serialize, Deserialize)]
13pub struct Plan {
14 /// Unique identifier for the plan in Lago.
15 pub lago_id: Uuid,
16 /// Name of the plan.
17 pub name: String,
18 /// Display name for invoices.
19 pub invoice_display_name: Option<String>,
20 /// When the plan was created.
21 pub created_at: DateTime<Utc>,
22 /// Unique code for the plan.
23 pub code: String,
24 /// Billing interval (weekly, monthly, quarterly, yearly).
25 pub interval: PlanInterval,
26 /// Description of the plan.
27 pub description: Option<String>,
28 /// Base amount in cents.
29 pub amount_cents: i64,
30 /// Currency for the amount.
31 pub amount_currency: String,
32 /// Trial period in days.
33 pub trial_period: Option<f64>,
34 /// Whether the plan is billed in advance.
35 pub pay_in_advance: bool,
36 /// Whether charges are billed monthly for yearly plans.
37 pub bill_charges_monthly: Option<bool>,
38 /// Number of active subscriptions using this plan.
39 pub active_subscriptions_count: Option<i32>,
40 /// Number of draft invoices for this plan.
41 pub draft_invoices_count: Option<i32>,
42 /// Parent plan ID (for plan overrides).
43 pub parent_id: Option<Uuid>,
44 /// Charges associated with this plan.
45 pub charges: Option<Vec<PlanCharge>>,
46 /// Taxes associated with this plan.
47 pub taxes: Option<Vec<PlanTax>>,
48 /// Minimum commitment for this plan.
49 pub minimum_commitment: Option<PlanMinimumCommitment>,
50 /// Usage thresholds for progressive billing.
51 pub usage_thresholds: Option<Vec<UsageThreshold>>,
52}
53
54/// Billing interval for a plan.
55#[derive(Debug, Clone, Serialize, Deserialize, EnumString, PartialEq, Eq)]
56#[serde(rename_all = "snake_case")]
57#[strum(serialize_all = "snake_case")]
58pub enum PlanInterval {
59 /// Weekly billing.
60 Weekly,
61 /// Monthly billing.
62 Monthly,
63 /// Quarterly billing.
64 Quarterly,
65 /// Semi-annual billing.
66 Semiannual,
67 /// Yearly billing.
68 Yearly,
69}
70
71/// Charge model types.
72#[derive(Debug, Clone, Serialize, Deserialize, EnumString, PartialEq, Eq)]
73#[serde(rename_all = "snake_case")]
74#[strum(serialize_all = "snake_case")]
75pub enum ChargeModel {
76 /// Standard pricing model.
77 Standard,
78 /// Graduated pricing model.
79 Graduated,
80 /// Volume pricing model.
81 Volume,
82 /// Package pricing model.
83 Package,
84 /// Percentage pricing model.
85 Percentage,
86 /// Graduated percentage pricing model.
87 GraduatedPercentage,
88 /// Dynamic pricing model.
89 Dynamic,
90}
91
92/// Represents a charge in a plan.
93#[derive(Debug, Clone, Serialize, Deserialize)]
94pub struct PlanCharge {
95 /// Unique identifier for the charge in Lago.
96 pub lago_id: Option<Uuid>,
97 /// The Lago ID of the billable metric.
98 pub lago_billable_metric_id: Option<Uuid>,
99 /// The billable metric ID to reference.
100 pub billable_metric_id: Option<Uuid>,
101 /// When the charge was created.
102 pub created_at: Option<DateTime<Utc>>,
103 /// The charge model to use.
104 pub charge_model: ChargeModel,
105 /// Whether the charge is invoiceable.
106 pub invoiceable: Option<bool>,
107 /// Display name for the charge on invoices.
108 pub invoice_display_name: Option<String>,
109 /// Whether the charge is billed in advance.
110 pub pay_in_advance: Option<bool>,
111 /// Whether the charge is prorated.
112 pub prorated: Option<bool>,
113 /// Minimum amount in cents for this charge.
114 pub min_amount_cents: Option<i64>,
115 /// Charge properties (model-specific configuration).
116 pub properties: Option<serde_json::Value>,
117 /// Tax codes for this charge.
118 pub tax_codes: Option<Vec<String>>,
119 /// Taxes applied to this charge.
120 pub taxes: Option<Vec<PlanTax>>,
121 /// Filters for differentiated pricing.
122 pub filters: Option<Vec<ChargeFilter>>,
123 /// The regroup paid fees option.
124 pub regroup_paid_fees: Option<String>,
125}
126
127/// Represents a charge filter for differentiated pricing.
128#[derive(Debug, Clone, Serialize, Deserialize)]
129pub struct ChargeFilter {
130 /// Invoice display name for this filter.
131 pub invoice_display_name: Option<String>,
132 /// Filter properties.
133 pub properties: Option<serde_json::Value>,
134 /// Filter values mapping.
135 pub values: Option<serde_json::Value>,
136}
137
138/// Represents a tax applied to a plan or charge.
139#[derive(Debug, Clone, Serialize, Deserialize)]
140pub struct PlanTax {
141 /// Unique identifier for the tax in Lago.
142 pub lago_id: Option<Uuid>,
143 /// Name of the tax.
144 pub name: Option<String>,
145 /// Code for the tax.
146 pub code: Option<String>,
147 /// Tax rate as a string (percentage).
148 pub rate: Option<String>,
149 /// Description of the tax.
150 pub description: Option<String>,
151 /// Whether tax is applied by default.
152 pub applied_to_organization: Option<bool>,
153}
154
155/// Minimum commitment for a plan.
156#[derive(Debug, Clone, Serialize, Deserialize)]
157pub struct PlanMinimumCommitment {
158 /// Unique identifier in Lago.
159 pub lago_id: Option<Uuid>,
160 /// Plan ID this commitment belongs to.
161 pub plan_code: Option<String>,
162 /// Minimum commitment amount in cents.
163 pub amount_cents: Option<i64>,
164 /// Invoice display name for the minimum commitment.
165 pub invoice_display_name: Option<String>,
166 /// When the commitment was created.
167 pub created_at: Option<DateTime<Utc>>,
168 /// When the commitment was last updated.
169 pub updated_at: Option<DateTime<Utc>>,
170 /// Tax codes for the minimum commitment.
171 pub tax_codes: Option<Vec<String>>,
172 /// Taxes applied to the minimum commitment.
173 pub taxes: Option<Vec<PlanTax>>,
174}