feat(purchase_order_number): Subscriptions invoices splitting

Author: D1353L

app/services/invoices/subscription_service.rb

@@ -29,6 +29,10 @@ def call
         return result.validation_failure!(errors: {billing_entity: ["mixed_billing_entities"]})
       end
 
+      if mixed_purchase_order_numbers?
+        return result.validation_failure!(errors: {purchase_order_number: ["mixed_purchase_order_numbers"]})
+      end
+
       create_generating_invoice unless invoice
       invoice.status = :open if subscription_gated?
       result.invoice = invoice
@@ -180,6 +184,12 @@ def mixed_billing_entities?
       subscriptions.map(&:applicable_billing_entity_id).uniq.many?
     end
 
+    # NOTE: Backstop for the PO grouping done upstream (periodic consolidation and
+    #       upgrade/downgrade rotation). A single invoice must never mix PO numbers.
+    def mixed_purchase_order_numbers?
+      subscriptions.map(&:purchase_order_number).uniq.many?
+    end
+
     def set_invoice_generated_status
       return invoice.status = :draft if grace_period?
 

app/services/subscriptions/activate_service.rb

@@ -143,8 +143,14 @@ def activate_standalone
 
     def bill_rotation_subscriptions(billable_subscriptions, billing_at:, non_invoiceable_subscriptions: [subscription.previous_subscription])
       after_commit do
-        BillSubscriptionJob.perform_later(billable_subscriptions, billing_at.to_i, invoicing_reason: :upgrading)
-        BillNonInvoiceableFeesJob.perform_later(non_invoiceable_subscriptions, billing_at)
+        # NOTE: On upgrade/downgrade the previous and new subscriptions may carry different
+        #       purchase order numbers. Split them so each PO produces its own invoice.
+        billable_subscriptions.group_by(&:purchase_order_number).each_value do |subscriptions|
+          BillSubscriptionJob.perform_later(subscriptions, billing_at.to_i, invoicing_reason: :upgrading)
+        end
+        non_invoiceable_subscriptions.group_by(&:purchase_order_number).each_value do |subscriptions|
+          BillNonInvoiceableFeesJob.perform_later(subscriptions, billing_at)
+        end
       end
     end
 

app/services/subscriptions/organization_billing_service.rb

@@ -29,6 +29,7 @@ def call
         subscription_groups = group_by_payment_method(billing_subscriptions)
         subscription_groups = group_by_currency(subscription_groups)
         subscription_groups = group_by_billing_entity(subscription_groups)
+        subscription_groups = group_by_purchase_order_number(subscription_groups)
         subscription_groups = split_consolidation_opted_out(subscription_groups)
 
         subscription_groups.each do |subscriptions|
@@ -552,6 +553,15 @@ def group_by_billing_entity(subscription_groups)
       end
     end
 
+    # NOTE: A purchase order number ties an invoice to a specific buyer authorization.
+    #       Subscriptions carrying different PO numbers must never be consolidated onto
+    #       the same invoice, so they are always split regardless of feature flags.
+    def group_by_purchase_order_number(subscription_groups)
+      subscription_groups.flat_map do |subscriptions|
+        subscriptions.group_by(&:purchase_order_number).values
+      end
+    end
+
     # NOTE: Returns array of subscription groups
     #       - Groups subscriptions by their EFFECTIVE payment method (resolved, not raw)
     #       - If payment_method_id is nil, resolves to customer's default payment method

spec/services/invoices/subscription_service_spec.rb

@@ -185,6 +185,40 @@
       end
     end
 
+    context "when batched subscriptions carry different purchase order numbers" do
+      let(:other_subscription) do
+        create(
+          :subscription,
+          plan:,
+          customer:,
+          subscription_at: started_at.to_date,
+          started_at:,
+          created_at: started_at,
+          purchase_order_number: "PO-2"
+        )
+      end
+      let(:subscription) do
+        create(
+          :subscription,
+          plan:,
+          customer:,
+          subscription_at: started_at.to_date,
+          started_at:,
+          created_at: started_at,
+          purchase_order_number: "PO-1"
+        )
+      end
+      let(:subscriptions) { [subscription, other_subscription] }
+
+      it "returns a validation failure rather than producing a mixed-PO invoice" do
+        result = invoice_service.call
+
+        expect(result).not_to be_success
+        expect(result.error).to be_a(BaseService::ValidationFailure)
+        expect(result.error.messages[:purchase_order_number]).to eq(["mixed_purchase_order_numbers"])
+      end
+    end
+
     it_behaves_like "syncs invoice" do
       let(:service_call) { invoice_service.call }
     end

spec/services/subscriptions/activate_service_spec.rb

@@ -684,6 +684,29 @@
         expect(BillNonInvoiceableFeesJob).to have_been_enqueued
           .with([previous_subscription, subscription], anything)
       end
+
+      context "when the previous and new subscriptions carry different purchase order numbers" do
+        before do
+          previous_subscription.update!(purchase_order_number: "PO-1")
+          subscription.update!(purchase_order_number: "PO-2")
+        end
+
+        it "splits the upgrade bill into one job per purchase order number" do
+          result
+
+          expect(BillSubscriptionJob).to have_been_enqueued
+            .with([previous_subscription], anything, invoicing_reason: :upgrading)
+          expect(BillSubscriptionJob).to have_been_enqueued
+            .with([subscription], anything, invoicing_reason: :upgrading)
+        end
+
+        it "splits BillNonInvoiceableFeesJob per purchase order number" do
+          result
+
+          expect(BillNonInvoiceableFeesJob).to have_been_enqueued.with([previous_subscription], anything)
+          expect(BillNonInvoiceableFeesJob).to have_been_enqueued.with([subscription], anything)
+        end
+      end
     end
 
     context "when activation_rules gate the new subscription" do

spec/services/subscriptions/organization_billing_service_spec.rb

@@ -442,6 +442,98 @@ def expect_to_bill_together(subscriptions, date)
       end
     end
 
+    context "when grouping subscriptions by purchase order number" do
+      let(:interval) { :monthly }
+      let(:billing_time) { :anniversary }
+      let(:current_date) { subscription_at.next_month }
+
+      before { subscription.destroy }
+
+      context "when subscriptions have different purchase order numbers" do
+        let(:po1_subscription) do
+          create(
+            :subscription,
+            customer:,
+            plan:,
+            subscription_at:,
+            started_at: current_date - 10.days,
+            billing_time:,
+            created_at:,
+            purchase_order_number: "PO-1"
+          )
+        end
+        let(:po2_subscription) do
+          create(
+            :subscription,
+            customer:,
+            plan:,
+            subscription_at:,
+            started_at: current_date - 10.days,
+            billing_time:,
+            created_at:,
+            purchase_order_number: "PO-2"
+          )
+        end
+
+        before do
+          po1_subscription
+          po2_subscription
+        end
+
+        it "produces separate billing jobs per purchase order number" do
+          billing_service.call
+
+          expect(BillSubscriptionJob).to have_been_enqueued
+            .with([po1_subscription], current_date.to_i, invoicing_reason: :subscription_periodic)
+          expect(BillSubscriptionJob).to have_been_enqueued
+            .with([po2_subscription], current_date.to_i, invoicing_reason: :subscription_periodic)
+        end
+      end
+
+      context "when subscriptions share the same purchase order number" do
+        let(:subscription1) do
+          create(
+            :subscription,
+            customer:,
+            plan:,
+            subscription_at:,
+            started_at: current_date - 10.days,
+            billing_time:,
+            created_at:,
+            purchase_order_number: "PO-1"
+          )
+        end
+        let(:subscription2) do
+          create(
+            :subscription,
+            customer:,
+            plan:,
+            subscription_at:,
+            started_at: current_date - 10.days,
+            billing_time:,
+            created_at:,
+            purchase_order_number: "PO-1"
+          )
+        end
+
+        before do
+          subscription1
+          subscription2
+        end
+
+        it "groups them into a single billing job" do
+          billing_service.call
+
+          expect(BillSubscriptionJob).to have_been_enqueued
+            .with(
+              contain_exactly(subscription1, subscription2),
+              current_date.to_i,
+              invoicing_reason: :subscription_periodic
+            )
+        end
+      end
+    end
+
     context "when grouping subscriptions by currency" do
       let(:organization) { create(:organization, feature_flags: ["multi_currency"]) }
       let(:interval) { :monthly }