square_api_client/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::{
8    config::Configuration,
9    http::client::HttpClient,
10    models::{
11        errors::ApiError, CreateCustomerRequest, CreateCustomerResponse, DeleteCustomerResponse,
12        ListCustomersParameters, ListCustomersResponse, RetrieveCustomerResponse,
13        SearchCustomersRequest, SearchCustomersResponse, UpdateCustomerRequest,
14        UpdateCustomerResponse,
15    },
16};
17
18const DEFAULT_URI: &str = "/customers";
19
20/// Create and manage [Customer] profiles and sync CRM systems with Square.
21pub struct CustomersApi {
22    /// App config information
23    config: Configuration,
24    /// HTTP Client for requests to the Customers API endpoints
25    client: HttpClient,
26}
27
28impl CustomersApi {
29    pub fn new(config: Configuration, client: HttpClient) -> Self {
30        Self { config, client }
31    }
32
33    /// Creates a new [Customer] for a business.
34    ///
35    /// You must provide at least one of the following values in your request to this endpoint:
36    ///
37    /// * `given_name`
38    /// * `family_name`
39    /// * `company_name`
40    /// * `email_address`
41    /// * `phone_number`
42    pub async fn create_customer(
43        &self,
44        body: &CreateCustomerRequest,
45    ) -> Result<CreateCustomerResponse, ApiError> {
46        let response = self.client.post(&self.url(), body).await?;
47
48        response.deserialize().await
49    }
50
51    /// Returns details for a single [Customer].
52    pub async fn retrieve_customer(
53        &self,
54        customer_id: &str,
55    ) -> Result<RetrieveCustomerResponse, ApiError> {
56        let url = format!("{}/{}", &self.url(), customer_id);
57        let response = self.client.get(&url).await?;
58
59        response.deserialize().await
60    }
61
62    /// Deletes a [Customer] profile from a business.
63    ///
64    /// This operation also unlinks any associated cards on file.
65    ///
66    /// As a best practice, you should include the version field in the request to enable optimistic
67    /// concurrency control. The value must be set to the current version of the customer profile.
68    ///
69    /// To delete a customer profile that was created by merging existing profiles, you must use the
70    /// ID of the newly created profile.
71    pub async fn delete_customer(
72        &self,
73        customer_id: &str,
74    ) -> Result<DeleteCustomerResponse, ApiError> {
75        let url = format!("{}/{}", &self.url(), customer_id);
76        let response = self.client.delete(&url).await?;
77
78        response.deserialize().await
79    }
80
81    /// Searches the [Customer] profiles associated with a Square account using a supported query
82    /// filter.
83    ///
84    /// Calling `SearchCustomers` without any explicit query filter returns all customer profiles
85    /// ordered alphabetically based on `given_name` and `family_name`.
86    ///
87    /// Under normal operating conditions, newly created or updated customer profiles become
88    /// available for the search operation in well under 30 seconds. Occasionally, propagation of
89    /// the new or updated profiles can take closer to one minute or longer, especially during
90    /// network incidents and outages.
91    pub async fn search_customers(
92        &self,
93        body: &SearchCustomersRequest,
94    ) -> Result<SearchCustomersResponse, ApiError> {
95        let url = format!("{}/search", &self.url());
96        let response = self.client.post(&url, body).await?;
97
98        response.deserialize().await
99    }
100
101    /// Lists [Customer] profiles associated with a Square account.
102    ///
103    /// Under normal operating conditions, newly created or updated customer profiles become
104    /// available for the listing operation in well under 30 seconds. Occasionally, propagation of
105    /// the new or updated profiles can take closer to one minute or longer, especially during
106    /// network incidents and outages.
107    pub async fn list_customers(
108        &self,
109        params: &ListCustomersParameters,
110    ) -> Result<ListCustomersResponse, ApiError> {
111        let url = format!("{}{}", &self.url(), params.to_query_string());
112        let response = self.client.get(&url).await?;
113
114        response.deserialize().await
115    }
116
117    /// Updates a [Customer] profile.
118    ///
119    /// To change an attribute, specify the new value. To remove an attribute, specify the value as
120    /// an empty string or empty object.
121    ///
122    /// As a best practice, you should include the `version` field in the request to enable
123    /// [optimistic
124    /// concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency)
125    /// control. The value must be set to the current version of the customer profile.
126    ///
127    /// To update a customer profile that was created by merging existing profiles, you must use the
128    /// ID of the newly created profile.
129    ///
130    /// You cannot use this endpoint to change cards on file. To make changes, use the [Cards
131    /// API](https://developer.squareup.com/reference/square/cards-api) or [Gift Cards
132    /// API](https://developer.squareup.com/reference/square/giftcards-api).
133    pub async fn update_customer(
134        &self,
135        customer_id: &str,
136        body: &UpdateCustomerRequest,
137    ) -> Result<UpdateCustomerResponse, ApiError> {
138        let url = format!("{}/{}", &self.url(), customer_id);
139        let response = self.client.put(&url, body).await?;
140
141        response.deserialize().await
142    }
143
144    fn url(&self) -> String {
145        format!("{}{}", &self.config.get_base_url(), DEFAULT_URI)
146    }
147}
square_api_client/api/customers_api.rs

square_api_client/api/
customers_api.rs
