stripe/resources/generated/tax_rate.rs
1// ======================================
2// This file was automatically generated.
3// ======================================
4
5use crate::client::{Client, Response};
6use crate::ids::TaxRateId;
7use crate::params::{Expand, List, Metadata, Object, Paginable, RangeQuery, Timestamp};
8use serde::{Deserialize, Serialize};
9
10/// The resource representing a Stripe "TaxRate".
11///
12/// For more details see <https://stripe.com/docs/api/tax_rates/object>
13#[derive(Clone, Debug, Default, Deserialize, Serialize)]
14pub struct TaxRate {
15 /// Unique identifier for the object.
16 pub id: TaxRateId,
17
18 /// Defaults to `true`.
19 ///
20 /// When set to `false`, this tax rate cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
21 pub active: bool,
22
23 /// Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
24 pub country: Option<String>,
25
26 /// Time at which the object was created.
27 ///
28 /// Measured in seconds since the Unix epoch.
29 pub created: Timestamp,
30
31 /// An arbitrary string attached to the tax rate for your internal use only.
32 ///
33 /// It will not be visible to your customers.
34 pub description: Option<String>,
35
36 /// The display name of the tax rates as it will appear to your customer on their receipt email, PDF, and the hosted invoice page.
37 pub display_name: String,
38
39 /// Actual/effective tax rate percentage out of 100.
40 ///
41 /// For tax calculations with automatic_tax[enabled]=true, this percentage reflects the rate actually used to calculate tax based on the product's taxability and whether the user is registered to collect taxes in the corresponding jurisdiction.
42 pub effective_percentage: Option<f64>,
43
44 /// This specifies if the tax rate is inclusive or exclusive.
45 pub inclusive: bool,
46
47 /// The jurisdiction for the tax rate.
48 ///
49 /// You can use this label field for tax reporting purposes.
50 /// It also appears on your customer’s invoice.
51 pub jurisdiction: Option<String>,
52
53 /// The level of the jurisdiction that imposes this tax rate.
54 ///
55 /// Will be `null` for manually defined tax rates.
56 pub jurisdiction_level: Option<TaxRateJurisdictionLevel>,
57
58 /// Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
59 pub livemode: bool,
60
61 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
62 ///
63 /// This can be useful for storing additional information about the object in a structured format.
64 pub metadata: Option<Metadata>,
65
66 /// Tax rate percentage out of 100.
67 ///
68 /// For tax calculations with automatic_tax[enabled]=true, this percentage includes the statutory tax rate of non-taxable jurisdictions.
69 pub percentage: f64,
70
71 /// [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix.
72 ///
73 /// For example, "NY" for New York, United States.
74 pub state: Option<String>,
75
76 /// The high-level tax type, such as `vat` or `sales_tax`.
77 pub tax_type: Option<TaxRateTaxType>,
78}
79
80impl TaxRate {
81 /// Returns a list of your tax rates.
82 ///
83 /// Tax rates are returned sorted by creation date, with the most recently created tax rates appearing first.
84 pub fn list(client: &Client, params: &ListTaxRates<'_>) -> Response<List<TaxRate>> {
85 client.get_query("/tax_rates", params)
86 }
87
88 /// Creates a new tax rate.
89 pub fn create(client: &Client, params: CreateTaxRate<'_>) -> Response<TaxRate> {
90 #[allow(clippy::needless_borrows_for_generic_args)]
91 client.post_form("/tax_rates", ¶ms)
92 }
93
94 /// Retrieves a tax rate with the given ID.
95 pub fn retrieve(client: &Client, id: &TaxRateId, expand: &[&str]) -> Response<TaxRate> {
96 client.get_query(&format!("/tax_rates/{}", id), Expand { expand })
97 }
98
99 /// Updates an existing tax rate.
100 pub fn update(client: &Client, id: &TaxRateId, params: UpdateTaxRate<'_>) -> Response<TaxRate> {
101 #[allow(clippy::needless_borrows_for_generic_args)]
102 client.post_form(&format!("/tax_rates/{}", id), ¶ms)
103 }
104}
105
106impl Object for TaxRate {
107 type Id = TaxRateId;
108 fn id(&self) -> Self::Id {
109 self.id.clone()
110 }
111 fn object(&self) -> &'static str {
112 "tax_rate"
113 }
114}
115
116/// The parameters for `TaxRate::create`.
117#[derive(Clone, Debug, Serialize)]
118pub struct CreateTaxRate<'a> {
119 /// Flag determining whether the tax rate is active or inactive (archived).
120 ///
121 /// Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
122 #[serde(skip_serializing_if = "Option::is_none")]
123 pub active: Option<bool>,
124
125 /// Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
126 #[serde(skip_serializing_if = "Option::is_none")]
127 pub country: Option<&'a str>,
128
129 /// An arbitrary string attached to the tax rate for your internal use only.
130 ///
131 /// It will not be visible to your customers.
132 #[serde(skip_serializing_if = "Option::is_none")]
133 pub description: Option<&'a str>,
134
135 /// The display name of the tax rate, which will be shown to users.
136 pub display_name: &'a str,
137
138 /// Specifies which fields in the response should be expanded.
139 #[serde(skip_serializing_if = "Expand::is_empty")]
140 pub expand: &'a [&'a str],
141
142 /// This specifies if the tax rate is inclusive or exclusive.
143 pub inclusive: bool,
144
145 /// The jurisdiction for the tax rate.
146 ///
147 /// You can use this label field for tax reporting purposes.
148 /// It also appears on your customer’s invoice.
149 #[serde(skip_serializing_if = "Option::is_none")]
150 pub jurisdiction: Option<&'a str>,
151
152 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
153 ///
154 /// This can be useful for storing additional information about the object in a structured format.
155 /// Individual keys can be unset by posting an empty value to them.
156 /// All keys can be unset by posting an empty value to `metadata`.
157 #[serde(skip_serializing_if = "Option::is_none")]
158 pub metadata: Option<Metadata>,
159
160 /// This represents the tax rate percent out of 100.
161 pub percentage: f64,
162
163 /// [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix.
164 ///
165 /// For example, "NY" for New York, United States.
166 #[serde(skip_serializing_if = "Option::is_none")]
167 pub state: Option<&'a str>,
168
169 /// The high-level tax type, such as `vat` or `sales_tax`.
170 #[serde(skip_serializing_if = "Option::is_none")]
171 pub tax_type: Option<TaxRateTaxType>,
172}
173
174impl<'a> CreateTaxRate<'a> {
175 pub fn new(display_name: &'a str, percentage: f64) -> Self {
176 CreateTaxRate {
177 active: Default::default(),
178 country: Default::default(),
179 description: Default::default(),
180 display_name,
181 expand: Default::default(),
182 inclusive: Default::default(),
183 jurisdiction: Default::default(),
184 metadata: Default::default(),
185 percentage,
186 state: Default::default(),
187 tax_type: Default::default(),
188 }
189 }
190}
191
192/// The parameters for `TaxRate::list`.
193#[derive(Clone, Debug, Serialize, Default)]
194pub struct ListTaxRates<'a> {
195 /// Optional flag to filter by tax rates that are either active or inactive (archived).
196 #[serde(skip_serializing_if = "Option::is_none")]
197 pub active: Option<bool>,
198
199 /// Optional range for filtering created date.
200 #[serde(skip_serializing_if = "Option::is_none")]
201 pub created: Option<RangeQuery<Timestamp>>,
202
203 /// A cursor for use in pagination.
204 ///
205 /// `ending_before` is an object ID that defines your place in the list.
206 /// 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.
207 #[serde(skip_serializing_if = "Option::is_none")]
208 pub ending_before: Option<TaxRateId>,
209
210 /// Specifies which fields in the response should be expanded.
211 #[serde(skip_serializing_if = "Expand::is_empty")]
212 pub expand: &'a [&'a str],
213
214 /// Optional flag to filter by tax rates that are inclusive (or those that are not inclusive).
215 #[serde(skip_serializing_if = "Option::is_none")]
216 pub inclusive: Option<bool>,
217
218 /// A limit on the number of objects to be returned.
219 ///
220 /// Limit can range between 1 and 100, and the default is 10.
221 #[serde(skip_serializing_if = "Option::is_none")]
222 pub limit: Option<u64>,
223
224 /// A cursor for use in pagination.
225 ///
226 /// `starting_after` is an object ID that defines your place in the list.
227 /// 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.
228 #[serde(skip_serializing_if = "Option::is_none")]
229 pub starting_after: Option<TaxRateId>,
230}
231
232impl<'a> ListTaxRates<'a> {
233 pub fn new() -> Self {
234 ListTaxRates {
235 active: Default::default(),
236 created: Default::default(),
237 ending_before: Default::default(),
238 expand: Default::default(),
239 inclusive: Default::default(),
240 limit: Default::default(),
241 starting_after: Default::default(),
242 }
243 }
244}
245impl Paginable for ListTaxRates<'_> {
246 type O = TaxRate;
247 fn set_last(&mut self, item: Self::O) {
248 self.starting_after = Some(item.id());
249 }
250}
251/// The parameters for `TaxRate::update`.
252#[derive(Clone, Debug, Serialize, Default)]
253pub struct UpdateTaxRate<'a> {
254 /// Flag determining whether the tax rate is active or inactive (archived).
255 ///
256 /// Inactive tax rates cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
257 #[serde(skip_serializing_if = "Option::is_none")]
258 pub active: Option<bool>,
259
260 /// Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
261 #[serde(skip_serializing_if = "Option::is_none")]
262 pub country: Option<&'a str>,
263
264 /// An arbitrary string attached to the tax rate for your internal use only.
265 ///
266 /// It will not be visible to your customers.
267 #[serde(skip_serializing_if = "Option::is_none")]
268 pub description: Option<&'a str>,
269
270 /// The display name of the tax rate, which will be shown to users.
271 #[serde(skip_serializing_if = "Option::is_none")]
272 pub display_name: Option<&'a str>,
273
274 /// Specifies which fields in the response should be expanded.
275 #[serde(skip_serializing_if = "Expand::is_empty")]
276 pub expand: &'a [&'a str],
277
278 /// The jurisdiction for the tax rate.
279 ///
280 /// You can use this label field for tax reporting purposes.
281 /// It also appears on your customer’s invoice.
282 #[serde(skip_serializing_if = "Option::is_none")]
283 pub jurisdiction: Option<&'a str>,
284
285 /// Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object.
286 ///
287 /// This can be useful for storing additional information about the object in a structured format.
288 /// Individual keys can be unset by posting an empty value to them.
289 /// All keys can be unset by posting an empty value to `metadata`.
290 #[serde(skip_serializing_if = "Option::is_none")]
291 pub metadata: Option<Metadata>,
292
293 /// [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2:US), without country prefix.
294 ///
295 /// For example, "NY" for New York, United States.
296 #[serde(skip_serializing_if = "Option::is_none")]
297 pub state: Option<&'a str>,
298
299 /// The high-level tax type, such as `vat` or `sales_tax`.
300 #[serde(skip_serializing_if = "Option::is_none")]
301 pub tax_type: Option<TaxRateTaxType>,
302}
303
304impl<'a> UpdateTaxRate<'a> {
305 pub fn new() -> Self {
306 UpdateTaxRate {
307 active: Default::default(),
308 country: Default::default(),
309 description: Default::default(),
310 display_name: Default::default(),
311 expand: Default::default(),
312 jurisdiction: Default::default(),
313 metadata: Default::default(),
314 state: Default::default(),
315 tax_type: Default::default(),
316 }
317 }
318}
319
320/// An enum representing the possible values of an `TaxRate`'s `jurisdiction_level` field.
321#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
322#[serde(rename_all = "snake_case")]
323pub enum TaxRateJurisdictionLevel {
324 City,
325 Country,
326 County,
327 District,
328 Multiple,
329 State,
330}
331
332impl TaxRateJurisdictionLevel {
333 pub fn as_str(self) -> &'static str {
334 match self {
335 TaxRateJurisdictionLevel::City => "city",
336 TaxRateJurisdictionLevel::Country => "country",
337 TaxRateJurisdictionLevel::County => "county",
338 TaxRateJurisdictionLevel::District => "district",
339 TaxRateJurisdictionLevel::Multiple => "multiple",
340 TaxRateJurisdictionLevel::State => "state",
341 }
342 }
343}
344
345impl AsRef<str> for TaxRateJurisdictionLevel {
346 fn as_ref(&self) -> &str {
347 self.as_str()
348 }
349}
350
351impl std::fmt::Display for TaxRateJurisdictionLevel {
352 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
353 self.as_str().fmt(f)
354 }
355}
356impl std::default::Default for TaxRateJurisdictionLevel {
357 fn default() -> Self {
358 Self::City
359 }
360}
361
362/// An enum representing the possible values of an `TaxRate`'s `tax_type` field.
363#[derive(Copy, Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
364#[serde(rename_all = "snake_case")]
365pub enum TaxRateTaxType {
366 AmusementTax,
367 CommunicationsTax,
368 Gst,
369 Hst,
370 Igst,
371 Jct,
372 LeaseTax,
373 Pst,
374 Qst,
375 Rst,
376 SalesTax,
377 ServiceTax,
378 Vat,
379}
380
381impl TaxRateTaxType {
382 pub fn as_str(self) -> &'static str {
383 match self {
384 TaxRateTaxType::AmusementTax => "amusement_tax",
385 TaxRateTaxType::CommunicationsTax => "communications_tax",
386 TaxRateTaxType::Gst => "gst",
387 TaxRateTaxType::Hst => "hst",
388 TaxRateTaxType::Igst => "igst",
389 TaxRateTaxType::Jct => "jct",
390 TaxRateTaxType::LeaseTax => "lease_tax",
391 TaxRateTaxType::Pst => "pst",
392 TaxRateTaxType::Qst => "qst",
393 TaxRateTaxType::Rst => "rst",
394 TaxRateTaxType::SalesTax => "sales_tax",
395 TaxRateTaxType::ServiceTax => "service_tax",
396 TaxRateTaxType::Vat => "vat",
397 }
398 }
399}
400
401impl AsRef<str> for TaxRateTaxType {
402 fn as_ref(&self) -> &str {
403 self.as_str()
404 }
405}
406
407impl std::fmt::Display for TaxRateTaxType {
408 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
409 self.as_str().fmt(f)
410 }
411}
412impl std::default::Default for TaxRateTaxType {
413 fn default() -> Self {
414 Self::AmusementTax
415 }
416}