square_api_client/models/invoice.rs
1//! Model struct for Invoice type
2
3use serde::{Deserialize, Serialize};
4
5use super::{
6 enums::{InvoiceDeliveryMethod, InvoiceStatus, Timezone},
7 DateTime, InvoiceAcceptedPaymentMethods, InvoiceCustomField, InvoicePaymentRequest,
8 InvoiceRecipient, Money,
9};
10
11/// Stores information about an invoice.
12///
13/// You use the Invoices API to create and manage invoices. For more information, see [Invoices API
14/// Overview](https://developer.squareup.com/docs/invoices-api/overview).
15#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
16pub struct Invoice {
17 /// **Read only** The Square-assigned ID of the invoice.
18 pub id: Option<String>,
19 /// The payment methods that customers can use to pay the invoice on the Square-hosted invoice
20 /// page. This setting is independent of any automatic payment requests for the invoice.
21 ///
22 /// This field is required when creating an invoice and must set at least one payment method to
23 /// `true`.
24 pub accepted_payment_methods: Option<InvoiceAcceptedPaymentMethods>,
25 /// **Read only** The timestamp when the invoice was created, in RFC 3339 format.
26 pub created_at: Option<DateTime>,
27 /// Additional seller-defined fields that are displayed on the invoice. For more information,
28 /// see [Custom
29 /// fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).
30 ///
31 /// Adding custom fields to an invoice requires an [Invoices Plus
32 /// subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).
33 ///
34 /// Max: 2 custom fields
35 ///
36 /// Max Length: 2
37 pub custom_fields: Option<Vec<InvoiceCustomField>>,
38 /// The delivery method that Square uses to send the invoice, reminders, and receipts to the
39 /// customer. After the invoice is published, Square processes the invoice based on the delivery
40 /// method and payment request settings, either immediately or on the `scheduled_at` date, if
41 /// specified. For example, Square might send the invoice or receipt for an automatic payment.
42 /// For invoices with automatic payments, this field must be set to `EMAIL`.
43 ///
44 /// One of the following is required when creating an invoice:
45 ///
46 /// - (Recommended) This `delivery_method` field. To configure an automatic payment, the
47 /// `automatic_payment_source` field of the payment request is also required.
48 /// - The deprecated `request_method` field of the payment request. Note that `invoice` objects
49 /// returned in responses do not include `request_method`.
50 pub delivery_method: Option<InvoiceDeliveryMethod>,
51 /// The description of the invoice, which is displayed on the invoice.
52 ///
53 /// Min Length: 1, Max Length: 65536
54 pub description: Option<String>,
55 /// A user-friendly invoice number that is displayed on the invoice. The value is unique within
56 /// a location. If not provided when creating an invoice, Square assigns a value. It increments
57 /// from 1 and is padded with zeros making it 7 characters long (for example, 0000001 and
58 /// 0000002).
59 ///
60 /// Min Length: 1, Max Length: 191
61 pub invoice_number: Option<String>,
62 /// The ID of the location that this invoice is associated with.
63 ///
64 /// If specified in a `CreateInvoice` request, the value must match the `location_id` of the
65 /// associated order.
66 ///
67 /// Min Length: 1, Max Length: 255
68 pub location_id: Option<String>,
69 /// Read only The current amount due for the invoice. In addition to the amount due on the next
70 /// payment request, this includes any overdue payment amounts.
71 pub next_payment_amount_money: Option<Money>,
72 /// The ID of the [Order] for which the invoice is created. This field is required when creating
73 /// an invoice, and the order must be in the `OPEN` state.
74 ///
75 /// To view the line items and other information for the associated order, call the
76 /// [RetrieveOrder](https://developer.squareup.com/reference/square/orders-api/retrieve-order)
77 /// endpoint using the order ID.
78 ///
79 /// Min Length: 1, Max Length: 255
80 pub order_id: Option<String>,
81 /// **France only**. The payment terms and conditions that are displayed on the invoice. For
82 /// more information, see [Payment
83 /// conditions](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions).
84 ///
85 /// For countries other than France, Square returns an `INVALID_REQUEST_ERROR` with a
86 /// `BAD_REQUEST` code and "Payment conditions are not supported for this location's country"
87 /// detail if this field is included in `CreateInvoice` or `UpdateInvoice` requests.
88 ///
89 /// Min Length: 1, Max Length: 2000
90 pub payment_conditions: Option<String>,
91 /// The payment schedule for the invoice, represented by one or more payment requests that
92 /// define payment settings, such as amount due and due date. An invoice supports the following
93 /// payment request combinations:
94 ///
95 /// - One balance
96 /// - One deposit with one balance
97 /// - 2–12 installments
98 /// - One deposit with 2–12 installments
99 ///
100 /// This field is required when creating an invoice. It must contain at least one payment
101 /// request. All payment requests for the invoice must equal the total order amount. For more
102 /// information, see [Configuring payment
103 /// requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).
104 ///
105 /// Adding `INSTALLMENT` payment requests to an invoice requires an [Invoices Plus
106 /// subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).
107 ///
108 /// Min Length: 1, Max Length: 13
109 pub payment_requests: Option<Vec<InvoicePaymentRequest>>,
110 /// The customer who receives the invoice. This customer data is displayed on the invoice and
111 /// used by Square to deliver the invoice.
112 ///
113 /// This field is required to publish an invoice, and it must specify the `customer_id`.
114 pub primary_recipient: Option<InvoiceRecipient>,
115 /// **Read only** The URL of the Square-hosted invoice page. After you publish the invoice using
116 /// the `PublishInvoice` endpoint, Square hosts the invoice page and returns the page URL in the
117 /// response.
118 pub public_url: Option<String>,
119 /// The date of the sale or the date that the service is rendered, in `YYYY-MM-DD` format. This
120 /// field can be used to specify a past or future date which is displayed on the invoice.
121 pub sale_or_service_date: Option<String>,
122 /// The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the
123 /// invoice is published, Square processes the invoice on the specified date, according to the
124 /// delivery method and payment request settings.
125 ///
126 /// If the field is not set, Square processes the invoice immediately after it is published.
127 pub scheduled_at: Option<DateTime>,
128 /// **Read only** The status of the invoice.
129 pub status: Option<InvoiceStatus>,
130 /// Indicates whether to allow a customer to save a credit or debit card as a card on file or a
131 /// bank transfer as a bank account on file. If `true`, Square displays a **Save my card on
132 /// file** or **Save my bank on file** checkbox on the invoice payment page. Stored payment
133 /// information can be used for future automatic payments. The default value is `false`.
134 pub store_payment_method_enabled: Option<bool>,
135 /// **Read only** The ID of the
136 /// [subscription](https://developer.squareup.com/reference/square/objects/Subscription)
137 /// associated with the invoice. This field is present only on subscription billing invoices.
138 pub subscription_id: Option<String>,
139 /// Read only The time zone used to interpret calendar dates on the invoice, such as `due_date`.
140 /// When an invoice is created, this field is set to the `timezone` specified for the seller
141 /// location. The value cannot be changed.
142 pub timezone: Option<Timezone>,
143 /// The title of the invoice, which is displayed on the invoice.
144 ///
145 /// Min Length: 1, Max Length: 255
146 pub title: Option<String>,
147 /// **Read only** The timestamp when the invoice was last updated, in RFC 3339 format.
148 pub updated_at: Option<DateTime>,
149 /// The Square-assigned version number, which is incremented each time an update is committed to
150 /// the invoice.
151 pub version: Option<i32>,
152}