squareup/api/customers_api.rs
1//! Create and manage customer profiles and sync CRM systems with Square.
2//!
3//! The Customers API enables you to create and manage customer profiles, as well as search for
4//! customers based on various criteria (including customer group membership). You can also use the
5//! API to sync contacts between your CRM system and Square.
6
7use crate::models::{
8 AddGroupToCustomerResponse, BulkCreateCustomersRequest, BulkCreateCustomersResponse,
9 BulkDeleteCustomersRequest, BulkDeleteCustomersResponse, BulkRetrieveCustomersRequest,
10 BulkRetrieveCustomersResponse, BulkUpdateCustomersRequest, BulkUpdateCustomersResponse,
11 DeleteCustomerParameters, RemoveGroupFromCustomerResponse,
12};
13use crate::{
14 SquareClient,
15 config::Configuration,
16 http::client::HttpClient,
17 models::{
18 CreateCustomerRequest, CreateCustomerResponse, DeleteCustomerResponse,
19 ListCustomersParameters, ListCustomersResponse, RetrieveCustomerResponse,
20 SearchCustomersRequest, SearchCustomersResponse, UpdateCustomerRequest,
21 UpdateCustomerResponse, errors::SquareApiError,
22 },
23};
24
25const DEFAULT_URI: &str = "/customers";
26
27/// Create and manage [Customer] profiles and sync CRM systems with Square.
28pub struct CustomersApi {
29 /// App config information
30 config: Configuration,
31 /// HTTP Client for requests to the Customers API endpoints
32 http_client: HttpClient,
33}
34
35impl CustomersApi {
36 /// Instantiates a new `CustomersApi`
37 pub fn new(square_client: SquareClient) -> CustomersApi {
38 CustomersApi {
39 config: square_client.config,
40 http_client: square_client.http_client,
41 }
42 }
43
44 /// Lists [Customer] profiles associated with a Square account.
45 ///
46 /// Under normal operating conditions, newly created or updated customer profiles become
47 /// available for the listing operation in well under 30 seconds. Occasionally, propagation of
48 /// the new or updated profiles can take closer to one minute or longer, especially during
49 /// network incidents and outages.
50 pub async fn list_customers(
51 &self,
52 params: &ListCustomersParameters,
53 ) -> Result<ListCustomersResponse, SquareApiError> {
54 let url = format!("{}{}", &self.url(), params.to_query_string());
55 let response = self.http_client.get(&url).await?;
56
57 response.deserialize().await
58 }
59
60 /// Creates a new [Customer] for a business.
61 ///
62 /// You must provide at least one of the following values in your request to this endpoint:
63 ///
64 /// * `given_name`
65 /// * `family_name`
66 /// * `company_name`
67 /// * `email_address`
68 /// * `phone_number`
69 pub async fn create_customer(
70 &self,
71 body: &CreateCustomerRequest,
72 ) -> Result<CreateCustomerResponse, SquareApiError> {
73 let response = self.http_client.post(&self.url(), body).await?;
74
75 response.deserialize().await
76 }
77
78 /// Creates multiple customer profiles for a business.
79 ///
80 /// This endpoint takes a map of individual create requests and returns a map of responses.
81 ///
82 /// You must provide at least one of the following values in each create request:
83 ///
84 /// * `given_name`
85 /// * `family_name`
86 /// * `company_name`
87 /// * `email_address`
88 /// * `phone_number`
89 ///
90 /// Permissions:CUSTOMERS_WRITE
91 pub async fn bulk_create_customers(
92 &self,
93 body: &BulkCreateCustomersRequest,
94 ) -> Result<BulkCreateCustomersResponse, SquareApiError> {
95 let url = format!("{}/bulk-create", &self.url());
96 let response = self.http_client.post(&url, body).await?;
97
98 response.deserialize().await
99 }
100
101 /// Deletes multiple customer profiles.
102 ///
103 /// The endpoint takes a list of customer IDs and returns a map of responses.
104 /// Permissions:CUSTOMERS_WRITE
105 pub async fn bulk_delete_customers(
106 &self,
107 body: &BulkDeleteCustomersRequest,
108 ) -> Result<BulkDeleteCustomersResponse, SquareApiError> {
109 let url = format!("{}/bulk-delete", &self.url());
110 let response = self.http_client.post(&url, body).await?;
111
112 response.deserialize().await
113 }
114
115 /// Retrieves multiple customer profiles.
116 ///
117 /// This endpoint takes a list of customer IDs and returns a map of responses.
118 /// Permissions:CUSTOMERS_READ
119 pub async fn bulk_retrieve_customers(
120 &self,
121 body: &BulkRetrieveCustomersRequest,
122 ) -> Result<BulkRetrieveCustomersResponse, SquareApiError> {
123 let url = format!("{}/bulk-retrieve", &self.url());
124 let response = self.http_client.post(&url, body).await?;
125
126 response.deserialize().await
127 }
128
129 /// Updates multiple customer profiles.
130 ///
131 /// This endpoint takes a map of individual update requests and returns a map of responses.
132 ///
133 /// You cannot use this endpoint to change cards on file. To make changes, use the Cards API
134 /// Use the Cards API to save a credit or debit card on file.Reference or Gift Cards API
135 /// Permissions:CUSTOMERS_WRITE
136 pub async fn bulk_update_customers(
137 &self,
138 body: &BulkUpdateCustomersRequest,
139 ) -> Result<BulkUpdateCustomersResponse, SquareApiError> {
140 let url = format!("{}/bulk-update", &self.url());
141 let response = self.http_client.post(&url, body).await?;
142
143 response.deserialize().await
144 }
145
146 /// Searches the [Customer] profiles associated with a Square account using a supported query
147 /// filter.
148 ///
149 /// Calling `SearchCustomers` without any explicit query filter returns all customer profiles
150 /// ordered alphabetically based on `given_name` and `family_name`.
151 ///
152 /// Under normal operating conditions, newly created or updated customer profiles become
153 /// available for the search operation in well under 30 seconds. Occasionally, propagation of
154 /// the new or updated profiles can take closer to one minute or longer, especially during
155 /// network incidents and outages.
156 pub async fn search_customers(
157 &self,
158 body: &SearchCustomersRequest,
159 ) -> Result<SearchCustomersResponse, SquareApiError> {
160 let url = format!("{}/search", &self.url());
161 let response = self.http_client.post(&url, body).await?;
162
163 response.deserialize().await
164 }
165
166 /// Deletes a [Customer] profile from a business.
167 ///
168 /// This operation also unlinks any associated cards on file.
169 ///
170 /// As a best practice, you should include the version field in the request to enable optimistic
171 /// concurrency control. The value must be set to the current version of the customer profile.
172 ///
173 /// To delete a customer profile that was created by merging existing profiles, you must use the
174 /// ID of the newly created profile.
175 pub async fn delete_customer(
176 &self,
177 customer_id: impl AsRef<str>,
178 params: &DeleteCustomerParameters,
179 ) -> Result<DeleteCustomerResponse, SquareApiError> {
180 let url = format!(
181 "{}/{}{}",
182 &self.url(),
183 customer_id.as_ref(),
184 params.to_query_string()
185 );
186 let response = self.http_client.delete(&url).await?;
187
188 response.deserialize().await
189 }
190
191 /// Returns details for a single [Customer].
192 pub async fn retrieve_customer(
193 &self,
194 customer_id: impl AsRef<str>,
195 ) -> Result<RetrieveCustomerResponse, SquareApiError> {
196 let url = format!("{}/{}", &self.url(), customer_id.as_ref());
197 let response = self.http_client.get(&url).await?;
198
199 response.deserialize().await
200 }
201
202 /// Updates a [Customer] profile.
203 ///
204 /// To change an attribute, specify the new value. To remove an attribute, specify the value as
205 /// an empty string or empty object.
206 ///
207 /// As a best practice, you should include the `version` field in the request to enable
208 /// [optimistic
209 /// concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency)
210 /// control. The value must be set to the current version of the customer profile.
211 ///
212 /// To update a customer profile that was created by merging existing profiles, you must use the
213 /// ID of the newly created profile.
214 ///
215 /// You cannot use this endpoint to change cards on file. To make changes, use the [Cards
216 /// API](https://developer.squareup.com/reference/square/cards-api) or [Gift Cards
217 /// API](https://developer.squareup.com/reference/square/giftcards-api).
218 pub async fn update_customer(
219 &self,
220 customer_id: impl AsRef<str>,
221 body: &UpdateCustomerRequest,
222 ) -> Result<UpdateCustomerResponse, SquareApiError> {
223 let url = format!("{}/{}", &self.url(), customer_id.as_ref());
224 let response = self.http_client.put(&url, body).await?;
225
226 response.deserialize().await
227 }
228
229 /// Removes a group membership from a [Customer].
230 ///
231 /// The customer is identified by the customer_id value and the customer group is
232 /// identified by the group_id value.
233 pub async fn remove_group_from_customer(
234 &self,
235 customer_id: impl AsRef<str>,
236 group_id: impl AsRef<str>,
237 ) -> Result<RemoveGroupFromCustomerResponse, SquareApiError> {
238 let url = format!(
239 "{}/{}/groups/{}",
240 &self.url(),
241 customer_id.as_ref(),
242 group_id.as_ref()
243 );
244 let response = self.http_client.delete(&url).await?;
245
246 response.deserialize().await
247 }
248
249 /// Adds a group membership to a [Customer].
250 ///
251 /// Adds a group membership to a customer.
252 /// The customer is identified by the customer_id value and the customer group is identified by
253 /// the group_id value.
254 pub async fn add_group_to_customer(
255 &self,
256 customer_id: impl AsRef<str>,
257 group_id: impl AsRef<str>,
258 ) -> Result<AddGroupToCustomerResponse, SquareApiError> {
259 let url = format!(
260 "{}/{}/groups/{}",
261 &self.url(),
262 customer_id.as_ref(),
263 group_id.as_ref()
264 );
265 let response = self.http_client.empty_put(&url).await?;
266
267 response.deserialize().await
268 }
269
270 fn url(&self) -> String {
271 format!("{}{}", &self.config.get_base_url(), DEFAULT_URI)
272 }
273}