feat(invoices): Ability to skip 0 invoices

app/controllers/api/v1/customers_controller.rb

@@ -111,6 +111,7 @@ def create_params
           :timezone,
           :net_payment_term,
           :external_salesforce_id,
+          :finalize_zero_amount_invoice,
           integration_customers: [
             :id,
             :external_customer_id,

app/controllers/api/v1/organizations_controller.rb

@@ -65,6 +65,7 @@ def input_params
           :webhook_url,
           :document_numbering,
           :document_number_prefix,
+          :finalize_zero_amount_invoice,
           email_settings: [],
           billing_configuration: [
             :invoice_footer,

app/models/customer.rb

@@ -9,6 +9,15 @@ class Customer < ApplicationRecord
   include Discard::Model
   self.discard_column = :deleted_at
 
+  FINALIZE_ZERO_AMOUNT_INVOICE_OPTIONS = [
+    :inherit,
+    :skip,
+    :finalize
+  ].freeze
+
+  attribute :finalize_zero_amount_invoice, :integer # rails 7.1 check the field exists when defining enum and when running the migration first time is not there
+  enum finalize_zero_amount_invoice: FINALIZE_ZERO_AMOUNT_INVOICE_OPTIONS, _prefix: :finalize_zero_amount_invoice
+
   before_save :ensure_slug
 
   belongs_to :organization
@@ -164,43 +173,44 @@ def ensure_slug
 #
 # Table name: customers
 #
-#  id                        :uuid             not null, primary key
-#  address_line1             :string
-#  address_line2             :string
-#  city                      :string
-#  country                   :string
-#  currency                  :string
-#  deleted_at                :datetime
-#  document_locale           :string
-#  email                     :string
-#  invoice_grace_period      :integer
-#  legal_name                :string
-#  legal_number              :string
-#  logo_url                  :string
-#  name                      :string
-#  net_payment_term          :integer
-#  payment_provider          :string
-#  payment_provider_code     :string
-#  phone                     :string
-#  shipping_address_line1    :string
-#  shipping_address_line2    :string
-#  shipping_city             :string
-#  shipping_country          :string
-#  shipping_state            :string
-#  shipping_zipcode          :string
-#  slug                      :string
-#  state                     :string
-#  tax_identification_number :string
-#  timezone                  :string
-#  url                       :string
-#  vat_rate                  :float
-#  zipcode                   :string
-#  created_at                :datetime         not null
-#  updated_at                :datetime         not null
-#  external_id               :string           not null
-#  external_salesforce_id    :string
-#  organization_id           :uuid             not null
-#  sequential_id             :bigint
+#  id                           :uuid             not null, primary key
+#  address_line1                :string
+#  address_line2                :string
+#  city                         :string
+#  country                      :string
+#  currency                     :string
+#  deleted_at                   :datetime
+#  document_locale              :string
+#  email                        :string
+#  finalize_zero_amount_invoice :integer          default(0), not null
+#  invoice_grace_period         :integer
+#  legal_name                   :string
+#  legal_number                 :string
+#  logo_url                     :string
+#  name                         :string
+#  net_payment_term             :integer
+#  payment_provider             :string
+#  payment_provider_code        :string
+#  phone                        :string
+#  shipping_address_line1       :string
+#  shipping_address_line2       :string
+#  shipping_city                :string
+#  shipping_country             :string
+#  shipping_state               :string
+#  shipping_zipcode             :string
+#  slug                         :string
+#  state                        :string
+#  tax_identification_number    :string
+#  timezone                     :string
+#  url                          :string
+#  vat_rate                     :float
+#  zipcode                      :string
+#  created_at                   :datetime         not null
+#  updated_at                   :datetime         not null
+#  external_id                  :string           not null
+#  external_salesforce_id       :string
+#  organization_id              :uuid             not null
+#  sequential_id                :bigint
 #
 # Indexes
 #

app/models/invoice.rb

@@ -63,7 +63,7 @@ class Invoice < ApplicationRecord
   PAYMENT_STATUS = %i[pending succeeded failed].freeze
 
   VISIBLE_STATUS = {draft: 0, finalized: 1, voided: 2, failed: 4}.freeze
-  INVISIBLE_STATUS = {generating: 3, open: 5}.freeze
+  INVISIBLE_STATUS = {generating: 3, open: 5, closed: 6}.freeze
   STATUS = VISIBLE_STATUS.merge(INVISIBLE_STATUS).freeze
 
   enum invoice_type: INVOICE_TYPES
@@ -77,6 +77,7 @@ class Invoice < ApplicationRecord
     state :finalized
     state :voided
     state :failed
+    state :closed
 
     event :finalize do
       transitions from: :draft, to: :finalized

app/models/organization.rb

@@ -70,6 +70,7 @@ class Organization < ApplicationRecord
   validates :name, presence: true
   validates :timezone, timezone: true
   validates :webhook_url, url: true, allow_nil: true
+  validates :finalize_zero_amount_invoice, inclusion: {in: [true, false]}
 
   validate :validate_email_settings
 
@@ -137,37 +138,38 @@ def validate_email_settings
 #
 # Table name: organizations
 #
-#  id                        :uuid             not null, primary key
-#  address_line1             :string
-#  address_line2             :string
-#  api_key                   :string
-#  city                      :string
-#  clickhouse_aggregation    :boolean          default(FALSE), not null
-#  country                   :string
-#  custom_aggregation        :boolean          default(FALSE)
-#  default_currency          :string           default("USD"), not null
-#  document_locale           :string           default("en"), not null
-#  document_number_prefix    :string
-#  document_numbering        :integer          default("per_customer"), not null
-#  email                     :string
-#  email_settings            :string           default([]), not null, is an Array
-#  eu_tax_management         :boolean          default(FALSE)
-#  invoice_footer            :text
-#  invoice_grace_period      :integer          default(0), not null
-#  legal_name                :string
-#  legal_number              :string
-#  logo                      :string
-#  name                      :string           not null
-#  net_payment_term          :integer          default(0), not null
-#  premium_integrations      :string           default([]), not null, is an Array
-#  state                     :string
-#  tax_identification_number :string
-#  timezone                  :string           default("UTC"), not null
-#  vat_rate                  :float            default(0.0), not null
-#  webhook_url               :string
-#  zipcode                   :string
-#  created_at                :datetime         not null
-#  updated_at                :datetime         not null
+#  id                           :uuid             not null, primary key
+#  address_line1                :string
+#  address_line2                :string
+#  api_key                      :string
+#  city                         :string
+#  clickhouse_aggregation       :boolean          default(FALSE), not null
+#  country                      :string
+#  custom_aggregation           :boolean          default(FALSE)
+#  default_currency             :string           default("USD"), not null
+#  document_locale              :string           default("en"), not null
+#  document_number_prefix       :string
+#  document_numbering           :integer          default("per_customer"), not null
+#  email                        :string
+#  email_settings               :string           default([]), not null, is an Array
+#  eu_tax_management            :boolean          default(FALSE)
+#  finalize_zero_amount_invoice :boolean          default(FALSE), not null
+#  invoice_footer               :text
+#  invoice_grace_period         :integer          default(0), not null
+#  legal_name                   :string
+#  legal_number                 :string
+#  logo                         :string
+#  name                         :string           not null
+#  net_payment_term             :integer          default(0), not null
+#  premium_integrations         :string           default([]), not null, is an Array
+#  state                        :string
+#  tax_identification_number    :string
+#  timezone                     :string           default("UTC"), not null
+#  vat_rate                     :float            default(0.0), not null
+#  webhook_url                  :string
+#  zipcode                      :string
+#  created_at                   :datetime         not null
+#  updated_at                   :datetime         not null
 #
 # Indexes
 #

app/serializers/v1/customer_serializer.rb

@@ -29,6 +29,7 @@ def serialize
         applicable_timezone: model.applicable_timezone,
         net_payment_term: model.net_payment_term,
         external_salesforce_id: model.external_salesforce_id,
+        finalize_zero_amount_invoice: model.finalize_zero_amount_invoice,
         billing_configuration:,
         shipping_address: model.shipping_address
       }

app/serializers/v1/organization_serializer.rb

@@ -25,6 +25,7 @@ def serialize
         document_numbering: model.document_numbering,
         document_number_prefix: model.document_number_prefix,
         tax_identification_number: model.tax_identification_number,
+        finalize_zero_amount_invoice: model.finalize_zero_amount_invoice,
         billing_configuration:
       }
 

app/services/customers/create_service.rb

@@ -16,6 +16,13 @@ def create_from_api(organization:, params:)
         )
       end
 
+      unless valid_finalize_zero_amount_invoice?(params[:finalize_zero_amount_invoice])
+        return result.single_validation_failure!(
+          field: :finalize_zero_amount_invoice,
+          error_code: 'invalid_value'
+        )
+      end
+
       unless valid_integration_customers_count?(integration_customers: params[:integration_customers])
         return result.single_validation_failure!(
           field: :integration_customers,
@@ -45,6 +52,7 @@ def create_from_api(organization:, params:)
         customer.legal_number = params[:legal_number] if params.key?(:legal_number)
         customer.net_payment_term = params[:net_payment_term] if params.key?(:net_payment_term)
         customer.external_salesforce_id = params[:external_salesforce_id] if params.key?(:external_salesforce_id)
+        customer.finalize_zero_amount_invoice = params[:finalize_zero_amount_invoice] if params.key?(:finalize_zero_amount_invoice)
         if params.key?(:tax_identification_number)
           customer.tax_identification_number = params[:tax_identification_number]
         end
@@ -144,6 +152,10 @@ def create(**args)
         tax_identification_number: args[:tax_identification_number]
       )
 
+      if args.key?(:finalize_zero_amount_invoice)
+        customer.finalize_zero_amount_invoice = args[:finalize_zero_amount_invoice]
+      end
+
       assign_premium_attributes(customer, args)
 
       ActiveRecord::Base.transaction do
@@ -187,11 +199,9 @@ def create(**args)
 
     private
 
-    def valid_email?(email)
-      return true if email.nil?
-
-      email_regexp = /\A[^@\s]+@[^@\s]+\z/
-      email_regexp.match?(email).present?
+    def valid_finalize_zero_amount_invoice?(value)
+      return true if value.nil?
+      Customer::FINALIZE_ZERO_AMOUNT_INVOICE_OPTIONS.include?(value.to_sym)
     end
 
     def valid_metadata_count?(metadata:)

app/services/invoices/advance_charges_service.rb

@@ -65,7 +65,7 @@ def create_group_invoice
         Invoices::ComputeAmountsFromFees.call(invoice:)
 
         invoice.payment_status = :succeeded
-        invoice.status = :finalized
+        Invoices::TransitionToFinalStatus.call(invoice:)
 
         invoice.save!
       end

app/services/invoices/create_one_off_service.rb

@@ -35,8 +35,8 @@ def call
 
         Invoices::ComputeAmountsFromFees.call(invoice:, provider_taxes: result.fees_taxes)
         invoice.payment_status = invoice.total_amount_cents.positive? ? :pending : :succeeded
-
-        invoice.finalized!
+        Invoices::TransitionToFinalStatus.call(invoice:)
+        invoice.save!
       end
 
       Utils::SegmentTrack.invoice_created(invoice)

app/services/invoices/create_pay_in_advance_charge_service.rb

@@ -43,7 +43,8 @@ def call
         create_applied_prepaid_credit if should_create_applied_prepaid_credit?
 
         invoice.payment_status = invoice.total_amount_cents.positive? ? :pending : :succeeded
-        invoice.finalized!
+        Invoices::TransitionToFinalStatus.call(invoice:)
+        invoice.save!
       end
 
       Utils::SegmentTrack.invoice_created(invoice)

app/services/invoices/refresh_draft_and_finalize_service.rb

@@ -22,7 +22,7 @@ def call
         refresh_result.raise_if_error!
 
         invoice.payment_due_date = payment_due_date
-        invoice.status = :finalized
+        Invoices::TransitionToFinalStatus.call(invoice:)
         invoice.save!
 
         invoice.credit_notes.each(&:finalized!)

app/services/invoices/subscription_service.rb

@@ -28,6 +28,11 @@ def call
 
       fee_result = ActiveRecord::Base.transaction do
         invoice.status = invoice_status
+        if invoice_status == :finalized
+          Invoices::TransitionToFinalStatus.call(invoice:)
+        else
+          invoice.status = :draft
+        end
 
         fee_result = Invoices::CalculateFeesService.call(
           invoice:,

app/services/invoices/transition_to_final_status.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Invoices
+  class TransitionToFinalStatus < BaseService
+    def initialize(invoice:)
+      @invoice = invoice
+      @customer = @invoice.customer
+      @organization = @customer.organization
+      super
+    end
+
+    def call
+      invoice.status = if should_finalize_invoice?
+        :finalized
+      else
+        :closed
+      end
+      result.invoice = invoice
+      result
+    end
+
+    private
+
+    attr_reader :invoice, :customer, :organization
+
+    def should_finalize_invoice?
+      return true unless invoice.fees_amount_cents.zero?
+      customer_setting = customer.finalize_zero_amount_invoice
+      if customer_setting == 'inherit'
+        organization.finalize_zero_amount_invoice
+      else
+        customer_setting == 'finalize'
+      end
+    end
+  end
+end

app/services/organizations/update_service.rb

@@ -26,6 +26,7 @@ def call
       organization.net_payment_term = params[:net_payment_term] if params.key?(:net_payment_term)
       organization.document_numbering = params[:document_numbering] if params.key?(:document_numbering)
       organization.document_number_prefix = params[:document_number_prefix] if params.key?(:document_number_prefix)
+      organization.finalize_zero_amount_invoice = params[:finalize_zero_amount_invoice] if params.key?(:finalize_zero_amount_invoice)
 
       billing = params[:billing_configuration]&.to_h || {}
       organization.invoice_footer = billing[:invoice_footer] if billing.key?(:invoice_footer)

db/migrate/20240821172352_add_finalize_zero_amount_invoice_to_organizations.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddFinalizeZeroAmountInvoiceToOrganizations < ActiveRecord::Migration[7.1]
+  def change
+    add_column :organizations, :finalize_zero_amount_invoice, :boolean, default: true, null: false
+  end
+end

db/migrate/20240821174724_add_finalize_zero_amount_invoice_to_customers.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddFinalizeZeroAmountInvoiceToCustomers < ActiveRecord::Migration[7.1]
+  def change
+    add_column :customers, :finalize_zero_amount_invoice, :integer, default: 0, null: false
+  end
+end