feat(order-forms): add order_form resource

lib/lago/api/client.rb

@@ -32,6 +32,8 @@
 require 'lago/api/resources/invoice_collection'
 require 'lago/api/resources/invoiced_usage'
 require 'lago/api/resources/mrr'
+require 'lago/api/resources/order_form'
+require 'lago/api/resources/order'
 require 'lago/api/resources/organization'
 require 'lago/api/resources/overdue_balance'
 require 'lago/api/resources/payment'
@@ -187,6 +189,14 @@ def mrrs
         Resources::Mrr.new(self)
       end
 
+      def order_forms
+        Resources::OrderForm.new(self)
+      end
+
+      def orders
+        Resources::Order.new(self)
+      end
+
       def organizations
         Resources::Organization.new(self)
       end

lib/lago/api/resources/order.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'lago/api/resources/base'
+
+module Lago
+  module Api
+    module Resources
+      class Order < Base
+        undef_method :create, :update, :destroy
+
+        def api_resource
+          'orders'
+        end
+
+        def root_name
+          'order'
+        end
+
+        def execute(order_id, params = {})
+          path = "/api/v1/orders/#{order_id}/execute"
+          payload = whitelist_params(params)
+          response = connection.post(payload, path)[root_name]
+
+          JSON.parse(response.to_json, object_class: OpenStruct)
+        end
+
+        def whitelist_params(params)
+          result = {
+            execution_mode: params[:execution_mode],
+          }.compact
+
+          return {} if result.empty?
+
+          { root_name => result }
+        end
+      end
+    end
+  end
+end

lib/lago/api/resources/order_form.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'lago/api/resources/base'
+
+module Lago
+  module Api
+    module Resources
+      class OrderForm < Base
+        undef_method :create, :update, :destroy
+
+        def api_resource
+          'order_forms'
+        end
+
+        def root_name
+          'order_form'
+        end
+
+        def mark_as_signed(order_form_id, params = {})
+          path = "/api/v1/order_forms/#{order_form_id}/mark_as_signed"
+          payload = whitelist_params(params)
+          response = connection.post(payload, path)[root_name]
+
+          JSON.parse(response.to_json, object_class: OpenStruct)
+        end
+
+        def void(order_form_id)
+          path = "/api/v1/order_forms/#{order_form_id}/void"
+          response = connection.post({}, path)[root_name]
+
+          JSON.parse(response.to_json, object_class: OpenStruct)
+        end
+
+        def whitelist_params(params)
+          result = {
+            signed_document: params[:signed_document],
+            execution_mode: params[:execution_mode],
+            execute_at: params[:execute_at],
+          }.compact
+
+          return {} if result.empty?
+
+          { root_name => result }
+        end
+      end
+    end
+  end
+end

spec/fixtures/api/executed_order.json

@@ -0,0 +1,36 @@
+{
+  "order": {
+    "lago_id": "cc33cc33-cc33-cc33-cc33-cc33cc33cc33",
+    "number": "OR-2026-0001",
+    "status": "executed",
+    "order_type": "subscription_creation",
+    "execution_mode": "execute_in_lago",
+    "currency": "EUR",
+    "executed_at": "2026-07-01T00:00:00Z",
+    "execution_record": {
+      "executed_at": "2026-07-01T00:00:00Z",
+      "execution_mode": "execute_in_lago",
+      "invoice_id": null,
+      "subscription_ids": ["dd44dd44-dd44-dd44-dd44-dd44dd44dd44"],
+      "terminated_subscription_ids": [],
+      "applied_coupon_ids": ["ee55ee55-ee55-ee55-ee55-ee55ee55ee55"],
+      "wallet_ids": [],
+      "errors": []
+    },
+    "lago_organization_id": "3c123c12-3c12-3c12-3c12-3c123c123c12",
+    "lago_customer_id": "2b012b01-2b01-2b01-2b01-2b012b012b01",
+    "lago_order_form_id": "aa11aa11-aa11-aa11-aa11-aa11aa11aa11",
+    "created_at": "2026-05-02T10:15:00Z",
+    "updated_at": "2026-07-01T00:00:00Z",
+    "billing_snapshot": {
+      "plans": [
+        {
+          "id": "7a567a56-7a56-7a56-7a56-7a567a567a56",
+          "localId": "b5c1e2a4-4e1e-4a7f-9f0e-9c1a0c7e1f2b",
+          "type": "plan",
+          "payload": { "code": "premium_plan" }
+        }
+      ]
+    }
+  }
+}

spec/fixtures/api/order.json

@@ -0,0 +1,36 @@
+{
+  "order": {
+    "lago_id": "cc33cc33-cc33-cc33-cc33-cc33cc33cc33",
+    "number": "OR-2026-0001",
+    "status": "created",
+    "order_type": "subscription_creation",
+    "execution_mode": "execute_in_lago",
+    "currency": "EUR",
+    "executed_at": null,
+    "execution_record": {
+      "executed_at": null,
+      "execution_mode": "execute_in_lago",
+      "invoice_id": null,
+      "subscription_ids": [],
+      "terminated_subscription_ids": [],
+      "applied_coupon_ids": [],
+      "wallet_ids": [],
+      "errors": []
+    },
+    "lago_organization_id": "3c123c12-3c12-3c12-3c12-3c123c123c12",
+    "lago_customer_id": "2b012b01-2b01-2b01-2b01-2b012b012b01",
+    "lago_order_form_id": "aa11aa11-aa11-aa11-aa11-aa11aa11aa11",
+    "created_at": "2026-05-02T10:15:00Z",
+    "updated_at": "2026-05-02T10:15:00Z",
+    "billing_snapshot": {
+      "plans": [
+        {
+          "id": "7a567a56-7a56-7a56-7a56-7a567a567a56",
+          "localId": "b5c1e2a4-4e1e-4a7f-9f0e-9c1a0c7e1f2b",
+          "type": "plan",
+          "payload": { "code": "premium_plan" }
+        }
+      ]
+    }
+  }
+}

spec/fixtures/api/order_form.json

@@ -0,0 +1,18 @@
+{
+  "order_form": {
+    "lago_id": "aa11aa11-aa11-aa11-aa11-aa11aa11aa11",
+    "number": "OF-2026-0001",
+    "status": "generated",
+    "void_reason": null,
+    "expires_at": "2026-06-30T23:59:59Z",
+    "signed_at": null,
+    "voided_at": null,
+    "signed_document_url": null,
+    "lago_organization_id": "3c123c12-3c12-3c12-3c12-3c123c123c12",
+    "lago_customer_id": "2b012b01-2b01-2b01-2b01-2b012b012b01",
+    "lago_quote_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+    "lago_quote_version_id": "4d234d23-4d23-4d23-4d23-4d234d234d23",
+    "created_at": "2026-04-29T08:59:51Z",
+    "updated_at": "2026-04-29T08:59:51Z"
+  }
+}

spec/fixtures/api/order_forms_index.json

@@ -0,0 +1,43 @@
+{
+  "order_forms": [
+    {
+      "lago_id": "aa11aa11-aa11-aa11-aa11-aa11aa11aa11",
+      "number": "OF-2026-0001",
+      "status": "generated",
+      "void_reason": null,
+      "expires_at": "2026-06-30T23:59:59Z",
+      "signed_at": null,
+      "voided_at": null,
+      "signed_document_url": null,
+      "lago_organization_id": "3c123c12-3c12-3c12-3c12-3c123c123c12",
+      "lago_customer_id": "2b012b01-2b01-2b01-2b01-2b012b012b01",
+      "lago_quote_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+      "lago_quote_version_id": "4d234d23-4d23-4d23-4d23-4d234d234d23",
+      "created_at": "2026-04-29T08:59:51Z",
+      "updated_at": "2026-04-29T08:59:51Z"
+    },
+    {
+      "lago_id": "bb22bb22-bb22-bb22-bb22-bb22bb22bb22",
+      "number": "OF-2026-0002",
+      "status": "voided",
+      "void_reason": "manual",
+      "expires_at": null,
+      "signed_at": null,
+      "voided_at": "2026-05-01T09:00:00Z",
+      "signed_document_url": null,
+      "lago_organization_id": "3c123c12-3c12-3c12-3c12-3c123c123c12",
+      "lago_customer_id": "2b012b01-2b01-2b01-2b01-2b012b012b01",
+      "lago_quote_id": "6f456f45-6f45-6f45-6f45-6f456f456f45",
+      "lago_quote_version_id": "9c789c78-9c78-9c78-9c78-9c789c789c78",
+      "created_at": "2026-04-30T08:59:51Z",
+      "updated_at": "2026-05-01T09:00:00Z"
+    }
+  ],
+  "meta": {
+    "current_page": 1,
+    "next_page": null,
+    "prev_page": null,
+    "total_pages": 1,
+    "total_count": 2
+  }
+}

spec/fixtures/api/orders_index.json

@@ -0,0 +1,61 @@
+{
+  "orders": [
+    {
+      "lago_id": "cc33cc33-cc33-cc33-cc33-cc33cc33cc33",
+      "number": "OR-2026-0001",
+      "status": "created",
+      "order_type": "subscription_creation",
+      "execution_mode": "execute_in_lago",
+      "currency": "EUR",
+      "executed_at": null,
+      "execution_record": {
+        "executed_at": null,
+        "execution_mode": "execute_in_lago",
+        "invoice_id": null,
+        "subscription_ids": [],
+        "terminated_subscription_ids": [],
+        "applied_coupon_ids": [],
+        "wallet_ids": [],
+        "errors": []
+      },
+      "lago_organization_id": "3c123c12-3c12-3c12-3c12-3c123c123c12",
+      "lago_customer_id": "2b012b01-2b01-2b01-2b01-2b012b012b01",
+      "lago_order_form_id": "aa11aa11-aa11-aa11-aa11-aa11aa11aa11",
+      "created_at": "2026-05-02T10:15:00Z",
+      "updated_at": "2026-05-02T10:15:00Z",
+      "billing_snapshot": {}
+    },
+    {
+      "lago_id": "ff66ff66-ff66-ff66-ff66-ff66ff66ff66",
+      "number": "OR-2026-0002",
+      "status": "failed",
+      "order_type": "one_off",
+      "execution_mode": null,
+      "currency": "EUR",
+      "executed_at": null,
+      "execution_record": {
+        "executed_at": null,
+        "execution_mode": null,
+        "invoice_id": null,
+        "subscription_ids": [],
+        "terminated_subscription_ids": [],
+        "applied_coupon_ids": [],
+        "wallet_ids": [],
+        "errors": ["plan_not_found"]
+      },
+      "lago_organization_id": "3c123c12-3c12-3c12-3c12-3c123c123c12",
+      "lago_customer_id": "2b012b01-2b01-2b01-2b01-2b012b012b01",
+      "lago_order_form_id": "bb22bb22-bb22-bb22-bb22-bb22bb22bb22",
+      "created_at": "2026-05-03T10:15:00Z",
+      "updated_at": "2026-05-03T10:15:00Z",
+      "billing_snapshot": {}
+    }
+  ],
+  "meta": {
+    "current_page": 1,
+    "next_page": null,
+    "prev_page": null,
+    "total_pages": 1,
+    "total_count": 2
+  }
+}

spec/fixtures/api/signed_order_form.json

@@ -0,0 +1,18 @@
+{
+  "order_form": {
+    "lago_id": "aa11aa11-aa11-aa11-aa11-aa11aa11aa11",
+    "number": "OF-2026-0001",
+    "status": "signed",
+    "void_reason": null,
+    "expires_at": "2026-06-30T23:59:59Z",
+    "signed_at": "2026-05-02T10:15:00Z",
+    "voided_at": null,
+    "signed_document_url": "https://api.getlago.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMi/OF-2026-0001",
+    "lago_organization_id": "3c123c12-3c12-3c12-3c12-3c123c123c12",
+    "lago_customer_id": "2b012b01-2b01-2b01-2b01-2b012b012b01",
+    "lago_quote_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+    "lago_quote_version_id": "4d234d23-4d23-4d23-4d23-4d234d234d23",
+    "created_at": "2026-04-29T08:59:51Z",
+    "updated_at": "2026-05-02T10:15:00Z"
+  }
+}