stripe/resources/generated/subscription_item.rs
1// ======================================
2// This file was automatically generated.
3// ======================================
4
5use crate::client::{Client, Response};
6use crate::ids::{PlanId, PriceId, SubscriptionId, SubscriptionItemId};
7use crate::params::{Deleted, Expand, List, Metadata, Object, Paginable, Timestamp};
8use crate::resources::{Currency, Plan, Price, SubscriptionItemBillingThresholds, TaxRate};
9use serde::{Deserialize, Serialize};
10
11/// The resource representing a Stripe "SubscriptionItem".
12///
13/// For more details see <https://stripe.com/docs/api/subscription_items/object>
14#[derive(Clone, Debug, Default, Deserialize, Serialize)]
15pub struct SubscriptionItem {
16 /// Unique identifier for the object.
17 pub id: SubscriptionItemId,
18
19 /// Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period.
20 #[serde(skip_serializing_if = "Option::is_none")]
21 pub billing_thresholds: Option<SubscriptionItemBillingThresholds>,
22
23 /// Time at which the object was created.
24 ///
25 /// Measured in seconds since the Unix epoch.
26 #[serde(skip_serializing_if = "Option::is_none")]
27 pub created: Option<Timestamp>,
28
29 // Always true for a deleted object
30 #[serde(default)]
31 pub deleted: bool,
32
33 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
34 ///
35 /// This can be useful for storing additional information about the object in a structured format.
36 #[serde(skip_serializing_if = "Option::is_none")]
37 pub metadata: Option<Metadata>,
38
39 #[serde(skip_serializing_if = "Option::is_none")]
40 pub plan: Option<Plan>,
41
42 #[serde(skip_serializing_if = "Option::is_none")]
43 pub price: Option<Price>,
44
45 /// The [quantity](https://stripe.com/docs/subscriptions/quantities) of the plan to which the customer should be subscribed.
46 #[serde(skip_serializing_if = "Option::is_none")]
47 pub quantity: Option<u64>,
48
49 /// The `subscription` this `subscription_item` belongs to.
50 #[serde(skip_serializing_if = "Option::is_none")]
51 pub subscription: Option<String>,
52
53 /// The tax rates which apply to this `subscription_item`.
54 ///
55 /// When set, the `default_tax_rates` on the subscription do not apply to this `subscription_item`.
56 #[serde(skip_serializing_if = "Option::is_none")]
57 pub tax_rates: Option<Vec<TaxRate>>,
58}
59
60impl SubscriptionItem {
61 /// Returns a list of your subscription items for a given subscription.
62 pub fn list(
63 client: &Client,
64 params: &ListSubscriptionItems<'_>,
65 ) -> Response<List<SubscriptionItem>> {
66 client.get_query("/subscription_items", params)
67 }
68
69 /// Adds a new item to an existing subscription.
70 ///
71 /// No existing items will be changed or replaced.
72 pub fn create(
73 client: &Client,
74 params: CreateSubscriptionItem<'_>,
75 ) -> Response<SubscriptionItem> {
76 #[allow(clippy::needless_borrows_for_generic_args)]
77 client.post_form("/subscription_items", ¶ms)
78 }
79
80 /// Retrieves the subscription item with the given ID.
81 pub fn retrieve(
82 client: &Client,
83 id: &SubscriptionItemId,
84 expand: &[&str],
85 ) -> Response<SubscriptionItem> {
86 client.get_query(&format!("/subscription_items/{}", id), Expand { expand })
87 }
88
89 /// Updates the plan or quantity of an item on a current subscription.
90 pub fn update(
91 client: &Client,
92 id: &SubscriptionItemId,
93 params: UpdateSubscriptionItem<'_>,
94 ) -> Response<SubscriptionItem> {
95 #[allow(clippy::needless_borrows_for_generic_args)]
96 client.post_form(&format!("/subscription_items/{}", id), ¶ms)
97 }
98
99 /// Deletes an item from the subscription.
100 ///
101 /// Removing a subscription item from a subscription will not cancel the subscription.
102 pub fn delete(
103 client: &Client,
104 id: &SubscriptionItemId,
105 ) -> Response<Deleted<SubscriptionItemId>> {
106 client.delete(&format!("/subscription_items/{}", id))
107 }
108}
109
110impl Object for SubscriptionItem {
111 type Id = SubscriptionItemId;
112 fn id(&self) -> Self::Id {
113 self.id.clone()
114 }
115 fn object(&self) -> &'static str {
116 "subscription_item"
117 }
118}
119
120/// The parameters for `SubscriptionItem::create`.
121#[derive(Clone, Debug, Serialize)]
122pub struct CreateSubscriptionItem<'a> {
123 /// Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period.
124 ///
125 /// When updating, pass an empty string to remove previously-defined thresholds.
126 #[serde(skip_serializing_if = "Option::is_none")]
127 pub billing_thresholds: Option<SubscriptionItemBillingThresholds>,
128
129 /// Specifies which fields in the response should be expanded.
130 #[serde(skip_serializing_if = "Expand::is_empty")]
131 pub expand: &'a [&'a str],
132
133 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
134 ///
135 /// This can be useful for storing additional information about the object in a structured format.
136 /// Individual keys can be unset by posting an empty value to them.
137 /// All keys can be unset by posting an empty value to `metadata`.
138 #[serde(skip_serializing_if = "Option::is_none")]
139 pub metadata: Option<Metadata>,
140
141 /// Use `allow_incomplete` to transition the subscription to `status=past_due` if a payment is required but cannot be paid.
142 ///
143 /// This allows you to manage scenarios where additional user actions are needed to pay a subscription's invoice.
144 /// For example, SCA regulation may require 3DS authentication to complete payment.
145 /// See the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication) for Billing to learn more.
146 /// This is the default behavior. Use `default_incomplete` to transition the subscription to `status=past_due` when payment is required and await explicit confirmation of the invoice's payment intent.
147 /// This allows simpler management of scenarios where additional user actions are needed to pay a subscription’s invoice.
148 /// Such as failed payments, [SCA regulation](https://stripe.com/docs/billing/migration/strong-customer-authentication), or collecting a mandate for a bank debit payment method. Use `pending_if_incomplete` to update the subscription using [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates).
149 /// When you use `pending_if_incomplete` you can only pass the parameters [supported by pending updates](https://stripe.com/docs/billing/pending-updates-reference#supported-attributes). Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's invoice cannot be paid.
150 /// For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead.
151 /// This was the default behavior for API versions prior to 2019-03-14.
152 /// See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
153 #[serde(skip_serializing_if = "Option::is_none")]
154 pub payment_behavior: Option<SubscriptionPaymentBehavior>,
155
156 /// The identifier of the plan to add to the subscription.
157 #[serde(skip_serializing_if = "Option::is_none")]
158 pub plan: Option<PlanId>,
159
160 /// The ID of the price object.
161 #[serde(skip_serializing_if = "Option::is_none")]
162 pub price: Option<PriceId>,
163
164 /// Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline.
165 #[serde(skip_serializing_if = "Option::is_none")]
166 pub price_data: Option<SubscriptionItemPriceData>,
167
168 /// Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes.
169 ///
170 /// The default value is `create_prorations`.
171 #[serde(skip_serializing_if = "Option::is_none")]
172 pub proration_behavior: Option<SubscriptionProrationBehavior>,
173
174 /// If set, the proration will be calculated as though the subscription was updated at the given time.
175 ///
176 /// This can be used to apply the same proration that was previewed with the [upcoming invoice](https://stripe.com/docs/api#retrieve_customer_invoice) endpoint.
177 #[serde(skip_serializing_if = "Option::is_none")]
178 pub proration_date: Option<Timestamp>,
179
180 /// The quantity you'd like to apply to the subscription item you're creating.
181 #[serde(skip_serializing_if = "Option::is_none")]
182 pub quantity: Option<u64>,
183
184 /// The identifier of the subscription to modify.
185 pub subscription: SubscriptionId,
186
187 /// A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids.
188 ///
189 /// These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription.
190 /// When updating, pass an empty string to remove previously-defined tax rates.
191 #[serde(skip_serializing_if = "Option::is_none")]
192 pub tax_rates: Option<Vec<String>>,
193}
194
195impl<'a> CreateSubscriptionItem<'a> {
196 pub fn new(subscription: SubscriptionId) -> Self {
197 CreateSubscriptionItem {
198 billing_thresholds: Default::default(),
199 expand: Default::default(),
200 metadata: Default::default(),
201 payment_behavior: Default::default(),
202 plan: Default::default(),
203 price: Default::default(),
204 price_data: Default::default(),
205 proration_behavior: Default::default(),
206 proration_date: Default::default(),
207 quantity: Default::default(),
208 subscription,
209 tax_rates: Default::default(),
210 }
211 }
212}
213
214/// The parameters for `SubscriptionItem::list`.
215#[derive(Clone, Debug, Serialize)]
216pub struct ListSubscriptionItems<'a> {
217 /// A cursor for use in pagination.
218 ///
219 /// `ending_before` is an object ID that defines your place in the list.
220 /// For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
221 #[serde(skip_serializing_if = "Option::is_none")]
222 pub ending_before: Option<SubscriptionItemId>,
223
224 /// Specifies which fields in the response should be expanded.
225 #[serde(skip_serializing_if = "Expand::is_empty")]
226 pub expand: &'a [&'a str],
227
228 /// A limit on the number of objects to be returned.
229 ///
230 /// Limit can range between 1 and 100, and the default is 10.
231 #[serde(skip_serializing_if = "Option::is_none")]
232 pub limit: Option<u64>,
233
234 /// A cursor for use in pagination.
235 ///
236 /// `starting_after` is an object ID that defines your place in the list.
237 /// For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
238 #[serde(skip_serializing_if = "Option::is_none")]
239 pub starting_after: Option<SubscriptionItemId>,
240
241 /// The ID of the subscription whose items will be retrieved.
242 pub subscription: SubscriptionId,
243}
244
245impl<'a> ListSubscriptionItems<'a> {
246 pub fn new(subscription: SubscriptionId) -> Self {
247 ListSubscriptionItems {
248 ending_before: Default::default(),
249 expand: Default::default(),
250 limit: Default::default(),
251 starting_after: Default::default(),
252 subscription,
253 }
254 }
255}
256impl Paginable for ListSubscriptionItems<'_> {
257 type O = SubscriptionItem;
258 fn set_last(&mut self, item: Self::O) {
259 self.starting_after = Some(item.id());
260 }
261}
262/// The parameters for `SubscriptionItem::update`.
263#[derive(Clone, Debug, Serialize, Default)]
264pub struct UpdateSubscriptionItem<'a> {
265 /// Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period.
266 ///
267 /// When updating, pass an empty string to remove previously-defined thresholds.
268 #[serde(skip_serializing_if = "Option::is_none")]
269 pub billing_thresholds: Option<SubscriptionItemBillingThresholds>,
270
271 /// Specifies which fields in the response should be expanded.
272 #[serde(skip_serializing_if = "Expand::is_empty")]
273 pub expand: &'a [&'a str],
274
275 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
276 ///
277 /// This can be useful for storing additional information about the object in a structured format.
278 /// Individual keys can be unset by posting an empty value to them.
279 /// All keys can be unset by posting an empty value to `metadata`.
280 #[serde(skip_serializing_if = "Option::is_none")]
281 pub metadata: Option<Metadata>,
282
283 /// Indicates if a customer is on or off-session while an invoice payment is attempted.
284 #[serde(skip_serializing_if = "Option::is_none")]
285 pub off_session: Option<bool>,
286
287 /// Use `allow_incomplete` to transition the subscription to `status=past_due` if a payment is required but cannot be paid.
288 ///
289 /// This allows you to manage scenarios where additional user actions are needed to pay a subscription's invoice.
290 /// For example, SCA regulation may require 3DS authentication to complete payment.
291 /// See the [SCA Migration Guide](https://stripe.com/docs/billing/migration/strong-customer-authentication) for Billing to learn more.
292 /// This is the default behavior. Use `default_incomplete` to transition the subscription to `status=past_due` when payment is required and await explicit confirmation of the invoice's payment intent.
293 /// This allows simpler management of scenarios where additional user actions are needed to pay a subscription’s invoice.
294 /// Such as failed payments, [SCA regulation](https://stripe.com/docs/billing/migration/strong-customer-authentication), or collecting a mandate for a bank debit payment method. Use `pending_if_incomplete` to update the subscription using [pending updates](https://stripe.com/docs/billing/subscriptions/pending-updates).
295 /// When you use `pending_if_incomplete` you can only pass the parameters [supported by pending updates](https://stripe.com/docs/billing/pending-updates-reference#supported-attributes). Use `error_if_incomplete` if you want Stripe to return an HTTP 402 status code if a subscription's invoice cannot be paid.
296 /// For example, if a payment method requires 3DS authentication due to SCA regulation and further user action is needed, this parameter does not update the subscription and returns an error instead.
297 /// This was the default behavior for API versions prior to 2019-03-14.
298 /// See the [changelog](https://stripe.com/docs/upgrades#2019-03-14) to learn more.
299 #[serde(skip_serializing_if = "Option::is_none")]
300 pub payment_behavior: Option<SubscriptionPaymentBehavior>,
301
302 /// The identifier of the new plan for this subscription item.
303 #[serde(skip_serializing_if = "Option::is_none")]
304 pub plan: Option<PlanId>,
305
306 /// The ID of the price object.
307 ///
308 /// When changing a subscription item's price, `quantity` is set to 1 unless a `quantity` parameter is provided.
309 #[serde(skip_serializing_if = "Option::is_none")]
310 pub price: Option<PriceId>,
311
312 /// Data used to generate a new [Price](https://stripe.com/docs/api/prices) object inline.
313 #[serde(skip_serializing_if = "Option::is_none")]
314 pub price_data: Option<SubscriptionItemPriceData>,
315
316 /// Determines how to handle [prorations](https://stripe.com/docs/subscriptions/billing-cycle#prorations) when the billing cycle changes (e.g., when switching plans, resetting `billing_cycle_anchor=now`, or starting a trial), or if an item's `quantity` changes.
317 ///
318 /// The default value is `create_prorations`.
319 #[serde(skip_serializing_if = "Option::is_none")]
320 pub proration_behavior: Option<SubscriptionProrationBehavior>,
321
322 /// If set, the proration will be calculated as though the subscription was updated at the given time.
323 ///
324 /// This can be used to apply the same proration that was previewed with the [upcoming invoice](https://stripe.com/docs/api#retrieve_customer_invoice) endpoint.
325 #[serde(skip_serializing_if = "Option::is_none")]
326 pub proration_date: Option<Timestamp>,
327
328 /// The quantity you'd like to apply to the subscription item you're creating.
329 #[serde(skip_serializing_if = "Option::is_none")]
330 pub quantity: Option<u64>,
331
332 /// A list of [Tax Rate](https://stripe.com/docs/api/tax_rates) ids.
333 ///
334 /// These Tax Rates will override the [`default_tax_rates`](https://stripe.com/docs/api/subscriptions/create#create_subscription-default_tax_rates) on the Subscription.
335 /// When updating, pass an empty string to remove previously-defined tax rates.
336 #[serde(skip_serializing_if = "Option::is_none")]
337 pub tax_rates: Option<Vec<String>>,
338}
339
340impl<'a> UpdateSubscriptionItem<'a> {
341 pub fn new() -> Self {
342 UpdateSubscriptionItem {
343 billing_thresholds: Default::default(),
344 expand: Default::default(),
345 metadata: Default::default(),
346 off_session: Default::default(),
347 payment_behavior: Default::default(),
348 plan: Default::default(),
349 price: Default::default(),
350 price_data: Default::default(),
351 proration_behavior: Default::default(),
352 proration_date: Default::default(),
353 quantity: Default::default(),
354 tax_rates: Default::default(),
355 }
356 }
357}
358
359#[derive(Clone, Debug, Default, Deserialize, Serialize)]
360pub struct SubscriptionItemPriceData {
361 /// Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase.
362 ///
363 /// Must be a [supported currency](https://stripe.com/docs/currencies).
364 pub currency: Currency,
365
366 /// The ID of the product that this price will belong to.
367 pub product: String,
368
369 /// The recurring components of a price such as `interval` and `interval_count`.
370 pub recurring: SubscriptionItemPriceDataRecurring,
371
372 /// Only required if a [default tax behavior](https://stripe.com/docs/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) was not provided in the Stripe Tax settings.
373 ///
374 /// Specifies whether the price is considered inclusive of taxes or exclusive of taxes.
375 /// One of `inclusive`, `exclusive`, or `unspecified`.
376 /// Once specified as either `inclusive` or `exclusive`, it cannot be changed.
377 #[serde(skip_serializing_if = "Option::is_none")]
378 pub tax_behavior: Option<SubscriptionItemPriceDataTaxBehavior>,
379
380 /// A positive integer in cents (or local equivalent) (or 0 for a free price) representing how much to charge.
381 #[serde(skip_serializing_if = "Option::is_none")]
382 pub unit_amount: Option<i64>,
383
384 /// Same as `unit_amount`, but accepts a decimal value in cents (or local equivalent) with at most 12 decimal places.
385 ///
386 /// Only one of `unit_amount` and `unit_amount_decimal` can be set.
387 #[serde(skip_serializing_if = "Option::is_none")]
388 pub unit_amount_decimal: Option<String>,
389}
390
391#[derive(Clone, Debug, Default, Deserialize, Serialize)]
392pub struct SubscriptionItemPriceDataRecurring {
393 /// Specifies billing frequency.
394 ///
395 /// Either `day`, `week`, `month` or `year`.
396 pub interval: PlanInterval,
397
398 /// The number of intervals between subscription billings.
399 ///
400 /// For example, `interval=month` and `interval_count=3` bills every 3 months.
401 /// Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).
402 #[serde(skip_serializing_if = "Option::is_none")]
403 pub interval_count: Option<u64>,
404}
405
406/// An enum representing the possible values of an `SubscriptionItemPriceDataRecurring`'s `interval` field.
407#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
408#[serde(rename_all = "snake_case")]
409pub enum PlanInterval {
410 Day,
411 Month,
412 Week,
413 Year,
414}
415
416impl PlanInterval {
417 pub fn as_str(self) -> &'static str {
418 match self {
419 PlanInterval::Day => "day",
420 PlanInterval::Month => "month",
421 PlanInterval::Week => "week",
422 PlanInterval::Year => "year",
423 }
424 }
425}
426
427impl AsRef<str> for PlanInterval {
428 fn as_ref(&self) -> &str {
429 self.as_str()
430 }
431}
432
433impl std::fmt::Display for PlanInterval {
434 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
435 self.as_str().fmt(f)
436 }
437}
438impl std::default::Default for PlanInterval {
439 fn default() -> Self {
440 Self::Day
441 }
442}
443
444/// An enum representing the possible values of an `SubscriptionItemPriceData`'s `tax_behavior` field.
445#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
446#[serde(rename_all = "snake_case")]
447pub enum SubscriptionItemPriceDataTaxBehavior {
448 Exclusive,
449 Inclusive,
450 Unspecified,
451}
452
453impl SubscriptionItemPriceDataTaxBehavior {
454 pub fn as_str(self) -> &'static str {
455 match self {
456 SubscriptionItemPriceDataTaxBehavior::Exclusive => "exclusive",
457 SubscriptionItemPriceDataTaxBehavior::Inclusive => "inclusive",
458 SubscriptionItemPriceDataTaxBehavior::Unspecified => "unspecified",
459 }
460 }
461}
462
463impl AsRef<str> for SubscriptionItemPriceDataTaxBehavior {
464 fn as_ref(&self) -> &str {
465 self.as_str()
466 }
467}
468
469impl std::fmt::Display for SubscriptionItemPriceDataTaxBehavior {
470 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
471 self.as_str().fmt(f)
472 }
473}
474impl std::default::Default for SubscriptionItemPriceDataTaxBehavior {
475 fn default() -> Self {
476 Self::Exclusive
477 }
478}
479
480/// An enum representing the possible values of an `CreateSubscriptionItem`'s `payment_behavior` field.
481#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
482#[serde(rename_all = "snake_case")]
483pub enum SubscriptionPaymentBehavior {
484 AllowIncomplete,
485 DefaultIncomplete,
486 ErrorIfIncomplete,
487 PendingIfIncomplete,
488}
489
490impl SubscriptionPaymentBehavior {
491 pub fn as_str(self) -> &'static str {
492 match self {
493 SubscriptionPaymentBehavior::AllowIncomplete => "allow_incomplete",
494 SubscriptionPaymentBehavior::DefaultIncomplete => "default_incomplete",
495 SubscriptionPaymentBehavior::ErrorIfIncomplete => "error_if_incomplete",
496 SubscriptionPaymentBehavior::PendingIfIncomplete => "pending_if_incomplete",
497 }
498 }
499}
500
501impl AsRef<str> for SubscriptionPaymentBehavior {
502 fn as_ref(&self) -> &str {
503 self.as_str()
504 }
505}
506
507impl std::fmt::Display for SubscriptionPaymentBehavior {
508 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
509 self.as_str().fmt(f)
510 }
511}
512impl std::default::Default for SubscriptionPaymentBehavior {
513 fn default() -> Self {
514 Self::AllowIncomplete
515 }
516}
517
518/// An enum representing the possible values of an `CreateSubscriptionItem`'s `proration_behavior` field.
519#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
520#[serde(rename_all = "snake_case")]
521pub enum SubscriptionProrationBehavior {
522 AlwaysInvoice,
523 CreateProrations,
524 None,
525}
526
527impl SubscriptionProrationBehavior {
528 pub fn as_str(self) -> &'static str {
529 match self {
530 SubscriptionProrationBehavior::AlwaysInvoice => "always_invoice",
531 SubscriptionProrationBehavior::CreateProrations => "create_prorations",
532 SubscriptionProrationBehavior::None => "none",
533 }
534 }
535}
536
537impl AsRef<str> for SubscriptionProrationBehavior {
538 fn as_ref(&self) -> &str {
539 self.as_str()
540 }
541}
542
543impl std::fmt::Display for SubscriptionProrationBehavior {
544 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
545 self.as_str().fmt(f)
546 }
547}
548impl std::default::Default for SubscriptionProrationBehavior {
549 fn default() -> Self {
550 Self::AlwaysInvoice
551 }
552}