Files
redmine_qbo/lib/redmine_qbo_billing/invoice_refund_writer.rb
T
rickyandClaude Opus 5.5 c851929e02 Refunds of paid invoices: refund receipt with optional restocking fee
Completed work that's billed and paid in full can be refunded from its
invoice (Refund on the invoice, or Paid invoice on the customer's Refund
page). It makes a QuickBooks Refund Receipt: the invoice lines refunded
(all or part, by quantity or amount) with their products/services and
tax codes, the invoice discount's share, and the restocking fee as a
negative line when it's ticked: the fee rate of the parts refunded, so
labor-only work has none. Paid out of the refund check or card account,
with the check number.

Each refund records the lines it refunded, so a line can't be refunded
for more than it was billed across refunds. Optionally notes the refund
on the invoice's work orders and emails the customer. The refund page,
PDF and email show the lines, tax and fee. Migration 056 adds the
columns to qbo_refunds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 13:23:10 -05:00

349 lines
17 KiB
Ruby

#The MIT License (MIT)
#
#Copyright (c) 2026 rick barrette
#
#Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
#
#The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
#
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
module RedmineQboBilling
# Refunds of completed work: an invoice that's billed and paid in full (SOP-OPS-014 for the restocking fee).
# QuickBooks' way to refund a paid sale is a Refund Receipt, which this makes:
#
# * the invoice lines refunded (all or part of each), with their product/service and tax code, so the income
# and the sales tax come back off the books the way they went on (QuickBooks works out the tax);
# * the invoice's discount, if it had one, in proportion to what's refunded;
# * the restocking fee, when it's charged, as a negative line with the restocking fee product/service:
# its rate (plugin setting) of the parts refunded. Labor carries no fee, and work with no parts has none;
# * paid out of the refund check or card refund bank account in the settings, by company check (its number)
# or a refund on the card terminal.
#
# The invoice itself stays as it is, paid. Each refund is recorded (QboRefund, kind invoice) with the lines it
# refunded, so a line can't be refunded for more than it was billed across several refunds. Then, as asked on
# the page, the refund is noted on the invoice's work orders and the customer is emailed a summary.
module InvoiceRefundWriter
Error = RefundWriter::Error
# An invoice line that can be refunded, with what earlier refunds already took of it
Line = Struct.new(:key, :item_id, :item_name, :description, :quantity, :rate, :amount, :taxable, :parts,
:refunded_quantity, :refunded_amount, keyword_init: true) do
def remaining_amount
[amount - refunded_amount, BigDecimal('0')].max
end
def remaining_quantity
quantity && [quantity - refunded_quantity, BigDecimal('0')].max
end
def refundable?
remaining_amount.positive?
end
def label
[item_name.presence, description.presence].compact.uniq.join(' · ')
end
end
# A line being refunded: the invoice line, the quantity (nil when only an amount is refunded) and the amount
Refunding = Struct.new(:line, :quantity, :amount, keyword_init: true)
# What a refund comes to: the lines, the invoice discount's share, the fee, the tax (estimated before
# QuickBooks works it out) and the refund
Plan = Struct.new(:refunding, :lines_amount, :parts_amount, :discount_rate, :discount, :fee_rate, :fee,
:tax_rate, :tax, :refund, keyword_init: true)
module_function
def settings
RefundWriter.settings
end
# Billed and paid in full: a total, and nothing left owing
def paid_in_full?(remote)
total = BigDecimal(remote&.total.to_s.presence || '0')
balance = BigDecimal(remote&.balance.to_s.presence || '0')
total.positive? && balance <= 0
end
# The customer's paid invoices to pick from on the Refund page, newest first: [[label, id], ...]
def invoice_choices(customer)
Invoice.where(customer_id: customer.id).where('balance <= 0 AND total_amount > 0')
.order(txn_date: :desc, id: :desc).limit(50).map do |invoice|
["##{invoice.doc_number} · #{invoice.txn_date} · #{RefundWriter.money(invoice.total_amount)}", invoice.id.to_s]
end
end
# The invoice's lines that can be refunded (bundles opened up into their lines), with what this invoice's
# earlier refunds took of each
def lines(remote, refunds: QboRefund.of_invoice(remote.id))
taken = Hash.new { |hash, key| hash[key] = [BigDecimal('0'), BigDecimal('0')] }
refunds.each do |refund|
refund.refunded_lines.each do |line|
taken[line.key][0] += BigDecimal(line.quantity.to_s.presence || '0')
taken[line.key][1] += line.amount.to_d
end
end
labor_ids = LaborItems.ids
sales_lines(Array(remote.line_items)).filter_map do |line, key|
detail = RefundWriter.sales_detail(line)
amount = BigDecimal(line.amount.to_s.presence || '0')
next unless amount.positive?
ref = detail&.item_ref
quantity = detail&.quantity.nil? ? nil : BigDecimal(detail.quantity.to_s)
quantity = nil unless quantity&.positive?
Line.new(key: key, item_id: ref&.value.to_s.presence, item_name: ref&.name.to_s, description: line.description.to_s,
quantity: quantity, rate: detail&.unit_price.nil? ? nil : BigDecimal(detail.unit_price.to_s),
amount: amount, taxable: detail&.tax_code_ref&.value.to_s == 'TAX',
parts: ref.present? && ref.value.present? && !LaborItems.match?(ref, ids: labor_ids),
refunded_quantity: taken[key][0], refunded_amount: taken[key][1])
end
end
# The sales lines with a key for each: its QuickBooks line id, or for a line in a bundle the bundle's id and
# its place in it
def sales_lines(lines, prefix = nil)
lines.each_with_index.flat_map do |line, index|
key = "#{prefix}#{line.id.presence || index + 1}"
if line.respond_to?(:group_line_detail) && line.group_line_detail
sales_lines(Array(line.group_line_detail.line_items), "#{key}.")
elsif RefundWriter.sales_detail(line)
[[line, key]]
else
[]
end
end
end
# The invoice's discount, as a share of its lines (0.1 for 10% off)
def discount_rate(remote)
discount = EstimateWriter.discount_total(remote).to_d
subtotal = sales_lines(Array(remote.line_items)).sum(BigDecimal('0')) { |line, _| BigDecimal(line.amount.to_s.presence || '0') }
return BigDecimal('0') unless discount.positive? && subtotal.positive?
[discount / subtotal, BigDecimal('1')].min
end
# The invoice's sales tax, as a share of its taxable lines after the discount, to estimate the tax refunded
def tax_rate(remote, invoice_lines = lines(remote, refunds: []))
tax = BigDecimal(remote.txn_tax_detail&.total_tax.to_s.presence || '0')
taxable = invoice_lines.select(&:taxable).sum(BigDecimal('0'), &:amount) * (1 - discount_rate(remote))
tax.positive? && taxable.positive? ? tax / taxable : BigDecimal('0')
end
# Works out the refund from the form's lines: [plan, errors]
def plan(remote, form, invoice_lines: lines(remote))
errors = []
by_key = invoice_lines.index_by(&:key)
refunding = form.chosen.filter_map do |key, choice|
line = by_key[key]
if line.nil?
errors << I18n.t(:error_refund_line_gone)
next
end
refunding_line(line, choice, errors)
end
lines_amount = refunding.sum(BigDecimal('0'), &:amount)
parts = refunding.select { |r| r.line.parts }.sum(BigDecimal('0'), &:amount)
rate = discount_rate(remote)
discount = (lines_amount * rate).round(2, BigDecimal::ROUND_HALF_UP)
fee_rate = RefundWriter.fee_rate
fee = form.charge_fee? ? RefundWriter.fee(parts, fee_rate) : BigDecimal('0')
tax_rate = tax_rate(remote, invoice_lines)
taxable = refunding.select { |r| r.line.taxable }.sum(BigDecimal('0'), &:amount) * (1 - rate)
tax = (taxable * tax_rate).round(2, BigDecimal::ROUND_HALF_UP)
refund = lines_amount - discount + tax - fee
if refunding.any? && fee >= lines_amount - discount
errors << I18n.t(:error_refund_fee_over_lines, fee: RefundWriter.money(fee), amount: RefundWriter.money(lines_amount - discount))
end
plan = Plan.new(refunding: refunding, lines_amount: lines_amount, parts_amount: parts, discount_rate: rate,
discount: discount, fee_rate: fee_rate, fee: fee, tax_rate: tax_rate, tax: tax,
refund: [refund, BigDecimal('0')].max)
[plan, errors.uniq]
end
# A line being refunded, from what was posted for it: the quantity and the amount (by default the quantity
# at the line's rate, or what's left of the line). Adds to errors when it can't be refunded.
def refunding_line(line, choice, errors)
name = line.label.presence || line.key
quantity = choice.quantity_value
quantity = nil if line.quantity.nil? || line.rate.nil?
amount = choice.amount_value
amount ||= quantity ? (quantity * line.rate).round(2) : line.remaining_amount
if quantity && (quantity <= 0 || quantity > line.remaining_quantity)
errors << I18n.t(:error_refund_line_quantity, line: name, quantity: RefundWriter.plain(line.remaining_quantity))
return nil
end
if amount.nil? || amount <= 0
errors << I18n.t(:error_refund_line_amount, line: name)
return nil
end
if amount > line.remaining_amount
errors << I18n.t(:error_refund_line_over, line: name, amount: RefundWriter.money(line.remaining_amount))
return nil
end
# A partial amount (not the quantity at the line's rate) is refunded as an amount alone, so it doesn't
# use up the line's quantity
quantity = nil if quantity && (quantity * line.rate).round(2) != amount
Refunding.new(line: line, quantity: quantity, amount: amount)
end
# The quantity to offer for a line: what's left of it, when that's what's left of its amount at its rate
def default_quantity(line)
quantity = line.remaining_quantity
return nil unless quantity&.positive? && line.rate
(quantity * line.rate).round(2) == line.remaining_amount ? quantity : nil
end
# Makes the refund receipt; returns the QboRefund (done, or incomplete with why in its message). Raises
# Error, before anything is made in QuickBooks, when the refund can't be made as asked.
def refund!(form, user: User.current, gateway: RefundGateway.new, mailer: QboRefundMailer)
customer = Customer.find_by(id: form.customer_id)
raise Error, I18n.t(:error_estimate_needs_customer) unless customer
remote = gateway.invoice(form.invoice_id)
raise Error, I18n.t(:notice_invoice_not_found) unless remote
raise Error, I18n.t(:error_refund_invoice_customer) unless remote.customer_ref&.value.to_s == customer.id.to_s
raise Error, I18n.t(:error_refund_invoice_not_paid) unless paid_in_full?(remote)
plan, errors = plan(remote, form)
raise Error, errors.join(' ') if errors.any?
raise Error, I18n.t(:error_refund_no_lines) if plan.refunding.empty?
item = RefundWriter.fee_item
raise Error, I18n.t(:error_refund_no_fee_item) if plan.fee.positive? && item.nil?
bank_account = settings[form.check? ? 'refund_check_account_id' : 'refund_card_account_id'].presence || gateway.account_id('Bank')
raise Error, I18n.t(:error_refund_no_bank_account) unless bank_account
paid = BigDecimal(remote.total.to_s) - BigDecimal(remote.balance.to_s.presence || '0')
record = QboRefund.create!(kind: 'invoice', customer_id: customer.id, invoice_id: remote.id,
invoice_number: remote.doc_number.to_s, user: user, txn_date: form.txn_date_value,
method: form.method, check_number: form.check? ? form.check_number : nil,
reason: form.reason, lines_amount: plan.lines_amount, discount_amount: plan.discount,
parts_amount: plan.parts_amount, fee_rate: plan.fee_rate, fee_amount: plan.fee,
tax_amount: plan.tax, credit_amount: paid, refund_amount: plan.refund,
refunded_lines: refunded_lines(plan), status: 'incomplete')
made = RefundWriter.step(record, :receipt) do
receipt = build_receipt(record, remote, plan, form, item, bank_account, gateway)
saved = gateway.create_refund_receipt(receipt)
raise Error, I18n.t(:error_refund_not_saved) unless saved&.id
tax = saved.txn_tax_detail&.total_tax
record.update!(purchase_id: saved.id.to_s, receipt_number: saved.doc_number.to_s,
refund_amount: saved.total.nil? ? plan.refund : BigDecimal(saved.total.to_s),
tax_amount: tax.nil? ? plan.tax : BigDecimal(tax.to_s))
end
return record unless made
warnings = []
warnings << note_issues(record, user) if form.note_issues?
warnings << RefundWriter.email_customer(record, customer, mailer) if form.email_customer?
record.update!(status: 'done', message: warnings.compact.join("\n").presence)
record
end
def refunded_lines(plan)
plan.refunding.map do |r|
QboRefund::RefundedLine.new(key: r.line.key, description: r.line.label, quantity: r.quantity,
amount: r.amount, parts: r.line.parts)
end
end
# The QuickBooks Refund Receipt: the lines refunded, the discount's share, the restocking fee
def build_receipt(record, remote, plan, form, fee_item, bank_account, gateway)
receipt = Quickbooks::Model::RefundReceipt.new
receipt.customer_ref = Quickbooks::Model::BaseReference.new(record.customer_id.to_s)
receipt.txn_date = record.txn_date
receipt.deposit_to_account_ref = Quickbooks::Model::BaseReference.new(bank_account.to_s)
method_id = gateway.payment_method_id(form.check? ? :check : :card)
receipt.payment_method_ref = Quickbooks::Model::BaseReference.new(method_id) if method_id
receipt.payment_ref_number = record.check_number if form.check?
receipt.bill_email = remote.bill_email if remote.bill_email&.address.present?
receipt.customer_memo = I18n.t(:text_refund_receipt_memo, number: record.invoice_number)
receipt.private_note = I18n.t(:text_refund_invoice_private_note, number: record.invoice_number, reason: record.reason)
receipt.apply_tax_after_discount = true if plan.discount.positive?
lines = plan.refunding.map { |r| receipt_line(r) }
lines << discount_line(plan) if plan.discount.positive?
lines << fee_line(record, fee_item) if plan.fee.positive?
lines.each_with_index { |line, index| line.line_num = index + 1 }
receipt.line_items = lines
receipt
end
# A refunded line: the invoice line's product/service and tax code. Its quantity and rate go with it when
# the amount is that quantity at the line's rate (refunding_line); a partial amount goes as an amount alone.
def receipt_line(refunding)
line = refunding.line
remote = Quickbooks::Model::Line.new
remote.description = line.description
remote.amount = refunding.amount
remote.sales_item! do |detail|
detail.item_ref = Quickbooks::Model::BaseReference.new(line.item_id) if line.item_id
if refunding.quantity
detail.quantity = refunding.quantity
detail.unit_price = line.rate
end
detail.tax_code_ref = Quickbooks::Model::BaseReference.new(line.taxable ? 'TAX' : 'NON')
end
remote
end
def discount_line(plan)
remote = Quickbooks::Model::Line.new
remote.amount = plan.discount
remote.discount! { |detail| detail.percent_based = false }
remote
end
# The restocking fee, kept back: a negative line, so the fee is income and the refund is less by it
def fee_line(record, item)
remote = Quickbooks::Model::Line.new
remote.amount = -record.fee_amount
remote.description = RefundWriter.fee_description(record.parts_amount, record.fee_rate, record.fee_amount,
nil, on: record.document_label)
remote.sales_item! do |detail|
detail.item_id = item.id
detail.quantity = 1
detail.unit_price = -record.fee_amount
detail.tax_code_ref = Quickbooks::Model::BaseReference.new('NON')
end
remote
end
# Notes the refund on the invoice's work orders (their status is left alone); returns a warning, or nil
def note_issues(record, user)
issues = Invoice.find_by(id: record.invoice_id)&.issues.to_a
return nil if issues.empty?
note = I18n.t(:text_refund_invoice_issue_note, amount: RefundWriter.money(record.refund_amount),
number: record.invoice_number, method: record.method_name,
reason: record.reason)
failed = []
noted = issues.filter_map do |issue|
issue.init_journal(user, note)
if issue.save
issue.id
else
failed << "##{issue.id} (#{issue.errors.full_messages.join(', ')})"
nil
end
end
record.update!(noted_issue_ids: noted)
failed.any? ? I18n.t(:text_refund_issues_not_noted, issues: failed.join('; ')) : nil
end
end
end