give / vendor / stripe / stripe-php / lib / Service / InvoiceService.php

InvoiceService.php in GiveWP – Donation Plugin and Fundraising Platform 4.15.5, at vendor/stripe/stripe-php/lib/Service/InvoiceService.php

293 lines 11.4 KB

Raw Download Zip

1	<?php
2
3	// File generated from our OpenAPI spec
4
5	namespace Stripe\Service;
6
7	class InvoiceService extends \Stripe\Service\AbstractService
8	{
9	/**
10	* You can list all invoices, or list the invoices for a specific customer. The
11	* invoices are returned sorted by creation date, with the most recently created
12	* invoices appearing first.
13	*
14	* @param null\|array $params
15	* @param null\|array\|\Stripe\Util\RequestOptions $opts
16	*
17	* @throws \Stripe\Exception\ApiErrorException if the request fails
18	*
19	* @return \Stripe\Collection<\Stripe\Invoice>
20	*/
21	public function all($params = null, $opts = null)
22	{
23	return $this->requestCollection('get', '/v1/invoices', $params, $opts);
24	}
25
26	/**
27	* When retrieving an invoice, you’ll get a <strong>lines</strong> property
28	* containing the total count of line items and the first handful of those items.
29	* There is also a URL where you can retrieve the full (paginated) list of line
30	* items.
31	*
32	* @param string $parentId
33	* @param null\|array $params
34	* @param null\|array\|\Stripe\Util\RequestOptions $opts
35	*
36	* @throws \Stripe\Exception\ApiErrorException if the request fails
37	*
38	* @return \Stripe\Collection<\Stripe\LineItem>
39	*/
40	public function allLines($parentId, $params = null, $opts = null)
41	{
42	return $this->requestCollection('get', $this->buildPath('/v1/invoices/%s/lines', $parentId), $params, $opts);
43	}
44
45	/**
46	* This endpoint creates a draft invoice for a given customer. The draft invoice
47	* created pulls in all pending invoice items on that customer, including
48	* prorations. The invoice remains a draft until you <a
49	* href="#finalize_invoice">finalize</a> the invoice, which allows you to <a
50	* href="#pay_invoice">pay</a> or <a href="#send_invoice">send</a> the invoice to
51	* your customers.
52	*
53	* @param null\|array $params
54	* @param null\|array\|\Stripe\Util\RequestOptions $opts
55	*
56	* @throws \Stripe\Exception\ApiErrorException if the request fails
57	*
58	* @return \Stripe\Invoice
59	*/
60	public function create($params = null, $opts = null)
61	{
62	return $this->request('post', '/v1/invoices', $params, $opts);
63	}
64
65	/**
66	* Permanently deletes a one-off invoice draft. This cannot be undone. Attempts to
67	* delete invoices that are no longer in a draft state will fail; once an invoice
68	* has been finalized or if an invoice is for a subscription, it must be <a
69	* href="#void_invoice">voided</a>.
70	*
71	* @param string $id
72	* @param null\|array $params
73	* @param null\|array\|\Stripe\Util\RequestOptions $opts
74	*
75	* @throws \Stripe\Exception\ApiErrorException if the request fails
76	*
77	* @return \Stripe\Invoice
78	*/
79	public function delete($id, $params = null, $opts = null)
80	{
81	return $this->request('delete', $this->buildPath('/v1/invoices/%s', $id), $params, $opts);
82	}
83
84	/**
85	* Stripe automatically finalizes drafts before sending and attempting payment on
86	* invoices. However, if you’d like to finalize a draft invoice manually, you can
87	* do so using this method.
88	*
89	* @param string $id
90	* @param null\|array $params
91	* @param null\|array\|\Stripe\Util\RequestOptions $opts
92	*
93	* @throws \Stripe\Exception\ApiErrorException if the request fails
94	*
95	* @return \Stripe\Invoice
96	*/
97	public function finalizeInvoice($id, $params = null, $opts = null)
98	{
99	return $this->request('post', $this->buildPath('/v1/invoices/%s/finalize', $id), $params, $opts);
100	}
101
102	/**
103	* Marking an invoice as uncollectible is useful for keeping track of bad debts
104	* that can be written off for accounting purposes.
105	*
106	* @param string $id
107	* @param null\|array $params
108	* @param null\|array\|\Stripe\Util\RequestOptions $opts
109	*
110	* @throws \Stripe\Exception\ApiErrorException if the request fails
111	*
112	* @return \Stripe\Invoice
113	*/
114	public function markUncollectible($id, $params = null, $opts = null)
115	{
116	return $this->request('post', $this->buildPath('/v1/invoices/%s/mark_uncollectible', $id), $params, $opts);
117	}
118
119	/**
120	* Stripe automatically creates and then attempts to collect payment on invoices
121	* for customers on subscriptions according to your <a
122	* href="https://dashboard.stripe.com/account/billing/automatic">subscriptions
123	* settings</a>. However, if you’d like to attempt payment on an invoice out of the
124	* normal collection schedule or for some other reason, you can do so.
125	*
126	* @param string $id
127	* @param null\|array $params
128	* @param null\|array\|\Stripe\Util\RequestOptions $opts
129	*
130	* @throws \Stripe\Exception\ApiErrorException if the request fails
131	*
132	* @return \Stripe\Invoice
133	*/
134	public function pay($id, $params = null, $opts = null)
135	{
136	return $this->request('post', $this->buildPath('/v1/invoices/%s/pay', $id), $params, $opts);
137	}
138
139	/**
140	* Retrieves the invoice with the given ID.
141	*
142	* @param string $id
143	* @param null\|array $params
144	* @param null\|array\|\Stripe\Util\RequestOptions $opts
145	*
146	* @throws \Stripe\Exception\ApiErrorException if the request fails
147	*
148	* @return \Stripe\Invoice
149	*/
150	public function retrieve($id, $params = null, $opts = null)
151	{
152	return $this->request('get', $this->buildPath('/v1/invoices/%s', $id), $params, $opts);
153	}
154
155	/**
156	* Search for invoices you’ve previously created using Stripe’s <a
157	* href="/docs/search#search-query-language">Search Query Language</a>. Don’t use
158	* search in read-after-write flows where strict consistency is necessary. Under
159	* normal operating conditions, data is searchable in less than a minute.
160	* Occasionally, propagation of new or updated data can be up to an hour behind
161	* during outages. Search functionality is not available to merchants in India.
162	*
163	* @param null\|array $params
164	* @param null\|array\|\Stripe\Util\RequestOptions $opts
165	*
166	* @throws \Stripe\Exception\ApiErrorException if the request fails
167	*
168	* @return \Stripe\SearchResult<\Stripe\Invoice>
169	*/
170	public function search($params = null, $opts = null)
171	{
172	return $this->requestSearchResult('get', '/v1/invoices/search', $params, $opts);
173	}
174
175	/**
176	* Stripe will automatically send invoices to customers according to your <a
177	* href="https://dashboard.stripe.com/account/billing/automatic">subscriptions
178	* settings</a>. However, if you’d like to manually send an invoice to your
179	* customer out of the normal schedule, you can do so. When sending invoices that
180	* have already been paid, there will be no reference to the payment in the email.
181	*
182	* Requests made in test-mode result in no emails being sent, despite sending an
183	* <code>invoice.sent</code> event.
184	*
185	* @param string $id
186	* @param null\|array $params
187	* @param null\|array\|\Stripe\Util\RequestOptions $opts
188	*
189	* @throws \Stripe\Exception\ApiErrorException if the request fails
190	*
191	* @return \Stripe\Invoice
192	*/
193	public function sendInvoice($id, $params = null, $opts = null)
194	{
195	return $this->request('post', $this->buildPath('/v1/invoices/%s/send', $id), $params, $opts);
196	}
197
198	/**
199	* At any time, you can preview the upcoming invoice for a customer. This will show
200	* you all the charges that are pending, including subscription renewal charges,
201	* invoice item charges, etc. It will also show you any discounts that are
202	* applicable to the invoice.
203	*
204	* Note that when you are viewing an upcoming invoice, you are simply viewing a
205	* preview – the invoice has not yet been created. As such, the upcoming invoice
206	* will not show up in invoice listing calls, and you cannot use the API to pay or
207	* edit the invoice. If you want to change the amount that your customer will be
208	* billed, you can add, remove, or update pending invoice items, or update the
209	* customer’s discount.
210	*
211	* You can preview the effects of updating a subscription, including a preview of
212	* what proration will take place. To ensure that the actual proration is
213	* calculated exactly the same as the previewed proration, you should pass a
214	* <code>proration_date</code> parameter when doing the actual subscription update.
215	* The value passed in should be the same as the
216	* <code>subscription_proration_date</code> returned on the upcoming invoice
217	* resource. The recommended way to get only the prorations being previewed is to
218	* consider only proration line items where <code>period[start]</code> is equal to
219	* the <code>subscription_proration_date</code> on the upcoming invoice resource.
220	*
221	* @param null\|array $params
222	* @param null\|array\|\Stripe\Util\RequestOptions $opts
223	*
224	* @throws \Stripe\Exception\ApiErrorException if the request fails
225	*
226	* @return \Stripe\Invoice
227	*/
228	public function upcoming($params = null, $opts = null)
229	{
230	return $this->request('get', '/v1/invoices/upcoming', $params, $opts);
231	}
232
233	/**
234	* When retrieving an upcoming invoice, you’ll get a <strong>lines</strong>
235	* property containing the total count of line items and the first handful of those
236	* items. There is also a URL where you can retrieve the full (paginated) list of
237	* line items.
238	*
239	* @param null\|array $params
240	* @param null\|array\|\Stripe\Util\RequestOptions $opts
241	*
242	* @throws \Stripe\Exception\ApiErrorException if the request fails
243	*
244	* @return \Stripe\Collection<\Stripe\Invoice>
245	*/
246	public function upcomingLines($params = null, $opts = null)
247	{
248	return $this->requestCollection('get', '/v1/invoices/upcoming/lines', $params, $opts);
249	}
250
251	/**
252	* Draft invoices are fully editable. Once an invoice is <a
253	* href="/docs/billing/invoices/workflow#finalized">finalized</a>, monetary values,
254	* as well as <code>collection_method</code>, become uneditable.
255	*
256	* If you would like to stop the Stripe Billing engine from automatically
257	* finalizing, reattempting payments on, sending reminders for, or <a
258	* href="/docs/billing/invoices/reconciliation">automatically reconciling</a>
259	* invoices, pass <code>auto_advance=false</code>.
260	*
261	* @param string $id
262	* @param null\|array $params
263	* @param null\|array\|\Stripe\Util\RequestOptions $opts
264	*
265	* @throws \Stripe\Exception\ApiErrorException if the request fails
266	*
267	* @return \Stripe\Invoice
268	*/
269	public function update($id, $params = null, $opts = null)
270	{
271	return $this->request('post', $this->buildPath('/v1/invoices/%s', $id), $params, $opts);
272	}
273
274	/**
275	* Mark a finalized invoice as void. This cannot be undone. Voiding an invoice is
276	* similar to <a href="#delete_invoice">deletion</a>, however it only applies to
277	* finalized invoices and maintains a papertrail where the invoice can still be
278	* found.
279	*
280	* @param string $id
281	* @param null\|array $params
282	* @param null\|array\|\Stripe\Util\RequestOptions $opts
283	*
284	* @throws \Stripe\Exception\ApiErrorException if the request fails
285	*
286	* @return \Stripe\Invoice
287	*/
288	public function voidInvoice($id, $params = null, $opts = null)
289	{
290	return $this->request('post', $this->buildPath('/v1/invoices/%s/void', $id), $params, $opts);
291	}
292	}
293