lago_types/requests/
subscription.rs

1use serde::{Deserialize, Serialize};
2
3use crate::filters::common::ListFilters;
4use crate::filters::subscription::SubscriptionFilters;
5use crate::models::{PaginationParams, SubscriptionBillingTime};
6
7/// Request parameters for listing subscriptions.
8#[derive(Debug, Clone)]
9pub struct ListSubscriptionsRequest {
10    pub pagination: PaginationParams,
11    pub filters: SubscriptionFilters,
12}
13
14impl ListSubscriptionsRequest {
15    /// Creates a new empty list subscriptions request.
16    pub fn new() -> Self {
17        Self {
18            pagination: PaginationParams::default(),
19            filters: SubscriptionFilters::default(),
20        }
21    }
22
23    /// Sets the pagination parameters for the request.
24    pub fn with_pagination(mut self, pagination: PaginationParams) -> Self {
25        self.pagination = pagination;
26        self
27    }
28
29    /// Sets the subscription filters for the request.
30    pub fn with_filters(mut self, filters: SubscriptionFilters) -> Self {
31        self.filters = filters;
32        self
33    }
34
35    /// Converts the request parameters into HTTP query parameters.
36    pub fn to_query_params(&self) -> Vec<(&str, String)> {
37        let mut params = self.pagination.to_query_params();
38        params.extend(self.filters.to_query_params());
39        params
40    }
41}
42
43impl Default for ListSubscriptionsRequest {
44    fn default() -> Self {
45        Self::new()
46    }
47}
48
49/// Request parameters for retrieving a specific subscription.
50#[derive(Debug, Clone)]
51pub struct GetSubscriptionRequest {
52    /// The external unique identifier of the subscription.
53    pub external_id: String,
54}
55
56impl GetSubscriptionRequest {
57    /// Creates a new get subscription request.
58    pub fn new(external_id: String) -> Self {
59        Self { external_id }
60    }
61}
62
63/// Request parameters for listing a customer's subscriptions.
64#[derive(Debug, Clone)]
65pub struct ListCustomerSubscriptionsRequest {
66    /// The external unique identifier of the customer.
67    pub external_customer_id: String,
68    pub pagination: PaginationParams,
69    pub filters: SubscriptionFilters,
70}
71
72impl ListCustomerSubscriptionsRequest {
73    /// Creates a new list customer subscriptions request.
74    pub fn new(external_customer_id: String) -> Self {
75        Self {
76            external_customer_id,
77            pagination: PaginationParams::default(),
78            filters: SubscriptionFilters::default(),
79        }
80    }
81
82    /// Sets the pagination parameters for the request.
83    pub fn with_pagination(mut self, pagination: PaginationParams) -> Self {
84        self.pagination = pagination;
85        self
86    }
87
88    /// Sets the subscription filters for the request.
89    pub fn with_filters(mut self, filters: SubscriptionFilters) -> Self {
90        self.filters = filters;
91        self
92    }
93
94    /// Converts the request parameters into HTTP query parameters.
95    pub fn to_query_params(&self) -> Vec<(&str, String)> {
96        let mut params = self.pagination.to_query_params();
97        params.extend(self.filters.to_query_params());
98        params
99    }
100}
101
102/// Input data for creating a subscription.
103#[derive(Debug, Clone, Serialize, Deserialize)]
104pub struct CreateSubscriptionInput {
105    /// External unique identifier for the customer.
106    pub external_customer_id: String,
107    /// Code of the plan to assign to the subscription.
108    pub plan_code: String,
109    /// Optional display name for the subscription.
110    #[serde(skip_serializing_if = "Option::is_none")]
111    pub name: Option<String>,
112    /// Optional external unique identifier for the subscription.
113    #[serde(skip_serializing_if = "Option::is_none")]
114    pub external_id: Option<String>,
115    /// Billing time determines when recurring billing cycles occur.
116    #[serde(skip_serializing_if = "Option::is_none")]
117    pub billing_time: Option<SubscriptionBillingTime>,
118    /// The subscription start date (ISO 8601 format).
119    #[serde(skip_serializing_if = "Option::is_none")]
120    pub subscription_at: Option<String>,
121    /// The subscription end date (ISO 8601 format).
122    #[serde(skip_serializing_if = "Option::is_none")]
123    pub ending_at: Option<String>,
124    /// Plan overrides to customize the plan for this subscription.
125    #[serde(skip_serializing_if = "Option::is_none")]
126    pub plan_overrides: Option<SubscriptionPlanOverrides>,
127}
128
129impl CreateSubscriptionInput {
130    /// Creates a new subscription input with required fields.
131    pub fn new(external_customer_id: String, plan_code: String) -> Self {
132        Self {
133            external_customer_id,
134            plan_code,
135            name: None,
136            external_id: None,
137            billing_time: None,
138            subscription_at: None,
139            ending_at: None,
140            plan_overrides: None,
141        }
142    }
143
144    /// Sets the subscription name.
145    pub fn with_name(mut self, name: String) -> Self {
146        self.name = Some(name);
147        self
148    }
149
150    /// Sets the external ID.
151    pub fn with_external_id(mut self, external_id: String) -> Self {
152        self.external_id = Some(external_id);
153        self
154    }
155
156    /// Sets the billing time.
157    pub fn with_billing_time(mut self, billing_time: SubscriptionBillingTime) -> Self {
158        self.billing_time = Some(billing_time);
159        self
160    }
161
162    /// Sets the subscription start date.
163    pub fn with_subscription_at(mut self, subscription_at: String) -> Self {
164        self.subscription_at = Some(subscription_at);
165        self
166    }
167
168    /// Sets the subscription end date.
169    pub fn with_ending_at(mut self, ending_at: String) -> Self {
170        self.ending_at = Some(ending_at);
171        self
172    }
173
174    /// Sets plan overrides.
175    pub fn with_plan_overrides(mut self, plan_overrides: SubscriptionPlanOverrides) -> Self {
176        self.plan_overrides = Some(plan_overrides);
177        self
178    }
179}
180
181/// Request for creating a subscription.
182#[derive(Debug, Clone, Serialize)]
183pub struct CreateSubscriptionRequest {
184    pub subscription: CreateSubscriptionInput,
185}
186
187impl CreateSubscriptionRequest {
188    /// Creates a new create subscription request.
189    pub fn new(input: CreateSubscriptionInput) -> Self {
190        Self {
191            subscription: input,
192        }
193    }
194}
195
196/// Input data for updating a subscription.
197#[derive(Debug, Clone, Serialize, Deserialize)]
198pub struct UpdateSubscriptionInput {
199    /// Optional new name for the subscription.
200    #[serde(skip_serializing_if = "Option::is_none")]
201    pub name: Option<String>,
202    /// Optional new end date for the subscription.
203    #[serde(skip_serializing_if = "Option::is_none")]
204    pub ending_at: Option<String>,
205    /// Optional new plan code (for plan changes).
206    #[serde(skip_serializing_if = "Option::is_none")]
207    pub plan_code: Option<String>,
208    /// Optional new subscription date.
209    #[serde(skip_serializing_if = "Option::is_none")]
210    pub subscription_at: Option<String>,
211    /// Plan overrides to customize the plan for this subscription.
212    #[serde(skip_serializing_if = "Option::is_none")]
213    pub plan_overrides: Option<SubscriptionPlanOverrides>,
214}
215
216impl UpdateSubscriptionInput {
217    /// Creates a new empty update subscription input.
218    pub fn new() -> Self {
219        Self {
220            name: None,
221            ending_at: None,
222            plan_code: None,
223            subscription_at: None,
224            plan_overrides: None,
225        }
226    }
227
228    /// Sets the subscription name.
229    pub fn with_name(mut self, name: String) -> Self {
230        self.name = Some(name);
231        self
232    }
233
234    /// Sets the subscription end date.
235    pub fn with_ending_at(mut self, ending_at: String) -> Self {
236        self.ending_at = Some(ending_at);
237        self
238    }
239
240    /// Sets the plan code (for plan changes).
241    pub fn with_plan_code(mut self, plan_code: String) -> Self {
242        self.plan_code = Some(plan_code);
243        self
244    }
245
246    /// Sets the subscription date.
247    pub fn with_subscription_at(mut self, subscription_at: String) -> Self {
248        self.subscription_at = Some(subscription_at);
249        self
250    }
251
252    /// Sets plan overrides.
253    pub fn with_plan_overrides(mut self, plan_overrides: SubscriptionPlanOverrides) -> Self {
254        self.plan_overrides = Some(plan_overrides);
255        self
256    }
257}
258
259impl Default for UpdateSubscriptionInput {
260    fn default() -> Self {
261        Self::new()
262    }
263}
264
265/// Request for updating a subscription.
266#[derive(Debug, Clone, Serialize)]
267pub struct UpdateSubscriptionRequest {
268    /// The external unique identifier of the subscription to update.
269    #[serde(skip)]
270    pub external_id: String,
271    /// The subscription update data.
272    pub subscription: UpdateSubscriptionInput,
273}
274
275impl UpdateSubscriptionRequest {
276    /// Creates a new update subscription request.
277    pub fn new(external_id: String, input: UpdateSubscriptionInput) -> Self {
278        Self {
279            external_id,
280            subscription: input,
281        }
282    }
283}
284
285/// Request for deleting a subscription.
286#[derive(Debug, Clone)]
287pub struct DeleteSubscriptionRequest {
288    /// The external unique identifier of the subscription to delete.
289    pub external_id: String,
290    /// Optional status to set the subscription to (defaults to terminated).
291    pub status: Option<String>,
292}
293
294impl DeleteSubscriptionRequest {
295    /// Creates a new delete subscription request.
296    pub fn new(external_id: String) -> Self {
297        Self {
298            external_id,
299            status: None,
300        }
301    }
302
303    /// Sets the target status for the subscription.
304    pub fn with_status(mut self, status: String) -> Self {
305        self.status = Some(status);
306        self
307    }
308
309    /// Converts the request parameters into HTTP query parameters.
310    pub fn to_query_params(&self) -> Vec<(&str, String)> {
311        let mut params = Vec::new();
312        if let Some(status) = &self.status {
313            params.push(("status", status.clone()));
314        }
315        params
316    }
317}
318
319/// Plan overrides to customize a plan for a specific subscription.
320#[derive(Debug, Clone, Serialize, Deserialize, Default)]
321pub struct SubscriptionPlanOverrides {
322    /// Override the base amount in cents.
323    #[serde(skip_serializing_if = "Option::is_none")]
324    pub amount_cents: Option<i64>,
325    /// Override the currency.
326    #[serde(skip_serializing_if = "Option::is_none")]
327    pub amount_currency: Option<String>,
328    /// Override the plan description.
329    #[serde(skip_serializing_if = "Option::is_none")]
330    pub description: Option<String>,
331    /// Override the invoice display name.
332    #[serde(skip_serializing_if = "Option::is_none")]
333    pub invoice_display_name: Option<String>,
334    /// Override the plan name.
335    #[serde(skip_serializing_if = "Option::is_none")]
336    pub name: Option<String>,
337    /// Override the tax codes.
338    #[serde(skip_serializing_if = "Option::is_none")]
339    pub tax_codes: Option<Vec<String>>,
340    /// Override the trial period in days.
341    #[serde(skip_serializing_if = "Option::is_none")]
342    pub trial_period: Option<f64>,
343    /// Override the minimum commitment.
344    #[serde(skip_serializing_if = "Option::is_none")]
345    pub minimum_commitment: Option<SubscriptionMinimumCommitmentOverride>,
346    /// Override specific charges.
347    #[serde(skip_serializing_if = "Option::is_none")]
348    pub charges: Option<Vec<SubscriptionChargeOverride>>,
349}
350
351impl SubscriptionPlanOverrides {
352    /// Creates a new empty plan overrides object.
353    pub fn new() -> Self {
354        Self::default()
355    }
356
357    /// Sets the amount in cents override.
358    pub fn with_amount_cents(mut self, amount_cents: i64) -> Self {
359        self.amount_cents = Some(amount_cents);
360        self
361    }
362
363    /// Sets the currency override.
364    pub fn with_amount_currency(mut self, currency: String) -> Self {
365        self.amount_currency = Some(currency);
366        self
367    }
368
369    /// Sets the description override.
370    pub fn with_description(mut self, description: String) -> Self {
371        self.description = Some(description);
372        self
373    }
374
375    /// Sets the invoice display name override.
376    pub fn with_invoice_display_name(mut self, name: String) -> Self {
377        self.invoice_display_name = Some(name);
378        self
379    }
380
381    /// Sets the name override.
382    pub fn with_name(mut self, name: String) -> Self {
383        self.name = Some(name);
384        self
385    }
386
387    /// Sets the trial period override.
388    pub fn with_trial_period(mut self, days: f64) -> Self {
389        self.trial_period = Some(days);
390        self
391    }
392}
393
394/// Minimum commitment override for a subscription.
395#[derive(Debug, Clone, Serialize, Deserialize)]
396pub struct SubscriptionMinimumCommitmentOverride {
397    /// Minimum commitment amount in cents.
398    #[serde(skip_serializing_if = "Option::is_none")]
399    pub amount_cents: Option<i64>,
400    /// Invoice display name for the minimum commitment.
401    #[serde(skip_serializing_if = "Option::is_none")]
402    pub invoice_display_name: Option<String>,
403    /// Tax codes for the minimum commitment.
404    #[serde(skip_serializing_if = "Option::is_none")]
405    pub tax_codes: Option<Vec<String>>,
406}
407
408/// Charge override for a subscription.
409#[derive(Debug, Clone, Serialize, Deserialize)]
410pub struct SubscriptionChargeOverride {
411    /// The ID of the charge to override.
412    pub id: String,
413    /// Override the billable metric ID.
414    #[serde(skip_serializing_if = "Option::is_none")]
415    pub billable_metric_id: Option<String>,
416    /// Override the invoice display name.
417    #[serde(skip_serializing_if = "Option::is_none")]
418    pub invoice_display_name: Option<String>,
419    /// Override the minimum amount in cents.
420    #[serde(skip_serializing_if = "Option::is_none")]
421    pub min_amount_cents: Option<i64>,
422    /// Override tax codes for this charge.
423    #[serde(skip_serializing_if = "Option::is_none")]
424    pub tax_codes: Option<Vec<String>>,
425    /// Override the pricing properties.
426    #[serde(skip_serializing_if = "Option::is_none")]
427    pub properties: Option<serde_json::Value>,
428}
lago_types/requests/subscription.rs

lago_types/requests/
subscription.rs
