File Coverage

lib/Net/API/Stripe/Billing/Invoice.pm
Criterion Covered Total %
statement 19 100 19.0
branch n/a
condition n/a
subroutine 7 88 7.9
pod 77 81 95.0
total 103 269 38.2


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## Stripe API - ~/lib/Net/API/Stripe/Billing/Invoice.pm
3             ## Version v0.101.1
4             ## Copyright(c) 2020 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2019/11/02
7             ## Modified 2020/11/20
8             ## All rights reserved
9             ##
10             ## This program is free software; you can redistribute it and/or modify it
11             ## under the same terms as Perl itself.
12             ##----------------------------------------------------------------------------
13             ## https://stripe.com/docs/api/invoices/object
14             package Net::API::Stripe::Billing::Invoice;
15             BEGIN
16             {
17 2     2   21331712 use strict;
  2         13  
  2         62  
18 2     2   11 use warnings;
  2         3  
  2         57  
19 2     2   12 use parent qw( Net::API::Stripe::Generic );
  2         3  
  2         10  
20 2     2   140 use vars qw( $VERSION );
  2         5  
  2         112  
21 2     2   36 our( $VERSION ) = 'v0.101.1';
22             };
23              
24 2     2   11 use strict;
  2         3  
  2         34  
25 2     2   11 use warnings;
  2         3  
  2         3115  
26              
27 0     0 1   sub id { return( shift->_set_get_scalar( 'id', @_ ) ); }
28              
29 0     0 1   sub object { return( shift->_set_get_scalar( 'object', @_ ) ); }
30              
31 0     0 1   sub account_country { return( shift->_set_get_scalar( 'account_country', @_ ) ); }
32              
33 0     0 1   sub account_name { return( shift->_set_get_scalar( 'account_name', @_ ) ); }
34              
35 0     0 1   sub account_tax_ids { return( shift->_set_get_object_array( 'account_tax_ids', 'Net::API::Stripe::Billing::TaxID', @_ ) ); }
36              
37 0     0 1   sub amount_due { return( shift->_set_get_number( 'amount_due', @_ ) ); }
38              
39 0     0 1   sub amount_paid { return( shift->_set_get_number( 'amount_paid', @_ ) ); }
40              
41 0     0 1   sub amount_remaining { return( shift->_set_get_number( 'amount_remaining', @_ ) ); }
42              
43 0     0 1   sub application { return( shift->_set_get_scalar_or_object( 'application', 'Net::API::Stripe::Connect::Account', @_ ) ); }
44              
45             ## 2019-03-14: Stripe renamed this to application_fee
46             # sub application_fee { return( shift->_set_get_number( 'application_fee', @_ ) ); }
47 0     0 0   sub application_fee { return( shift->application_fee_amount( @_ ) ); }
48              
49 0     0 1   sub application_fee_amount { return( shift->_set_get_number( 'application_fee_amount', @_ ) ); }
50              
51 0     0 1   sub attempt_count { return( shift->_set_get_scalar( 'attempt_count', @_ ) ); }
52              
53 0     0 1   sub attempted { return( shift->_set_get_boolean( 'attempted', @_ ) ); }
54              
55 0     0 1   sub auto_advance { return( shift->_set_get_boolean( 'auto_advance', @_ ) ); }
56              
57 0     0 1   sub automatic_tax { return( shift->_set_get_class( 'automatic_tax',
58             {
59             enabled => { type => 'boolean' },
60             status => { type => 'string' },
61             }, @_ ) ); }
62              
63 0     0 1   sub billing { return( shift->_set_get_scalar( 'billing', @_ ) ); }
64              
65 0     0 1   sub billing_reason { return( shift->_set_get_scalar( 'billing_reason', @_ ) ); }
66              
67 0     0 1   sub charge { return( shift->_set_get_scalar_or_object( 'charge', 'Net::API::Stripe::Charge', @_ ) ); }
68              
69 0     0 0   sub closed { return( shift->_set_get_scalar( 'closed', @_ ) ); }
70              
71 0     0 1   sub collection_method { return( shift->_set_get_scalar( 'collection_method', @_ ) ); }
72              
73 0     0 1   sub created { return( shift->_set_get_datetime( 'created', @_ ) ); }
74              
75 0     0 1   sub currency { return( shift->_set_get_scalar( 'currency', @_ ) ); }
76              
77 0     0 1   sub custom_fields { return( shift->_set_get_object_array( 'custom_fields', 'Net::API::Stripe::CustomField', @_ ) ); }
78              
79 0     0 1   sub customer { return( shift->_set_get_scalar_or_object( 'customer', 'Net::API::Stripe::Customer', @_ ) ); }
80              
81 0     0 1   sub customer_address { return( shift->_set_get_object( 'customer_address', 'Net::API::Stripe::Address', @_ ) ); }
82              
83 0     0 1   sub customer_email { return( shift->_set_get_scalar( 'customer_email', @_ ) ); }
84              
85 0     0 1   sub customer_name { return( shift->_set_get_scalar( 'customer_name', @_ ) ); }
86              
87 0     0 1   sub customer_phone { return( shift->_set_get_scalar( 'customer_phone', @_ ) ); }
88              
89 0     0 1   sub customer_shipping { return( shift->_set_get_object( 'customer_shipping', 'Net::API::Stripe::Shipping', @_ ) ); }
90              
91 0     0 1   sub customer_tax_exempt { return( shift->_set_get_scalar( 'customer_tax_exempt', @_ ) ); }
92              
93 0     0 1   sub customer_tax_ids { return( shift->_set_get_object_array( 'customer_tax_ids', 'Net::API::Stripe::Customer::TaxId', @_ ) ); }
94              
95 0     0 1   sub date { return( shift->_set_get_datetime( 'date', @_ ) ); }
96              
97 0     0 1   sub default_payment_method { return( shift->_set_get_scalar_or_object( 'default_payment_method', 'Net::API::Stripe::Payment::Method', @_ ) ); }
98              
99 0     0 1   sub default_source { return( shift->_set_get_scalar_or_object( 'default_source', 'Net::API::Stripe::Payment::Source', @_ ) ); }
100              
101 0     0 1   sub default_tax_rates { return( shift->_set_get_object_array( 'default_tax_rates', 'Net::API::Stripe::Tax::Rate', @_ ) ); }
102              
103 0     0 1   sub description { return( shift->_set_get_scalar( 'description', @_ ) ); }
104              
105 0     0 1   sub discount { return( shift->_set_get_object( 'discount', 'Net::API::Stripe::Billing::Discount', @_ ) ); }
106              
107 0     0 1   sub discounts { return( shift->_set_get_scalar_or_object_array( 'discounts', 'Net::API::Stripe::Billing::Discount', @_ ) ); }
108              
109 0     0 1   sub due_date { return( shift->_set_get_datetime( 'due_date', @_ ) ); }
110              
111 0     0 1   sub ending_balance { return( shift->_set_get_number( 'ending_balance', @_ ) ); }
112              
113 0     0 1   sub footer { return( shift->_set_get_scalar( 'footer', @_ ) ); }
114              
115 0     0 1   sub forgiven { return( shift->_set_get_boolean( 'forgiven', @_ ) ); }
116              
117             ## Not used anymore? It's not on the API documentation
118 0     0 0   sub hosted_invoice_payment_pending { return( shift->_set_get_scalar( 'hosted_invoice_payment_pending', @_ ) ); }
119              
120 0     0 1   sub hosted_invoice_url { return( shift->_set_get_uri( 'hosted_invoice_url', @_ ) ); }
121              
122 0     0 1   sub invoice_pdf { return( shift->_set_get_uri( 'invoice_pdf', @_ ) ); }
123              
124 0     0 1   sub last_finalization_error { return( shift->_set_get_class( 'last_finalization_error',
125             {
126             code => { type => "scalar" },
127             doc_url => { type => "scalar" },
128             message => { type => "scalar" },
129             param => { type => "scalar" },
130             payment_method_type => { type => "scalar" },
131             type => { type => "scalar" },
132             }, @_ ) ); }
133              
134 0     0 1   sub lines { return( shift->_set_get_object( 'lines', 'Net::API::Stripe::Billing::Invoice::Lines', @_ ) ); }
135              
136 0     0 1   sub livemode { return( shift->_set_get_boolean( 'livemode', @_ ) ); }
137              
138 0     0 1   sub metadata { return( shift->_set_get_hash( 'metadata', @_ ) ); }
139              
140 0     0 1   sub next_payment_attempt { return( shift->_set_get_datetime( 'next_payment_attempt', @_ ) ); }
141              
142 0     0 1   sub number { return( shift->_set_get_scalar( 'number', @_ ) ); }
143              
144 0     0 1   sub on_behalf_of { return( shift->_set_get_scalar_or_object( 'on_behalf_of', 'Net::API::Stripe::Connect::Account', @_ ) ); }
145              
146 0     0 1   sub paid { return( shift->_set_get_boolean( 'paid', @_ ) ); }
147              
148 0     0 1   sub paid_out_of_band { return( shift->_set_get_boolean( 'paid_out_of_band', @_ ) ); }
149              
150 0     0 1   sub payment_intent { return( shift->_set_get_scalar_or_object( 'payment_intent', 'Net::API::Stripe::Payment::Intent', @_ ) ); }
151              
152 0     0 1   sub payment_settings { return( shift->_set_get_object( 'payment_settings', 'Net::API::Stripe::Payment::Settings', @_ ) ); }
153              
154 0     0 1   sub period_end { return( shift->_set_get_datetime( 'period_end', @_ ) ); }
155              
156 0     0 1   sub period_start { return( shift->_set_get_datetime( 'period_start', @_ ) ); }
157              
158 0     0 1   sub post_payment_credit_notes_amount { return( shift->_set_get_number( 'post_payment_credit_notes_amount', @_ ) ); }
159              
160 0     0 1   sub pre_payment_credit_notes_amount { return( shift->_set_get_number( ' pre_payment_credit_notes_amount', @_ ) ); }
161              
162 0     0 1   sub quote { return( shift->_set_get_scalar_or_object( 'quote', 'Net::API::Stripe::Billing::Quote', @_ ) ); }
163              
164 0     0 1   sub receipt_number { return( shift->_set_get_scalar( 'receipt_number', @_ ) ); }
165              
166 0     0 1   sub rendering_options { return( shift->_set_get_class( 'rendering_options',
167             {
168             amount_tax_display => { type => 'string' },
169             }, @_ ) ); }
170              
171 0     0 1   sub starting_balance { return( shift->_set_get_number( 'starting_balance', @_ ) ); }
172              
173 0     0 1   sub statement_descriptor { return( shift->_set_get_scalar( 'statement_descriptor', @_ ) ); }
174              
175 0     0 1   sub status { return( shift->_set_get_scalar( 'status', @_ ) ); }
176              
177 0     0 1   sub status_transitions { return( shift->_set_get_object( 'status_transitions', 'Net::API::Stripe::Billing::Invoice::StatusTransition', @_ ) ); }
178              
179 0     0 1   sub subscription { return( shift->_set_get_scalar_or_object( 'subscription', 'Net::API::Stripe::Billing::Subscription', @_ ) ); }
180              
181 0     0 1   sub subscription_proration_date { return( shift->_set_get_scalar( 'subscription_proration_date', @_ ) ); }
182              
183 0     0 1   sub subtotal { return( shift->_set_get_number( 'subtotal', @_ ) ); }
184              
185 0     0 1   sub subtotal_excluding_tax { return( shift->_set_get_number( 'subtotal_excluding_tax', @_ ) ); }
186              
187 0     0 1   sub tax { return( shift->_set_get_number( 'tax', @_ ) ); }
188              
189             # Does not seem to exist anymore in the API documentation...
190 0     0 0   sub tax_percent { return( shift->_set_get_number( 'tax_percent', @_ ) ); }
191              
192 0     0 1   sub test_clock { return( shift->_set_get_scalar_or_object( 'test_clock', 'Net::API::Stripe::Billing::TestClock', @_ ) ); }
193              
194 0     0 1   sub threshold_reason { return( shift->_set_get_hash( 'threshold_reason', @_ ) ); }
195              
196 0     0 1   sub total { return( shift->_set_get_number( 'total', @_ ) ); }
197              
198             sub total_discount_amounts
199             {
200 0     0 1   return( shift->_set_get_class_array( 'total_discount_amounts',
201             {
202             amount => { type => 'number' },
203             discount => { type => 'object', class => 'Net::API::Stripe::Billing::Discount' },
204             }, @_ ) );
205             }
206              
207 0     0 1   sub total_excluding_tax { return( shift->_set_get_number( 'total_excluding_tax', @_ ) ); }
208              
209 0     0 1   sub total_tax_amounts { return( shift->_set_get_object_array( 'total_tax_amounts', 'Net::API::Stripe::Billing::Invoice::TaxAmount', @_ ) ); }
210              
211 0     0 1   sub transfer_data { return( shift->_set_get_class( 'transfer_data', {
212             amount => { type => "number" },
213             destination => { type => "scalar" },
214             }, @_ ) ); }
215              
216 0     0 1   sub webhooks_delivered_at { return( shift->_set_get_datetime( 'webhooks_delivered_at', @_ ) ); }
217              
218             1;
219              
220             __END__
221              
222             =encoding utf8
223              
224             =head1 NAME
225              
226             Net::API::Stripe::Billing::Invoice - A Stripe Invoice
227              
228             =head1 SYNOPSIS
229              
230             my $stripe = Net::API::Stripe->new( conf_file => './settings.json', expand => 'all' ) || die( Net::API::Stripe->error );
231             my $inv = $stripe->invoices( create =>
232             {
233             account_country => 'jp',
234             account_name => 'John Doe',
235             amount_due => 2000,
236             amount_paid => 500,
237             amount_remaining => 1500
238             billing => 'charge_automatically',
239             charge => 'ch_fake123456789',
240             currency => 'jpy',
241             customer => $customer_object,
242             customer_address => $stripe->address({
243             line1 => '1-2-3 Sugamo, Bukyo-ku',
244             line2 => 'Taro Bldg'.
245             city => 'Tokyo',
246             postal_code => '123-4567',
247             country => 'jp',
248             }),
249             customer_email => 'john.doe@example.com',
250             customer_name => 'John Doe',
251             description => 'Invoice for professional services',
252             due_date => '2020-04-01',
253             }) || die( $stripe->error );
254              
255             =head1 VERSION
256              
257             v0.101.1
258              
259             =head1 DESCRIPTION
260              
261             Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription.
262              
263             They contain invoice items (L<Net::API::Stripe::Billing::Invoice::Item> / L<https://stripe.com/docs/api/invoices#invoiceitems>), and proration adjustments that may be caused by subscription upgrades/downgrades (if necessary).
264              
265             If your invoice is configured to be billed through automatic charges, Stripe automatically finalizes your invoice and attempts payment. Note that finalizing the invoice, when automatic (L<https://stripe.com/docs/billing/invoices/workflow/#auto_advance>), does not happen immediately as the invoice is created. Stripe waits until one hour after the last webhook was successfully sent (or the last webhook timed out after failing). If you (and the platforms you may have connected to) have no webhooks configured, Stripe waits one hour after creation to finalize the invoice.
266              
267             If your invoice is configured to be billed by sending an email, then based on your email settings, Stripe will email the invoice to your customer and await payment. These emails can contain a link to a hosted page to pay the invoice.
268              
269             Stripe applies any customer credit on the account before determining the amount due for the invoice (i.e., the amount that will be actually charged). If the amount due for the invoice is less than L<Stripe's minimum allowed charge per currency|https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts>, the invoice is automatically marked paid, and Stripe adds the amount due to the customer's running account balance which is applied to the next invoice.
270              
271             More details on the customer's account balance are L<here|https://stripe.com/docs/api/customers/object#customer_object-account_balance>.
272              
273             =head1 CONSTRUCTOR
274              
275             =head2 new
276              
277             Provided with an hash of key-value properties and this creates a new L<Net::API::Stripe::Billing::Invoice> object.
278              
279             =head1 METHODS
280              
281             =head2 id string
282              
283             Unique identifier for the object.
284              
285             =head2 object string, value is "invoice"
286              
287             String representing the object’s type. Objects of the same type share the same value.
288              
289             =head2 account_country string
290              
291             The country of the business associated with this invoice, most often the business creating the invoice.
292              
293             =head2 account_name string
294              
295             The public name of the business associated with this invoice, most often the business creating the invoice.
296              
297             =head2 account_tax_ids array containing strings expandable
298              
299             The account tax IDs associated with the invoice. Only editable when the invoice is a draft.
300              
301             When expanded, this contains an array of L<Net::API::Stripe::Billing::TaxID> objects.
302              
303             =head2 amount_due integer
304              
305             Final amount due at this time for this invoice. If the invoice’s total is smaller than the minimum charge amount, for example, or if there is account credit that can be applied to the invoice, the amount_due may be 0. If there is a positive starting_balance for the invoice (the customer owes money), the amount_due will also take that into account. The charge that gets generated for the invoice will be for the amount specified in amount_due.
306              
307             =head2 amount_paid integer
308              
309             The amount, in JPY, that was paid.
310              
311             =head2 amount_remaining integer
312              
313             The amount remaining, in JPY, that is due.
314              
315             =head2 application
316              
317             Expandable.
318              
319             Set or gets an L<Net::API::Stripe::Connect::Account> object or id.
320              
321             ID of the Connect Application that created the invoice.
322              
323             =head2 application_fee_amount integer
324              
325             The fee in JPY that will be applied to the invoice and transferred to the application owner’s Stripe account when the invoice is paid.
326              
327             =head2 attempt_count positive integer or zero
328              
329             Number of payment attempts made for this invoice, from the perspective of the payment retry schedule. Any payment attempt counts as the first attempt, and subsequently only automatic retries increment the attempt count. In other words, manual payment attempts after the first attempt do not affect the retry schedule.
330              
331             =head2 attempted boolean
332              
333             Whether an attempt has been made to pay the invoice. An invoice is not attempted until 1 hour after the invoice.created webhook, for example, so you might not want to display that invoice as unpaid to your users.
334              
335             =head2 auto_advance boolean
336              
337             Controls whether Stripe will perform automatic collection of the invoice. When false, the invoice’s state will not automatically advance without an explicit action.
338              
339             =head2 automatic_tax hash
340              
341             Settings and latest results for automatic tax lookup for this invoice.
342              
343             =over 4
344              
345             =item * C<enabled> boolean
346              
347             Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified tax rates, negative amounts, or tax_behavior=unspecified) cannot be added to automatic tax invoices.
348              
349             =item * C<status> enum
350              
351             The status of the most recent automated tax calculation for this invoice.
352              
353             Possible enum values
354              
355             =over 8
356              
357             =item * C<requires_location_inputs>
358              
359             The location details supplied on the customer aren’t valid or don’t provide enough location information to accurately determine tax rates for the customer.
360              
361             =item * C<complete>
362              
363             Stripe successfully calculated tax automatically on this invoice.
364              
365             =item * C<failed>
366              
367             The Stripe Tax service failed, please try again later.
368              
369             =back
370              
371             =back
372              
373             =head2 billing string
374              
375             This is an undocumented property, but that appears in Stripe's own API object example. It contains C<charge_automatically>
376              
377             =head2 billing_reason string
378              
379             Indicates the reason why the invoice was created. subscription_cycle indicates an invoice created by a subscription advancing into a new period. subscription_create indicates an invoice created due to creating a subscription. subscription_update indicates an invoice created due to updating a subscription. subscription is set for all old invoices to indicate either a change to a subscription or a period advancement. manual is set for all invoices unrelated to a subscription (for example: created via the invoice editor). The upcoming value is reserved for simulated invoices per the upcoming invoice endpoint. subscription_threshold indicates an invoice created due to a billing threshold being reached.
380              
381             =head2 charge string (expandable)
382              
383             ID of the latest charge generated for this invoice, if any. When expanded, this is a L<Net::API::Stripe::Charge> object.
384              
385             =head2 collection_method string
386              
387             Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay this invoice using the default source attached to the customer. When sending an invoice, Stripe will email this invoice to the customer with payment instructions.
388              
389             =head2 created timestamp
390              
391             Time at which the object was created. Measured in seconds since the Unix epoch.
392              
393             =head2 currency currency
394              
395             Three-letter ISO currency code, in lowercase. Must be a supported currency.
396              
397             =head2 custom_fields array of hashes
398              
399             Custom fields displayed on the invoice. This is an array of L<Net::API::Stripe::CustomField> objects.
400              
401             =over 4
402              
403             =item * <name>
404              
405             The name of the custom field.
406              
407             =item * <value>
408              
409             The value of the custom field.
410              
411             =back
412              
413             =head2 customer string (expandable)
414              
415             This is a Stripe Customer id, or when expanded, this is a L<Net::API::Stripe::Customer> object.
416              
417             =head2 customer_address hash
418              
419             The customer’s address. Until the invoice is finalized, this field will equal customer.address. Once the invoice is finalised, this field will no longer be updated.
420              
421             This is a L<Net::API::Stripe::Address> object.
422              
423             =head2 customer_email string
424              
425             The customer’s email. Until the invoice is finalized, this field will equal customer.email. Once the invoice is finalised, this field will no longer be updated.
426              
427             =head2 customer_name string
428              
429             The customer’s name. Until the invoice is finalized, this field will equal customer.name. Once the invoice is finalized, this field will no longer be updated.
430              
431             =head2 customer_phone string
432              
433             The customer’s phone number. Until the invoice is finalized, this field will equal customer.phone. Once the invoice is finalized, this field will no longer be updated.
434              
435             =head2 customer_shipping hash
436              
437             The customer’s shipping information. Until the invoice is finalized, this field will equal customer.shipping. Once the invoice is finalized, this field will no longer be updated.
438              
439             This is a L<Net::API::Stripe::Shipping> object.
440              
441             =head2 customer_tax_exempt string
442              
443             The customer’s tax exempt status. Until the invoice is finalized, this field will equal customer.tax_exempt. Once the invoice is finalized, this field will no longer be updated.
444              
445             =head2 customer_tax_ids array of hashes
446              
447             The customer’s tax IDs. Until the invoice is finalized, this field will contain the same tax IDs as customer.tax_ids. Once the invoice is finalized, this field will no longer be updated.
448              
449             This is a L<Net::API::Stripe::Customer::TaxIds> object.
450              
451             =head2 default_payment_method string (expandable)
452              
453             ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription’s default payment method, if any, or to the default payment method in the customer’s invoice settings.
454              
455             When expanded, this is a L<Net::API::Stripe::Payment::Method> object.
456              
457             =head2 default_source string (expandable)
458              
459             ID of the default payment source for the invoice. It must belong to the customer associated with the invoice and be in a chargeable state. If not set, defaults to the subscription’s default source, if any, or to the customer’s default source.
460              
461             When expanded, this is a L<Net::API::Stripe::Payment::Source> object.
462              
463             =head2 default_tax_rates array of hashes
464              
465             The tax rates applied to this invoice, if any.
466              
467             This is an array of L<Net::API::Stripe::Tax::Rate> object.
468              
469             =head2 description string
470              
471             An arbitrary string attached to the object. Often useful for displaying to users. Referenced as ‘memo’ in the Dashboard.
472              
473             =head2 discount hash, discount object
474              
475             This is a L<Net::API::Stripe::Billing::Discount> object
476              
477             =head2 discounts expandable
478              
479             The discounts applied to the invoice. Line item discounts are applied before invoice discounts. Use `expand[]=discounts` to expand each discount.
480              
481             When expanded this is an L<Net::API::Stripe::Billing::Discount> object.
482              
483             =head2 due_date timestamp
484              
485             The date on which payment for this invoice is due. This value will be null for invoices where collection_method=charge_automatically.
486              
487             =head2 ending_balance integer
488              
489             Ending customer balance after the invoice is finalized. Invoices are finalized approximately an hour after successful webhook delivery or when payment collection is attempted for the invoice. If the invoice has not been finalized yet, this will be null.
490              
491             =head2 footer string
492              
493             Footer displayed on the invoice.
494              
495             =head2 forgiven boolean
496              
497             Boolean value defining if the invoice was paid.
498              
499             Not part of the Stripe documentation anymore but present in data returned.
500              
501             =head2 hosted_invoice_url string
502              
503             The URL for the hosted invoice page, which allows customers to view and pay an invoice. If the invoice has not been finalized yet, this will be null.
504              
505             =head2 invoice_pdf string
506              
507             The link to download the PDF for the invoice. If the invoice has not been finalized yet, this will be null.
508              
509             =head2 last_finalization_error hash
510              
511             The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
512              
513             It has the following properties:
514              
515             =over 4
516              
517             =item I<code> string
518              
519             For some errors that could be handled programmatically, a short string indicating the [error code](/docs/error-codes) reported.
520              
521             =item I<doc_url> string
522              
523             A URL to more information about the [error code](/docs/error-codes) reported.
524              
525             =item I<message> string
526              
527             A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.
528              
529             =item I<param> string
530              
531             If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field.
532              
533             =item I<payment_method_type> string
534              
535             If the error is specific to the type of payment method, the payment method type that had a problem. This field is only populated for invoice-related errors.
536              
537             =item I<type> string
538              
539             The type of error returned. One of C<api_connection_error>, C<api_error>, C<authentication_error>, C<card_error>, C<idempotency_error>, C<invalid_request_error>, or C<rate_limit_error>
540              
541             =back
542              
543             =head2 lines list
544              
545             The individual line items that make up the invoice. lines is sorted as follows: invoice items in reverse chronological order, followed by the subscription, if any.
546              
547             This is a L<Net::API::Stripe::Billing::Invoice::Lines> object.
548              
549             =head2 livemode boolean
550              
551             Has the value true if the object exists in live mode or the value false if the object exists in test mode.
552              
553             =head2 metadata hash
554              
555             Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
556              
557             =head2 next_payment_attempt timestamp
558              
559             The time at which payment will next be attempted. This value will be null for invoices where collection_method=send_invoice.
560              
561             =head2 number string
562              
563             A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer’s unique invoice_prefix if it is specified.
564              
565             =head2 on_behalf_of
566              
567             Expandable
568              
569             Sets or gets an L<Net::API::Stripe::Connect::Account> object or id.
570              
571             =head2 paid boolean
572              
573             Whether payment was successfully collected for this invoice. An invoice can be paid (most commonly) with a charge or with credit from the customer’s account balance.
574              
575             =head2 paid_out_of_band boolean
576              
577             Returns true if the invoice was manually marked paid, returns false if the invoice hasn’t been paid yet or was paid on Stripe.
578              
579             =head2 payment_intent string (expandable)
580              
581             The PaymentIntent associated with this invoice. The PaymentIntent is generated when the invoice is finalized, and can then be used to pay the invoice. Note that voiding an invoice will cancel the PaymentIntent.
582              
583             When expanded, this is a L<Net::API::Stripe::Payment::Intent> object.
584              
585             =head2 payment_settings hash
586              
587             Sets or gets a L<Net::API::Stripe::Payment::Settings> object.
588              
589             =head2 period_end timestamp
590              
591             End of the usage period during which invoice items were added to this invoice.
592              
593             =head2 period_start timestamp
594              
595             Start of the usage period during which invoice items were added to this invoice.
596              
597             =head2 post_payment_credit_notes_amount integer
598              
599             Total amount of all post-payment credit notes issued for this invoice.
600              
601             =head2 pre_payment_credit_notes_amount integer
602              
603             Total amount of all pre-payment credit notes issued for this invoice.
604              
605             =head2 quote
606              
607             Expandable.
608              
609             Sets or gets a L<Net::API::Stripe::Billing::Quote> object or id.
610              
611             =head2 receipt_number string
612              
613             This is the transaction number that appears on email receipts sent for this invoice.
614              
615             =head2 rendering_options hash
616              
617             Options for invoice PDF rendering.
618              
619             =over 4
620              
621             =item * C<amount_tax_display> string
622              
623             How line-item prices and amounts will be displayed with respect to tax on invoice PDFs.
624              
625             =back
626              
627             =head2 starting_balance integer
628              
629             Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance.
630              
631             =head2 statement_descriptor string
632              
633             Extra information about an invoice for the customer’s credit card statement.
634              
635             =head2 status string
636              
637             The status of the invoice, one of draft, open, paid, uncollectible, or void. Learn more
638              
639             =head2 status_transitions hash
640              
641             This is a L<Net::API::Stripe::Billing::Invoice::StatusTransition> object.
642              
643             =head2 subscription string (expandable)
644              
645             The subscription that this invoice was prepared for, if any. When expanded, this is a L<Net::API::Stripe::Billing::Subscription> object.
646              
647             =head2 subscription_proration_date integer
648              
649             Only set for upcoming invoices that preview prorations. The time used to calculate prorations.
650              
651             =head2 subtotal integer
652              
653             Total of all subscriptions, invoice items, and prorations on the invoice before any discount or tax is applied.
654              
655             =head2 subtotal_excluding_tax integer
656              
657             The integer amount in JPY representing the subtotal of the invoice before any invoice level discount or tax is applied. Item discounts are already incorporated
658              
659             =head2 tax integer
660              
661             The amount of tax on this invoice. This is the sum of all the tax amounts on this invoice.
662              
663             =head2 test_clock string
664              
665             Expandable
666              
667             Sets or gets the L<Net::API::Stripe::Billing::TestClock> object or ID of the test clock this invoice belongs to.
668              
669             =head2 threshold_reason hash
670              
671             If billing_reason is set to subscription_threshold this returns more information on which threshold rules triggered the invoice.
672              
673             =over 4
674              
675             =item * C<amount_gte> integer
676              
677             The total invoice amount threshold boundary if it triggered the threshold invoice.
678              
679             =item * C<item_reasons> array of hashes
680              
681             Indicates which line items triggered a threshold invoice.
682              
683             =over 8
684              
685             =item * C<line_item_ids> array containing strings
686              
687             The IDs of the line items that triggered the threshold invoice.
688              
689             =item * C<usage_gte> integer
690              
691             The quantity threshold boundary that applied to the given line item.
692              
693             =back
694              
695             =back
696              
697             =head2 total integer
698              
699             Total after discounts and taxes.
700              
701             =head2 total_discount_amounts array of hashes
702              
703             The aggregate amounts calculated per discount across all line items.
704              
705             =over 4
706              
707             =item * C<amount> integer
708              
709             The amount, in JPY, of the discount.
710              
711             =item * C<discount> string
712              
713             Expandable
714              
715             The discount that was applied to get this discount amount.
716              
717             =back
718              
719             =head2 total_excluding_tax integer
720              
721             The integer amount in JPY representing the total amount of the invoice including all discounts but excluding all tax.
722              
723             Properties are:
724              
725             =over 4
726              
727             =item I<amount> integer
728              
729             The amount, in JPY, of the discount.
730              
731             =item I<discount> string expandable
732              
733             The discount that was applied to get this discount amount.
734              
735             =back
736              
737             =head2 total_tax_amounts array of hashes
738              
739             The aggregate amounts calculated per tax rate for all line items.
740              
741             This is an array of L<Net::API::Stripe::Billing::Invoice::TaxAmount> objects.
742              
743             =head2 transfer_data hash
744              
745             The account (if any) the payment will be attributed to for tax reporting, and where funds from the payment will be transferred to for the invoice.
746              
747             It has the following properties:
748              
749             =over 4
750              
751             =item I<amount> integer
752              
753             The amount in JPY that will be transferred to the destination account when the invoice is paid. By default, the entire amount is transferred to the destination.
754              
755             =item I<destination> string
756              
757             The account where funds from the payment will be transferred to upon payment success.
758              
759             =back
760              
761             =head2 webhooks_delivered_at timestamp
762              
763             The time at which webhooks for this invoice were successfully delivered (if the invoice had no webhooks to deliver, this will match created). Invoice payment is delayed until webhooks are delivered, or until all webhook delivery attempts have been exhausted.
764              
765             =head1 API SAMPLE
766              
767             {
768             "id": "in_fake1234567890",
769             "object": "invoice",
770             "account_country": "JP",
771             "account_name": "Angels, Inc",
772             "account_tax_ids": null,
773             "amount_due": 5300,
774             "amount_paid": 0,
775             "amount_remaining": 5300,
776             "application": null,
777             "application_fee_amount": null,
778             "attempt_count": 0,
779             "attempted": false,
780             "auto_advance": true,
781             "automatic_tax": {
782             "enabled": false,
783             "status": null
784             },
785             "billing_reason": "manual",
786             "charge": null,
787             "collection_method": "charge_automatically",
788             "created": 1657660441,
789             "currency": "jpy",
790             "custom_fields": null,
791             "customer": "cus_fake123456789990",
792             "customer_address": null,
793             "customer_email": null,
794             "customer_name": null,
795             "customer_phone": null,
796             "customer_shipping": null,
797             "customer_tax_exempt": "none",
798             "customer_tax_ids": [],
799             "default_payment_method": null,
800             "default_source": null,
801             "default_tax_rates": [],
802             "description": null,
803             "discount": null,
804             "discounts": [],
805             "due_date": null,
806             "ending_balance": null,
807             "footer": null,
808             "hosted_invoice_url": null,
809             "invoice_pdf": null,
810             "last_finalization_error": null,
811             "lines": {
812             "object": "list",
813             "data": [
814             {
815             "id": "il_fake1234567890",
816             "object": "line_item",
817             "amount": 5300,
818             "amount_excluding_tax": 5300,
819             "currency": "jpy",
820             "description": "My First Invoice Item (created for API docs)",
821             "discount_amounts": [],
822             "discountable": true,
823             "discounts": [],
824             "invoice_item": "ii_fake1234567890",
825             "livemode": false,
826             "metadata": {},
827             "period": {
828             "end": 1657660440,
829             "start": 1657660440
830             },
831             "price": {
832             "id": "price_fake1234567890",
833             "object": "price",
834             "active": true,
835             "billing_scheme": "per_unit",
836             "created": 1649731261,
837             "currency": "jpy",
838             "custom_unit_amount": null,
839             "livemode": false,
840             "lookup_key": null,
841             "metadata": {},
842             "nickname": null,
843             "product": "prod_fake1234567890",
844             "recurring": null,
845             "tax_behavior": "unspecified",
846             "tiers_mode": null,
847             "transform_quantity": null,
848             "type": "one_time",
849             "unit_amount": 5300,
850             "unit_amount_decimal": "5300"
851             },
852             "proration": false,
853             "proration_details": {
854             "credited_items": null
855             },
856             "quantity": 1,
857             "subscription": null,
858             "tax_amounts": [],
859             "tax_rates": [],
860             "type": "invoiceitem",
861             "unit_amount_excluding_tax": "5300"
862             }
863             ],
864             "has_more": false,
865             "url": "/v1/invoices/in_fake1234567890/lines"
866             },
867             "livemode": false,
868             "metadata": {},
869             "next_payment_attempt": 1657664041,
870             "number": null,
871             "on_behalf_of": null,
872             "paid": false,
873             "paid_out_of_band": false,
874             "payment_intent": null,
875             "payment_settings": {
876             "payment_method_options": null,
877             "payment_method_types": null
878             },
879             "period_end": 1657660440,
880             "period_start": 1657660440,
881             "post_payment_credit_notes_amount": 0,
882             "pre_payment_credit_notes_amount": 0,
883             "quote": null,
884             "receipt_number": null,
885             "rendering_options": null,
886             "starting_balance": 0,
887             "statement_descriptor": null,
888             "status": "draft",
889             "status_transitions": {
890             "finalized_at": null,
891             "marked_uncollectible_at": null,
892             "paid_at": null,
893             "voided_at": null
894             },
895             "subscription": null,
896             "subtotal": 5300,
897             "subtotal_excluding_tax": 5300,
898             "tax": null,
899             "test_clock": null,
900             "total": 5300,
901             "total_discount_amounts": [],
902             "total_excluding_tax": 5300,
903             "total_tax_amounts": [],
904             "transfer_data": null,
905             "webhooks_delivered_at": null
906             }
907              
908             =head1 HISTORY
909              
910             =head2 v0.1
911              
912             Initial version
913              
914             =head1 STRIPE HISTORY
915              
916             =head2 2019-12-03
917              
918             Customer balances applied to all invoices are now debited or credited back to the customer when voided. Earlier, applied customer balances were not returned back to the customer and were consumed.
919              
920             =over 4
921              
922             =item * To achieve this behavior in earlier API versions:
923              
924             =over 8
925              
926             =item * Set consume_applied_balance to false when voiding invoices in /v1/invoices/:id/void.
927              
928             =item * Set invoice_customer_balance_settings[consume_applied_balance_on_void] to false in /v1/subscriptions create or update to force this behavior for Invoices voided by a Subscription.
929              
930             =item * Set subscription_data[invoice_customer_balance_settings][consume_applied_balance_on_void] to false in /v1/checkout/sessions create to force this behavior for Invoices voided by Subscriptions created with Checkout.
931              
932             =back
933              
934             =back
935              
936             =head2 2019-03-14
937              
938             There are a few changes to the invoice object:
939              
940             =over 4
941              
942             =item * A I<status_transitions> hash now contains the timestamps when an invoice was finalized, paid, marked uncollectible, or voided.
943              
944             =item * The I<date> property has been renamed to created.
945              
946             =item * The I<finalized_at> property has been moved into the I<status_transitions> hash.
947              
948             =back
949              
950             =head2 2018-11-08
951              
952             The I<closed> property on the invoice object controls automatic collection. I<closed> has been deprecated in favor of the more specific I<auto_advance> field. Where you might have set I<closed=true> on invoices in the past, set I<auto_advance=false>.
953              
954             =head2 2018-11-08
955              
956             Instead of checking the I<forgiven> field on an invoice, check for the I<uncollectible> status.
957              
958             Instead of setting the I<forgiven> field on an invoice, mark it as uncollectible.
959              
960             =head2 2022-08-27
961              
962             Stripe has removed L</tax_percent> from objects and requests in favor of L<tax rates|https://stripe.com/docs/api/tax_rates>.
963              
964             =head2 2022-07-12
965              
966             The following methods were added by Stripe:
967              
968             =over 4
969              
970             =item * L</application>
971              
972             =item * L</automatic_tax>
973              
974             =item * L</on_behalf_of>
975              
976             =item * L</paid_out_of_band>
977              
978             =item * L</payment_settings>
979              
980             =item * L</quote>
981              
982             =item * L</rendering_options>
983              
984             =item * L</subtotal_excluding_tax>
985              
986             =item * L</test_clock>
987              
988             =item * L</total_excluding_tax>
989              
990             =back
991              
992             =head1 AUTHOR
993              
994             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
995              
996             =head1 SEE ALSO
997              
998             Stripe API documentation:
999              
1000             L<https://stripe.com/docs/api/invoices>, L<https://stripe.com/docs/billing/invoices/sending>
1001              
1002             =head1 COPYRIGHT & LICENSE
1003              
1004             Copyright (c) 2019-2020 DEGUEST Pte. Ltd.
1005              
1006             You can use, copy, modify and redistribute this package and associated
1007             files under the same terms as Perl itself.
1008              
1009             =cut