square_api_client/api/orders_api.rs
1//! Get sales data for a Square seller, itemize payments, push orders to POS, and more.
2//!
3//! The Orders API is your one-stop shop for adding rich functionality to payments. You can itemize
4//! payments using custom line items or catalog objects, send orders to physical Point of Sale
5//! devices to be fulfilled, attach a customer to a payment, and more.
6//!
7//! In addition, the Orders API lets you search through all of a seller's past sales and returns
8//! itemization data, customer references, and other details from sales made using POS or online.
9//!
10//! If you use the Square Orders API with a non-Square payments provider, Square charges a
11//! transaction fee. For more information, see [Orders API fee
12//! structure](https://developer.squareup.com/docs/payments-pricing#orders-api-fee-structure).
13
14use crate::{
15 config::Configuration,
16 http::client::HttpClient,
17 models::{
18 errors::ApiError, BatchRetrieveOrdersRequest, BatchRetrieveOrdersResponse,
19 CalculateOrderRequest, CalculateOrderResponse, CloneOrderRequest, CloneOrderResponse,
20 CreateOrderRequest, CreateOrderResponse, PayOrderRequest, PayOrderResponse,
21 RetrieveOrderResponse, SearchOrdersRequest, SearchOrdersResponse, UpdateOrderRequest,
22 UpdateOrderResponse,
23 },
24};
25
26const DEFAULT_URI: &str = "/orders";
27
28/// Get sales data for a Square seller, itemize payments, push orders to POS, and more.
29pub struct OrdersApi {
30 /// App config information
31 config: Configuration,
32 /// HTTP Client for requests to the Orders API endpoints
33 client: HttpClient,
34}
35
36impl OrdersApi {
37 /// Instantiates a new `OrdersApi`
38 pub fn new(config: Configuration, client: HttpClient) -> Self {
39 Self { config, client }
40 }
41
42 /// Creates a new order that can include information about products for purchase and settings to apply to the purchase.
43 ///
44 /// To pay for a created order, see Pay for Orders.
45 ///
46 /// You can modify open orders using the UpdateOrder endpoint.
47 pub async fn create_order(
48 &self,
49 body: &CreateOrderRequest,
50 ) -> Result<CreateOrderResponse, ApiError> {
51 let response = self.client.post(&self.url(), body).await?;
52
53 response.deserialize().await
54 }
55
56 /// Retrieves a set of [orders](Order) by their IDs.
57 ///
58 /// If a given order ID does not exist, the ID is ignored instead of generating an error.
59 pub async fn batch_retrieve_orders(
60 &self,
61 body: &BatchRetrieveOrdersRequest,
62 ) -> Result<BatchRetrieveOrdersResponse, ApiError> {
63 let url = format!("{}/batch-retrieve", &self.url());
64 let response = self.client.post(&url, body).await?;
65
66 response.deserialize().await
67 }
68
69 /// Enables applications to preview order pricing without creating an order.
70 pub async fn calculate_order(
71 &self,
72 body: &CalculateOrderRequest,
73 ) -> Result<CalculateOrderResponse, ApiError> {
74 let url = format!("{}/calculate", &self.url());
75 let response = self.client.post(&url, body).await?;
76
77 response.deserialize().await
78 }
79
80 /// Creates a new order, in the `DRAFT` state, by duplicating an existing order.
81 ///
82 /// The newly created order has only the core fields (such as line items, taxes, and discounts)
83 /// copied from the original order.
84 pub async fn clone_order(
85 &self,
86 body: &CloneOrderRequest,
87 ) -> Result<CloneOrderResponse, ApiError> {
88 let url = format!("{}/clone", &self.url());
89 let response = self.client.post(&url, body).await?;
90
91 response.deserialize().await
92 }
93
94 /// Search all orders for one or more locations.
95 ///
96 /// Orders include all sales, returns, and exchanges regardless of how or when they entered the
97 /// Square ecosystem (such as Point of Sale, Invoices, and Connect APIs).
98 ///
99 /// `SearchOrders` requests need to specify which locations to search and define a
100 /// [SearchOrdersQuery] object that controls how to sort or filter the results. Your
101 /// `SearchOrdersQuery` can:
102 ///
103 /// Set filter criteria. Set the sort order. Determine whether to return results as complete
104 /// [Order] objects or as [OrderEntry] objects.
105 ///
106 /// Note that details for orders processed with Square Point of Sale while in offline mode might
107 /// not be transmitted to Square for up to 72 hours. Offline orders have a `created_at` value
108 /// that reflects the time the order was created, not the time it was subsequently transmitted
109 /// to Square.
110 pub async fn search_orders(
111 &self,
112 body: &SearchOrdersRequest,
113 ) -> Result<SearchOrdersResponse, ApiError> {
114 let url = format!("{}/search", &self.url());
115 let response = self.client.post(&url, body).await?;
116
117 response.deserialize().await
118 }
119
120 /// Retrieves an [Order] by ID.
121 pub async fn retrieve_order(&self, order_id: &str) -> Result<RetrieveOrderResponse, ApiError> {
122 let url = format!("{}/{}", &self.url(), order_id);
123 let response = self.client.get(&url).await?;
124
125 response.deserialize().await
126 }
127
128 /// Updates an open [Order] by adding, replacing, or deleting fields.
129 ///
130 /// Orders with a `COMPLETED` or `CANCELED` state cannot be updated.
131 ///
132 /// An `UpdateOrder` request requires the following:
133 ///
134 /// * The `order_id` in the endpoint path, identifying the order to update.
135 /// * The latest `version` of the order to update.
136 /// * The [sparse order](https://developer.squareup.com/docs/orders-api/manage-orders#sparse-order-objects)
137 /// containing only the fields to update and the version to which the update is being applied.
138 /// * If deleting fields, the [dot notation
139 /// paths](https://developer.squareup.com/docs/orders-api/manage-orders#on-dot-notation)
140 /// identifying the fields to clear.
141 ///
142 /// To pay for an order, see Pay for Orders.
143 pub async fn update_order(
144 &self,
145 order_id: &str,
146 body: &UpdateOrderRequest,
147 ) -> Result<UpdateOrderResponse, ApiError> {
148 let url = format!("{}/{}", &self.url(), order_id);
149 let response = self.client.put(&url, body).await?;
150
151 response.deserialize().await
152 }
153
154 /// Pay for an [Order] using one or more approved [Payment]s or settle an order with a total of
155 /// `0`.
156 ///
157 /// The total of the `payment_ids` listed in the request must be equal to the order total.
158 /// Orders with a total amount of `0` can be marked as paid by specifying an empty array of
159 /// `payment_ids` in the request.
160 ///
161 /// To be used with `PayOrder`, a payment must:
162 ///
163 /// * Reference the order by specifying the `order_id` when creating the payment. Any approved
164 /// payments that reference the same `order_id` not specified in the `payment_ids` is
165 /// canceled.
166 /// * Be approved with [delayed
167 /// capture](https://developer.squareup.com/docs/payments-api/take-payments#delayed-capture).
168 /// Using a delayed capture payment with `PayOrder` completes the approved payment.
169 pub async fn pay_order(
170 &self,
171 order_id: &str,
172 body: &PayOrderRequest,
173 ) -> Result<PayOrderResponse, ApiError> {
174 let url = format!("{}/{}/pay", &self.url(), order_id);
175 let response = self.client.post(&url, body).await?;
176
177 response.deserialize().await
178 }
179
180 /// Constructs the basic entity URL including domain and entity path. Any additional path
181 /// elements (e.g. path parameters) will need to be appended to this URL.
182 fn url(&self) -> String {
183 format!("{}{}", &self.config.get_base_url(), DEFAULT_URI)
184 }
185}