square_api_client/api/
subscriptions_api.rs

1//! Subscriptions API
2//!
3//! Create and manage subscriptions.
4//!
5//! Subscriptions enable sellers to generate a reliable cash flow and recurring revenue to grow
6//! their businesses. Square offers the Subscriptions API for developers to embed subscription
7//! functionality in their applications. You first create a subscription plan using the Catalog API
8//! and then use the Subscriptions API to create and manage subscriptions.
9
10use crate::{
11    config::Configuration,
12    http::client::HttpClient,
13    models::{
14        errors::ApiError, CancelSubscriptionResponse, CreateSubscriptionRequest,
15        CreateSubscriptionResponse, DeleteSubscriptionActionResponse,
16        ListSubscriptionEventsParameters, ListSubscriptionEventsResponse, PauseSubscriptionRequest,
17        PauseSubscriptionResponse, ResumeSubscriptionRequest, ResumeSubscriptionResponse,
18        RetrieveSubscriptionParameters, RetrieveSubscriptionResponse, SearchSubscriptionsRequest,
19        SearchSubscriptionsResponse, SwapPlanRequest, SwapPlanResponse, UpdateSubscriptionRequest,
20        UpdateSubscriptionResponse,
21    },
22};
23
24const DEFAULT_URI: &str = "/subscriptions";
25
26/// Create and manage subscriptions.
27pub struct SubscriptionsApi {
28    /// App config information
29    config: Configuration,
30    /// HTTP Client for requests to the Subscriptions API endpoints
31    client: HttpClient,
32}
33
34impl SubscriptionsApi {
35    /// Instantiates a new `SubscriptionsApi`
36    pub fn new(config: Configuration, client: HttpClient) -> Self {
37        Self { config, client }
38    }
39
40    /// Creates a subscription to a subscription plan by a customer.
41    ///
42    /// If you provide a card on file in the request, Square charges the card for the subscription.
43    /// Otherwise, Square bills an invoice to the customer's email address. The subscription starts
44    /// immediately, unless the request includes the optional `start_date`. Each individual
45    /// subscription is associated with a particular location.
46    pub async fn create_subscription(
47        &self,
48        body: &CreateSubscriptionRequest,
49    ) -> Result<CreateSubscriptionResponse, ApiError> {
50        let response = self.client.post(&self.url(), body).await?;
51
52        response.deserialize().await
53    }
54
55    /// Searches for subscriptions.
56    ///
57    /// Results are ordered chronologically by subscription creation date. If the request specifies
58    /// more than one location ID, the endpoint orders the result by location ID, and then by
59    /// creation date within each location. If no locations are given in the query, all locations
60    /// are searched.
61    ///
62    /// You can also optionally specify `customer_ids` to search by customer. If left unset, all
63    /// customers associated with the specified locations are returned. If the request specifies
64    /// customer IDs, the endpoint orders results first by location, within location by customer ID,
65    /// and within customer by subscription creation date.
66    ///
67    /// For more information, see [Retrieve
68    /// subscriptions](https://developer.squareup.com/docs/subscriptions-api/overview#retrieve-subscriptions).
69    pub async fn search_subscriptions(
70        &self,
71        body: &SearchSubscriptionsRequest,
72    ) -> Result<SearchSubscriptionsResponse, ApiError> {
73        let url = format!("{}/search", &self.url());
74        let response = self.client.post(&url, body).await?;
75
76        response.deserialize().await
77    }
78
79    /// Retrieves a subscription.
80    pub async fn retrieve_subscription(
81        &self,
82        subscription_id: &str,
83        params: &RetrieveSubscriptionParameters,
84    ) -> Result<RetrieveSubscriptionResponse, ApiError> {
85        let url = format!("{}/{}{}", &self.url(), subscription_id, params.to_query_string());
86        let response = self.client.get(&url).await?;
87
88        response.deserialize().await
89    }
90
91    /// Updates a subscription.
92    ///
93    /// You can set, modify, and clear the `subscription` field values.
94    pub async fn update_subscription(
95        &self,
96        subscription_id: &str,
97        body: &UpdateSubscriptionRequest,
98    ) -> Result<UpdateSubscriptionResponse, ApiError> {
99        let url = format!("{}/{}", &self.url(), subscription_id);
100        let response = self.client.put(&url, body).await?;
101
102        response.deserialize().await
103    }
104
105    /// Deletes a scheduled action for a subscription.
106    pub async fn delete_subscription_action(
107        &self,
108        subscription_id: &str,
109        action_id: &str,
110    ) -> Result<DeleteSubscriptionActionResponse, ApiError> {
111        let url = format!("{}/{}/actions/{}", &self.url(), subscription_id, action_id);
112        let response = self.client.delete(&url).await?;
113
114        response.deserialize().await
115    }
116
117    /// Schedules a `CANCEL` action to cancel an active subscription by setting the `canceled_date`
118    /// field to the end of the active billing period and changing the subscription status from
119    /// ACTIVE to CANCELED after this date.
120    pub async fn cancel_subscription(
121        &self,
122        subscription_id: &str,
123    ) -> Result<CancelSubscriptionResponse, ApiError> {
124        let url = format!("{}/{}/cancel", &self.url(), subscription_id);
125        let response = self.client.post(&url, "").await?;
126
127        response.deserialize().await
128    }
129
130    /// Lists all events for a specific subscription.
131    pub async fn list_subscription_events(
132        &self,
133        subscription_id: &str,
134        params: &ListSubscriptionEventsParameters,
135    ) -> Result<ListSubscriptionEventsResponse, ApiError> {
136        let url = format!("{}/{}/events{}", &self.url(), subscription_id, params.to_query_string());
137        let response = self.client.get(&url).await?;
138
139        response.deserialize().await
140    }
141
142    /// Schedules a `PAUSE` action to pause an active subscription.
143    pub async fn pause_subscription(
144        &self,
145        subscription_id: &str,
146        body: &PauseSubscriptionRequest,
147    ) -> Result<PauseSubscriptionResponse, ApiError> {
148        let url = format!("{}/{}/pause", &self.url(), subscription_id);
149        let response = self.client.post(&url, body).await?;
150
151        response.deserialize().await
152    }
153
154    /// Schedules a `RESUME` action to resume a paused or a deactivated subscription.
155    pub async fn resume_subscription(
156        &self,
157        subscription_id: &str,
158        body: &ResumeSubscriptionRequest,
159    ) -> Result<ResumeSubscriptionResponse, ApiError> {
160        let url = format!("{}/{}/resume", &self.url(), subscription_id);
161        let response = self.client.post(&url, body).await?;
162
163        response.deserialize().await
164    }
165
166    /// Schedules a `SWAP_PLAN` action to swap a subscription plan in an existing subscription.
167    pub async fn swap_plan(
168        &self,
169        subscription_id: &str,
170        body: &SwapPlanRequest,
171    ) -> Result<SwapPlanResponse, ApiError> {
172        let url = format!("{}/{}/swap-plan", &self.url(), subscription_id);
173        let response = self.client.post(&url, body).await?;
174
175        response.deserialize().await
176    }
177
178    /// Constructs the basic entity URL including domain and entity path. Any additional path
179    /// elements (e.g. path parameters) will need to be appended to this URL.
180    fn url(&self) -> String {
181        format!("{}{}", &self.config.get_base_url(), DEFAULT_URI)
182    }
183}
square_api_client/api/subscriptions_api.rs

square_api_client/api/
subscriptions_api.rs
