Module: PaymentKit::Resources::Invoices

Included in:
Client
Defined in:
lib/payment_kit/resources/invoices.rb

Overview

Invoices and floating (pending) invoice items.

Instance Method Summary collapse

Instance Method Details

#bill_pending_items(params = nil) ⇒ Object

Sweeps floating items into standalone invoices (one per currency), finalizes them and attempts collection. Always pass a stable idempotency_key or duplicate requests create duplicate invoices.



40
41
42
 
# File 'lib/payment_kit/resources/invoices.rb', line 40

def bill_pending_items(params = nil, **)
  post("/invoices/bill-pending-items", params, **)
end

#create_invoice(params = nil) ⇒ Object

POST /invoices/ — creates a one-off invoice in draft. Each entry in items takes an amount, a unit_amount with quantity, or a catalog price_id.



10
 
# File 'lib/payment_kit/resources/invoices.rb', line 10

def create_invoice(params = nil, **) = post("/invoices/", params, **)

#create_invoice_item(params = nil) ⇒ Object

POST /invoice-items/ — creates a floating (pending) item, collected at the next renewal or on demand via #bill_pending_items. The subscription must be active or trialing and belong to the same customer.



49
 
# File 'lib/payment_kit/resources/invoices.rb', line 49

def create_invoice_item(params = nil, **) = post("/invoice-items/", params, **)

#finalize_invoice(id) ⇒ Object

Moves a draft invoice to open and locks its amounts.



30
 
# File 'lib/payment_kit/resources/invoices.rb', line 30

def finalize_invoice(id, **) = post("/invoices/#{id}/finalize", {}, **)

#list_invoice_items(params = {}) ⇒ Object

GET /invoice-items/ — auto-paginated; filter with subscription_id and status: "floating" to list pending items.



56
 
# File 'lib/payment_kit/resources/invoices.rb', line 56

def list_invoice_items(params = {}) = list("/invoice-items/", params)

#list_invoices(params = {}) ⇒ Object

GET /invoices/ — auto-paginated Array of invoices.



16
 
# File 'lib/payment_kit/resources/invoices.rb', line 16

def list_invoices(params = {}) = list("/invoices/", params)

#mark_invoice_uncollectible(id) ⇒ Object

Only permitted from OPEN or PAST_DUE; other states return 422.



33
34
35
 
# File 'lib/payment_kit/resources/invoices.rb', line 33

def mark_invoice_uncollectible(id, **)
  post("/invoices/#{id}/mark-uncollectible", {}, **)
end

#pay_invoice(id, params = nil) ⇒ Object

Attempts collection on an open invoice (finalizing it first if draft). A decline raises PaymentKit::CardError and leaves the invoice payable.



24
 
# File 'lib/payment_kit/resources/invoices.rb', line 24

def pay_invoice(id, params = nil, **) = post("/invoices/#{id}/collect", params, **)

#retrieve_invoice(id, params = {}) ⇒ Object

Supports expand, e.g. retrieve_invoice("in_1", expand: "custom_fields").



13
 
# File 'lib/payment_kit/resources/invoices.rb', line 13

def retrieve_invoice(id, params = {}) = get("/invoices/#{id}", params)

#retrieve_invoice_item(id) ⇒ Object

GET /invoice-items/id



52
 
# File 'lib/payment_kit/resources/invoices.rb', line 52

def retrieve_invoice_item(id) = get("/invoice-items/#{id}")

#retrieve_invoice_pdf(id) ⇒ Object

Returns { "pdf_url" => ..., "status" => "available" | "generating" }; poll again while status is generating.



20
 
# File 'lib/payment_kit/resources/invoices.rb', line 20

def retrieve_invoice_pdf(id) = get("/invoices/#{id}/pdf")

#update_invoice_item(id, params = nil) ⇒ Object

PATCH /invoice-items/id



59
60
61
 
# File 'lib/payment_kit/resources/invoices.rb', line 59

def update_invoice_item(id, params = nil, **)
  patch("/invoice-items/#{id}", params, **)
end

#void_invoice(id) ⇒ Object

Cancels the invoice so no payment is expected.



27
 
# File 'lib/payment_kit/resources/invoices.rb', line 27

def void_invoice(id, **) = post("/invoices/#{id}/void", {}, **)