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