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}