paddle_rust_sdk/
adjustments.rs

1//! Builders for making requests to the Paddle API for making adjustments to billed or completed transactions.
2//!
3//! See the [Paddle API](https://developer.paddle.com/api-reference/adjustments/overview) documentation for more information.
4
5use reqwest::Method;
6use serde::Serialize;
7use serde_with::skip_serializing_none;
8
9use crate::entities::{Adjustment, AdjustmentItemInput};
10use crate::enums::{AdjustmentAction, AdjustmentStatus, AdjustmentType, TaxMode};
11use crate::ids::{AdjustmentID, CustomerID, SubscriptionID, TransactionID};
12use crate::paginated::Paginated;
13use crate::{Paddle, Result};
14
15// Request builder for retrieving adjustments
16#[skip_serializing_none]
17#[derive(Serialize)]
18pub struct AdjustmentsList<'a> {
19    #[serde(skip)]
20    client: &'a Paddle,
21    action: Option<AdjustmentAction>,
22    after: Option<AdjustmentID>,
23    #[serde(serialize_with = "crate::comma_separated")]
24    customer_id: Option<Vec<CustomerID>>,
25    order_by: Option<String>,
26    per_page: Option<usize>,
27    #[serde(serialize_with = "crate::comma_separated_enum")]
28    status: Option<Vec<AdjustmentStatus>>,
29    #[serde(serialize_with = "crate::comma_separated")]
30    subscription_id: Option<Vec<SubscriptionID>>,
31    #[serde(serialize_with = "crate::comma_separated")]
32    transaction_id: Option<Vec<TransactionID>>,
33    #[serde(serialize_with = "crate::comma_separated")]
34    id: Option<Vec<AdjustmentID>>,
35}
36
37impl<'a> AdjustmentsList<'a> {
38    pub fn new(client: &'a Paddle) -> Self {
39        Self {
40            client,
41            action: None,
42            after: None,
43            customer_id: None,
44            order_by: None,
45            per_page: None,
46            status: None,
47            subscription_id: None,
48            transaction_id: None,
49            id: None,
50        }
51    }
52
53    /// Return entities for the specified action.
54    pub fn action(&mut self, adjustment_action: AdjustmentAction) -> &mut Self {
55        self.action = Some(adjustment_action);
56        self
57    }
58
59    /// Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations.
60    pub fn after(&mut self, id: impl Into<AdjustmentID>) -> &mut Self {
61        self.after = Some(id.into());
62        self
63    }
64
65    /// Return entities related to the specified customers.
66    pub fn customer_id(
67        &mut self,
68        customer_ids: impl IntoIterator<Item = impl Into<CustomerID>>,
69    ) -> &mut Self {
70        self.customer_id = Some(customer_ids.into_iter().map(Into::into).collect());
71        self
72    }
73
74    /// Order returned entities by the specified field. Valid fields for ordering: `id`
75    pub fn order_by_asc(&mut self, field: &str) -> &mut Self {
76        self.order_by = Some(format!("{}[ASC]", field));
77        self
78    }
79
80    /// Order returned entities by the specified field. Valid fields for ordering: `id`
81    pub fn order_by_desc(&mut self, field: &str) -> &mut Self {
82        self.order_by = Some(format!("{}[DESC]", field));
83        self
84    }
85
86    /// Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested.
87    /// Check `meta.pagination.per_page` in the response to see how many were returned.
88    ///
89    /// Default: `50`; Maximum: `200`.
90    pub fn per_page(&mut self, entities_per_page: usize) -> &mut Self {
91        self.per_page = Some(entities_per_page);
92        self
93    }
94
95    /// Return entities that match the specified status.
96    pub fn status(&mut self, statuses: impl IntoIterator<Item = AdjustmentStatus>) -> &mut Self {
97        self.status = Some(statuses.into_iter().collect());
98        self
99    }
100
101    /// Return entities related to the specified subscription.
102    pub fn subscription_ids(
103        &mut self,
104        subscription_ids: impl IntoIterator<Item = impl Into<SubscriptionID>>,
105    ) -> &mut Self {
106        self.subscription_id = Some(subscription_ids.into_iter().map(Into::into).collect());
107        self
108    }
109
110    /// Return entities related to the specified subscription.
111    pub fn transaction_ids(
112        &mut self,
113        transaction_ids: impl IntoIterator<Item = impl Into<TransactionID>>,
114    ) -> &mut Self {
115        self.transaction_id = Some(transaction_ids.into_iter().map(Into::into).collect());
116        self
117    }
118
119    /// Return only the IDs specified.
120    pub fn id(&mut self, ids: impl IntoIterator<Item = impl Into<AdjustmentID>>) -> &mut Self {
121        self.id = Some(ids.into_iter().map(Into::into).collect());
122        self
123    }
124
125    /// Returns a paginator for fetching pages of entities from Paddle
126    pub fn send(&self) -> Paginated<Vec<Adjustment>> {
127        Paginated::new(self.client, "/adjustments", self)
128    }
129}
130
131/// Request builder for creating an adjustment in Paddle.
132#[skip_serializing_none]
133#[derive(Serialize)]
134pub struct AdjustmentCreate<'a> {
135    #[serde(skip)]
136    client: &'a Paddle,
137    transaction_id: TransactionID,
138    action: AdjustmentAction,
139    reason: String,
140    r#type: Option<AdjustmentType>,
141    tax_mode: Option<TaxMode>,
142    items: Option<Vec<AdjustmentItemInput>>,
143}
144
145impl<'a> AdjustmentCreate<'a> {
146    pub fn new(
147        client: &'a Paddle,
148        transaction_id: impl Into<TransactionID>,
149        action: AdjustmentAction,
150        reason: impl Into<String>,
151    ) -> Self {
152        Self {
153            client,
154            transaction_id: transaction_id.into(),
155            action,
156            reason: reason.into(),
157            r#type: None,
158            tax_mode: None,
159            items: None,
160        }
161    }
162
163    /// Type of adjustment. Use `full` to adjust the grand total for the related transaction. Include an `items` array when creating a `partial` adjustment. If omitted, defaults to `partial`.
164    pub fn r#type(&mut self, adjustment_type: AdjustmentType) -> &mut Self {
165        self.r#type = Some(adjustment_type);
166        self
167    }
168
169    /// List of transaction items to adjust. Required if `type` is not populated or set to `partial`.
170    pub fn items(&mut self, items: impl IntoIterator<Item = AdjustmentItemInput>) -> &mut Self {
171        self.items = Some(items.into_iter().collect());
172        self
173    }
174
175    /// Whether the amounts to be adjusted are inclusive or exclusive of tax. If `internal`, adjusted amounts are considered to be inclusive of tax. If `external`, Paddle calculates the tax and adds it to the amounts provided.
176    ///
177    /// Only valid for adjustments where the `type` is `partial`.
178    ///
179    /// If omitted, defaults to `internal`.
180    pub fn tax_mode(&mut self, mode: TaxMode) -> &mut Self {
181        self.tax_mode = Some(mode);
182        self
183    }
184
185    /// Send the request to Paddle and return the response.
186    pub async fn send(&self) -> Result<Adjustment> {
187        self.client.send(self, Method::POST, "/adjustments").await
188    }
189}
paddle_rust_sdk/adjustments.rs

paddle_rust_sdk/
adjustments.rs
