mirror of
https://github.com/rickbarrette/redmine_qbo.git
synced 2026-11-19 10:40:36 -05:00
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>
349 lines
17 KiB
Ruby
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
|