feat(issuing-date-5) Finalize invoices based on expected_finalization_date (#4667)

vankiru · web-flow · commit 0a00f8cefb78 · 2025-12-03T21:24:02.000+04:00
## Roadmap Task 👉 [Spec](https://www.notion.so/getlago/Spec-Define-the-issuing-date-preferences-of-subscription-invoices-2a0ef63110d2807d860cc22ced334bfb) 👉 [Dive In](https://www.notion.so/getlago/BE-Dive-In-Define-the-issuing-date-preferences-of-subscription-invoices-2a3ef63110d2800e8620fb5687f0edf9?d=2a3ef63110d2808f96fd001cbc71298b#2a3ef63110d2807abf14f498b984ac57) ## Context This PR is part of the Invoice Issuing Date preferences updates. With the new issuing date adjustment setting, `issuing_date` might skip using `invoice_grace_period` (when the adjustment set to "keep_anchor"). But we still need to factor in `invoice_grace_period` when finalizing invoices. ## Description This PR adds a new field, `expected_finalization_date`, which stores the date when a draft invoice should be auto-finalized. It's basically: ``` expected_finalization_date = invoice creation date + invoice_grace_period.days ``` The `expected_finalization_date` field is mostly for internal use. We only expose it in GraphQL so we can show the right message about when a draft invoice will be finalized. It's not available in the REST API or in the SDK clients.
diff --git a/app/graphql/types/invoices/object.rb b/app/graphql/types/invoices/object.rb
@@ -41,6 +41,7 @@ class Object < Types::BaseObject
       field :total_due_amount_cents, GraphQL::Types::BigInt, null: false
       field :total_paid_amount_cents, GraphQL::Types::BigInt, null: false
 
+      field :expected_finalization_date, GraphQL::Types::ISO8601Date, null: false
       field :issuing_date, GraphQL::Types::ISO8601Date, null: false
       field :payment_due_date, GraphQL::Types::ISO8601Date, null: false
       field :payment_overdue, Boolean, null: false
diff --git a/app/models/invoice.rb b/app/models/invoice.rb
@@ -121,7 +121,7 @@ class Invoice < ApplicationRecord
   scope :invisible, -> { where(status: INVISIBLE_STATUS.keys) }
   scope :with_generated_number, -> { where(status: %w[finalized voided]) }
   scope :ready_to_be_refreshed, -> { draft.where(ready_to_be_refreshed: true) }
-  scope :ready_to_be_finalized, -> { draft.where("issuing_date <= ?", Time.current.to_date) }
+  scope :ready_to_be_finalized, -> { draft.where("COALESCE(expected_finalization_date, issuing_date) <= ?", Time.current.to_date) }
 
   scope :created_before,
     lambda { |invoice|
@@ -440,6 +440,12 @@ def allow_manual_payment?
     MANUALLY_PAYABLE_INVOICE_STATUS.include?(status.to_sym)
   end
 
+  # A safeguard while we're populating the expected finalization date.
+  # We can drop it once fill_expected_finalization_date has been run.
+  def expected_finalization_date
+    read_attribute(:expected_finalization_date) || issuing_date
+  end
+
   private
 
   # Checks that every charge has at least one fee without a filter (charge_filter_id IS NULL)
@@ -594,6 +600,7 @@ def set_finalized_at
 #  coupons_amount_cents                    :bigint           default(0), not null
 #  credit_notes_amount_cents               :bigint           default(0), not null
 #  currency                                :string
+#  expected_finalization_date              :date
 #  fees_amount_cents                       :bigint           default(0), not null
 #  file                                    :string
 #  finalized_at                            :datetime
diff --git a/app/services/customers/update_invoice_issuing_date_settings_service.rb b/app/services/customers/update_invoice_issuing_date_settings_service.rb
@@ -21,6 +21,7 @@ def call
           # NOTE: Update issuing_date on draft invoices.
           customer.invoices.draft.find_each do |invoice|
             invoice.issuing_date = invoice.issuing_date + issuing_date_adjustment(invoice)
+            invoice.expected_finalization_date = invoice.expected_finalization_date + grace_period_adjustment(invoice)
             invoice.payment_due_date = grace_period_payment_due_date(invoice)
             invoice.save!
           end
@@ -60,21 +61,37 @@ def set_issuing_date_settings
     end
 
     def issuing_date_adjustment(invoice)
-      recurring = invoice.invoice_subscriptions.first&.recurring?
+      new_issuing_date_adjustment = new_issuing_date_service(invoice).issuing_date_adjustment
+      old_issuing_date_adjustment = old_issuing_date_service(invoice).issuing_date_adjustment
 
-      old_issuing_date_adjustment = Invoices::IssuingDateService.new(
+      new_issuing_date_adjustment - old_issuing_date_adjustment
+    end
+
+    def grace_period_adjustment(invoice)
+      new_grace_period = new_issuing_date_service(invoice).grace_period
+      old_grace_period = old_issuing_date_service(invoice).grace_period
+
+      new_grace_period - old_grace_period
+    end
+
+    def old_issuing_date_service(invoice)
+      Invoices::IssuingDateService.new(
         customer_settings: previous_issuing_date_settings,
         billing_entity_settings: customer.billing_entity,
-        recurring:
-      ).issuing_date_adjustment
+        recurring: recurring(invoice)
+      )
+    end
 
-      new_issuing_date_adjustment = Invoices::IssuingDateService.new(
+    def new_issuing_date_service(invoice)
+      Invoices::IssuingDateService.new(
         customer_settings: customer,
         billing_entity_settings: customer.billing_entity,
-        recurring:
-      ).issuing_date_adjustment
+        recurring: recurring(invoice)
+      )
+    end
 
-      new_issuing_date_adjustment - old_issuing_date_adjustment
+    def recurring(invoice)
+      invoice.invoice_subscriptions.first&.recurring?
     end
 
     def grace_period_payment_due_date(invoice)
diff --git a/app/services/invoices/create_generating_service.rb b/app/services/invoices/create_generating_service.rb
@@ -29,6 +29,7 @@ def call
           timezone: customer.applicable_timezone,
           status: :generating,
           issuing_date:,
+          expected_finalization_date:,
           payment_due_date:,
           net_payment_term: customer.applicable_net_payment_term,
           skip_charges:,
@@ -57,6 +58,13 @@ def issuing_date
       date + issuing_date_service.issuing_date_adjustment.days
     end
 
+    def expected_finalization_date
+      date = datetime.in_time_zone(customer.applicable_timezone).to_date
+      return date if !grace_period? || charge_in_advance
+
+      date + customer.applicable_invoice_grace_period.days
+    end
+
     def grace_period?
       return false unless invoice_type.to_sym == :subscription
 
diff --git a/app/services/invoices/issuing_date_service.rb b/app/services/invoices/issuing_date_service.rb
@@ -14,6 +14,10 @@ def issuing_date_adjustment
       send("#{anchor}_#{adjustment}")
     end
 
+    def grace_period
+      customer_settings[:invoice_grace_period] || billing_entity_settings[:invoice_grace_period] || 0
+    end
+
     private
 
     attr_reader :customer_settings, :billing_entity_settings, :recurring
@@ -35,10 +39,6 @@ def next_period_start_align_with_finalization_date
       grace_period
     end
 
-    def grace_period
-      customer_settings[:invoice_grace_period] || billing_entity_settings[:invoice_grace_period] || 0
-    end
-
     def anchor
       customer_settings[:subscription_invoice_issuing_date_anchor] || billing_entity_settings[:subscription_invoice_issuing_date_anchor]
     end
diff --git a/app/services/invoices/subscription_service.rb b/app/services/invoices/subscription_service.rb
@@ -134,12 +134,7 @@ def create_generating_invoice
     end
 
     def grace_period?
-      align_with_finalization_date =
-        customer.applicable_subscription_invoice_issuing_date_adjustment == "align_with_finalization_date"
-
-      grace_period = customer.applicable_invoice_grace_period.positive?
-
-      @grace_period ||= (!recurring || align_with_finalization_date) && grace_period
+      @grace_period ||= customer.applicable_invoice_grace_period.positive?
     end
 
     def set_invoice_generated_status
diff --git a/app/services/invoices/update_issuing_date_from_billing_entity_service.rb b/app/services/invoices/update_issuing_date_from_billing_entity_service.rb
@@ -15,6 +15,7 @@ def call
       return result unless invoice.draft?
 
       invoice.issuing_date = invoice.issuing_date + issuing_date_adjustment.days
+      invoice.expected_finalization_date = invoice.expected_finalization_date + grace_period_adjustment
       invoice.applied_grace_period = invoice.customer.applicable_invoice_grace_period
       invoice.payment_due_date = invoice.issuing_date + invoice.customer.applicable_net_payment_term.days
       invoice.save!
@@ -27,21 +28,37 @@ def call
     attr_reader :invoice, :previous_issuing_date_settings
 
     def issuing_date_adjustment
-      recurring = invoice.invoice_subscriptions.first&.recurring?
+      new_issuing_date_adjustment = new_issuing_date_service.issuing_date_adjustment
+      old_issuing_date_adjustment = old_issuing_date_service.issuing_date_adjustment
 
-      old_issuing_date_adjustment = Invoices::IssuingDateService.new(
+      new_issuing_date_adjustment - old_issuing_date_adjustment
+    end
+
+    def grace_period_adjustment
+      new_grace_period = new_issuing_date_service.grace_period
+      old_grace_period = old_issuing_date_service.grace_period
+
+      new_grace_period - old_grace_period
+    end
+
+    def old_issuing_date_service
+      Invoices::IssuingDateService.new(
         customer_settings: invoice.customer,
         billing_entity_settings: previous_issuing_date_settings,
         recurring:
-      ).issuing_date_adjustment
+      )
+    end
 
-      new_issuing_date_adjustment = Invoices::IssuingDateService.new(
+    def new_issuing_date_service
+      Invoices::IssuingDateService.new(
         customer_settings: invoice.customer,
         billing_entity_settings: invoice.billing_entity,
         recurring:
-      ).issuing_date_adjustment
+      )
+    end
 
-      new_issuing_date_adjustment - old_issuing_date_adjustment
+    def recurring
+      invoice.invoice_subscriptions.first&.recurring?
     end
   end
 end
diff --git a/db/migrate/20251201084648_add_expected_finalization_date_to_invoices.rb b/db/migrate/20251201084648_add_expected_finalization_date_to_invoices.rb
@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddExpectedFinalizationDateToInvoices < ActiveRecord::Migration[8.0]
+  def change
+    add_column :invoices, :expected_finalization_date, :date
+  end
+end
diff --git a/db/structure.sql b/db/structure.sql
@@ -3009,6 +3009,7 @@ CREATE TABLE public.invoices (
     finalized_at timestamp without time zone,
     voided_invoice_id uuid,
     xml_file character varying,
+    expected_finalization_date date,
     CONSTRAINT check_organizations_on_net_payment_term CHECK ((net_payment_term >= 0))
 );
 
@@ -10223,6 +10224,7 @@ ALTER TABLE ONLY public.fixed_charges_taxes
 SET search_path TO "$user", public;
 
 INSERT INTO "schema_migrations" (version) VALUES
+('20251201084648'),
 ('20251126135708'),
 ('20251126134516'),
 ('20251125174110'),
diff --git a/lib/tasks/invoices.rake b/lib/tasks/invoices.rake
@@ -38,4 +38,9 @@ namespace :invoices do
       )
     end
   end
+
+  desc "Fill expected_finalization_date"
+  task fill_expected_finalization_date: :environment do
+    Invoice.in_batches.update_all("expected_finalization_date = COALESCE(expected_finalization_date, issuing_date)") # rubocop:disable Rails/SkipsModelValidations
+  end
 end
diff --git a/schema.graphql b/schema.graphql
diff --git a/schema.json b/schema.json
diff --git a/spec/factories/invoices.rb b/spec/factories/invoices.rb
@@ -7,6 +7,7 @@
     organization { customer&.organization || association(:organization) }
 
     issuing_date { Time.zone.now - 1.day }
+    expected_finalization_date { Time.zone.now - 1.day }
     payment_due_date { issuing_date }
     payment_status { "pending" }
     currency { "EUR" }
diff --git a/spec/graphql/types/invoices/object_spec.rb b/spec/graphql/types/invoices/object_spec.rb
@@ -40,6 +40,7 @@
     expect(subject).to have_field(:total_paid_amount_cents).of_type("BigInt!")
 
     expect(subject).to have_field(:issuing_date).of_type("ISO8601Date!")
+    expect(subject).to have_field(:expected_finalization_date).of_type("ISO8601Date!")
     expect(subject).to have_field(:payment_due_date).of_type("ISO8601Date!")
     expect(subject).to have_field(:payment_overdue).of_type("Boolean!")
     expect(subject).to have_field(:ready_for_payment_processing).of_type("Boolean!")
diff --git a/spec/jobs/clock/finalize_invoices_job_spec.rb b/spec/jobs/clock/finalize_invoices_job_spec.rb
@@ -12,6 +12,7 @@
         :invoice,
         status: :draft,
         issuing_date: DateTime.parse("23 Jun 2022").to_date,
+        expected_finalization_date: DateTime.parse("23 Jun 2022").to_date,
         customer:,
         organization: customer.organization
       )
@@ -21,6 +22,7 @@
         :invoice,
         status: :finalized,
         issuing_date: DateTime.parse("23 Jun 2022").to_date,
+        expected_finalization_date: DateTime.parse("23 Jun 2022").to_date,
         customer:,
         organization: customer.organization
       )
diff --git a/spec/models/invoice_spec.rb b/spec/models/invoice_spec.rb
@@ -209,21 +209,29 @@
   end
 
   describe "ready_to_be_finalized" do
-    let(:invoice) { create(:invoice, status: :draft, issuing_date: Time.current - 1.day) }
+    let(:invoice) { create(:invoice, status: :draft, expected_finalization_date: Time.current - 1.day) }
 
     before { invoice }
 
     it "returns all invoices that are ready for finalization" do
       expect(described_class.ready_to_be_finalized.pluck(:id)).to include(invoice.id)
     end
 
-    context "when issuing date has not been reached" do
-      let(:invoice) { create(:invoice, status: :draft, issuing_date: Time.current + 1.day) }
+    context "when expected_finalization_date has not been reached" do
+      let(:invoice) { create(:invoice, status: :draft, expected_finalization_date: Time.current + 1.day) }
 
       it "returns all invoices that are ready for finalization" do
         expect(described_class.ready_to_be_finalized.pluck(:id)).not_to include(invoice.id)
       end
     end
+
+    context "when expected_finalization_date is nil" do
+      let(:invoice) { create(:invoice, status: :draft, issuing_date: Time.current + 1.day) }
+
+      it "returns all invoices that are ready for finalization" do
+        expect(described_class.ready_to_be_finalized.pluck(:id)).to include(invoice.id)
+      end
+    end
   end
 
   describe "ready_to_be_refreshed" do
@@ -238,7 +246,7 @@
     before { invoices }
 
     it "returns only the invoices that are ready for refresh" do
-      expect(described_class.ready_to_be_finalized.pluck(:id)).to include(invoices[0].id)
+      expect(described_class.ready_to_be_refreshed.pluck(:id)).to include(invoices[0].id)
     end
   end
 
@@ -2114,4 +2122,26 @@
       it { expect(subject).to be false }
     end
   end
+
+  describe "#expected_finalization_date" do
+    subject { invoice.expected_finalization_date }
+
+    let(:invoice) { build(:invoice, issuing_date: Time.current, expected_finalization_date:) }
+
+    context "when expected_finalization_date is present" do
+      let(:expected_finalization_date) { Time.current.to_date + 1.day }
+
+      it "returns expected_finalization_date value" do
+        expect(subject).to eq(expected_finalization_date)
+      end
+    end
+
+    context "when expected_finalization_date is blank" do
+      let(:expected_finalization_date) { nil }
+
+      it "returns issuing_date value" do
+        expect(subject).to eq(invoice.issuing_date)
+      end
+    end
+  end
 end
diff --git a/spec/services/customers/update_invoice_issuing_date_settings_service_spec.rb b/spec/services/customers/update_invoice_issuing_date_settings_service_spec.rb
diff --git a/spec/services/invoices/create_generating_service_spec.rb b/spec/services/invoices/create_generating_service_spec.rb
diff --git a/spec/services/invoices/issuing_date_service_spec.rb b/spec/services/invoices/issuing_date_service_spec.rb
diff --git a/spec/services/invoices/subscription_service_spec.rb b/spec/services/invoices/subscription_service_spec.rb
diff --git a/spec/services/invoices/update_issuing_date_from_billing_entity_service_spec.rb b/spec/services/invoices/update_issuing_date_from_billing_entity_service_spec.rb
