release: 1.13.0

.github/workflows/ci.yml

@@ -13,6 +13,40 @@ on:
       - 'stl-preview-base/**'
 
 jobs:
+  build:
+    timeout-minutes: 10
+    name: build
+    permissions:
+      contents: read
+      id-token: write
+    runs-on: ${{ github.repository == 'stainless-sdks/orb-ruby' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
+    if: |-
+      github.repository == 'stainless-sdks/orb-ruby' &&
+      (github.event_name == 'push' || github.event.pull_request.head.repo.fork)
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: false
+      - run: |-
+          bundle install
+
+      - name: Get GitHub OIDC Token
+        if: github.repository == 'stainless-sdks/orb-ruby'
+        id: github-oidc
+        uses: actions/github-script@v8
+        with:
+          script: core.setOutput('github_token', await core.getIDToken());
+
+      - name: Build and upload gem artifacts
+        if: github.repository == 'stainless-sdks/orb-ruby'
+        env:
+          URL: https://pkg.stainless.com/s
+          AUTH: ${{ steps.github-oidc.outputs.github_token }}
+          SHA: ${{ github.sha }}
+          PACKAGE_NAME: orb
+        run: ./scripts/utils/upload-artifact.sh
   lint:
     timeout-minutes: 10
     name: lint

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.12.0"
+  ".": "1.13.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 139
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-c92fb451e13f157b3735f188acc8d57aa3adfbaac1683645e1ba4f432dd7a4f8.yml
-openapi_spec_hash: dbcd87ecfbd3976eb3b99ec6f9fbc606
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-5bb582f84f0b4cf7bef84833fefd48a5f2734dc25805da2028fd8a6f1198da07.yml
+openapi_spec_hash: ced0e30dc67faa2414df511819408f12
 config_hash: 3279841440b02d4e8303c961d6983492

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.13.0 (2026-03-03)
+
+Full Changelog: [v1.12.0...v1.13.0](https://github.com/orbcorp/orb-ruby/compare/v1.12.0...v1.13.0)
+
+### Features
+
+* **api:** api update ([c203926](https://github.com/orbcorp/orb-ruby/commit/c203926582b3237293d3078ada79bf3d221071d7))
+* **api:** api update ([fd4f82d](https://github.com/orbcorp/orb-ruby/commit/fd4f82dd2f04f36cd49a7413fdfaa5e1189f22c2))
+* **api:** api update ([a703c63](https://github.com/orbcorp/orb-ruby/commit/a703c638264d4dd7761a3534562f47a86b8da288))
+* **api:** api update ([49c2213](https://github.com/orbcorp/orb-ruby/commit/49c22131d40a8e0e050f894be9ff48d5958301aa))
+* **api:** api update ([357d2d4](https://github.com/orbcorp/orb-ruby/commit/357d2d4e2758c92578d1c7af1e26f1a1779738b0))
+
+
+### Bug Fixes
+
+* **client:** serialize query parameters properly ([003ab4e](https://github.com/orbcorp/orb-ruby/commit/003ab4e466176c051711b7e89e1e40be5de6a664))
+* properly mock time in ruby ci tests ([c8c588e](https://github.com/orbcorp/orb-ruby/commit/c8c588eb8bd5383d1875fef102cd7de66d6dff71))
+
+
+### Chores
+
+* **ci:** add build step ([b57c8a3](https://github.com/orbcorp/orb-ruby/commit/b57c8a3f52e22c5c67f3842357747437d12f56d7))
+* **docs:** add missing descriptions ([174bbeb](https://github.com/orbcorp/orb-ruby/commit/174bbebe6ed10a5c2c079232299b48b4269e470c))
+* update mock server docs ([4b838cf](https://github.com/orbcorp/orb-ruby/commit/4b838cf2bc89666bea9767ae25e66868d38bbeef))
+
 ## 1.12.0 (2026-02-12)
 
 Full Changelog: [v1.11.2...v1.12.0](https://github.com/orbcorp/orb-ruby/compare/v1.11.2...v1.12.0)

CONTRIBUTING.md

@@ -68,8 +68,8 @@ $ bundle exec rake
 
 Most tests require you to [set up a mock server](https://github.com/stoplightio/prism) against the OpenAPI spec to run the tests.
 
-```bash
-$ npx prism mock path/to/your/openapi.yml
+```sh
+$ ./scripts/mock
 ```
 
 ```bash

Gemfile.lock

@@ -11,7 +11,7 @@ GIT
 PATH
   remote: .
   specs:
-    orb-billing (1.12.0)
+    orb-billing (1.13.0)
       cgi
       connection_pool
 

README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "orb-billing", "~> 1.12.0"
+gem "orb-billing", "~> 1.13.0"
 ```
 
 <!-- x-release-please-end -->

lib/orb/client.rb

@@ -21,42 +21,109 @@ class Client < Orb::Internal::Transport::BaseClient
     # @return [Orb::Resources::TopLevel]
     attr_reader :top_level
 
+    # The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be
+    # subscribed to by a customer. Plans define the billing behavior of the
+    # subscription. You can see more about how to configure prices in the
+    # [Price resource](/reference/price).
     # @return [Orb::Resources::Beta]
     attr_reader :beta
 
+    # A coupon represents a reusable discount configuration that can be applied either
+    # as a fixed or percentage amount to an invoice or subscription. Coupons are
+    # activated using a redemption code, which applies the discount to a subscription
+    # or invoice. The duration of a coupon determines how long it remains available
+    # for use by end users.
     # @return [Orb::Resources::Coupons]
     attr_reader :coupons
 
+    # The [Credit Note](/invoicing/credit-notes) resource represents a credit that has
+    # been applied to a particular invoice.
     # @return [Orb::Resources::CreditNotes]
     attr_reader :credit_notes
 
+    # A customer is a buyer of your products, and the other party to the billing
+    # relationship.
+    #
+    # In Orb, customers are assigned system generated identifiers automatically, but
+    # it's often desirable to have these match existing identifiers in your system. To
+    # avoid having to denormalize Orb ID information, you can pass in an
+    # `external_customer_id` with your own identifier. See
+    # [Customer ID Aliases](/events-and-metrics/customer-aliases) for further
+    # information about how these aliases work in Orb.
+    #
+    # In addition to having an identifier in your system, a customer may exist in a
+    # payment provider solution like Stripe. Use the `payment_provider_id` and the
+    # `payment_provider` enum field to express this mapping.
+    #
+    # A customer also has a timezone (from the standard
+    # [IANA timezone database](https://www.iana.org/time-zones)), which defaults to
+    # your account's timezone. See [Timezone localization](/essentials/timezones) for
+    # information on what this timezone parameter influences within Orb.
     # @return [Orb::Resources::Customers]
     attr_reader :customers
 
+    # The [Event](/core-concepts#event) resource represents a usage event that has
+    # been created for a customer. Events are the core of Orb's usage-based billing
+    # model, and are used to calculate the usage charges for a given billing period.
     # @return [Orb::Resources::Events]
     attr_reader :events
 
+    # An [`Invoice`](/core-concepts#invoice) is a fundamental billing entity,
+    # representing the request for payment for a single subscription. This includes a
+    # set of line items, which correspond to prices in the subscription's plan and can
+    # represent fixed recurring fees or usage-based fees. They are generated at the
+    # end of a billing period, or as the result of an action, such as a cancellation.
     # @return [Orb::Resources::InvoiceLineItems]
     attr_reader :invoice_line_items
 
+    # An [`Invoice`](/core-concepts#invoice) is a fundamental billing entity,
+    # representing the request for payment for a single subscription. This includes a
+    # set of line items, which correspond to prices in the subscription's plan and can
+    # represent fixed recurring fees or usage-based fees. They are generated at the
+    # end of a billing period, or as the result of an action, such as a cancellation.
     # @return [Orb::Resources::Invoices]
     attr_reader :invoices
 
+    # The Item resource represents a sellable product or good. Items are associated
+    # with all line items, billable metrics, and prices and are used for defining
+    # external sync behavior for invoices and tax calculation purposes.
     # @return [Orb::Resources::Items]
     attr_reader :items
 
+    # The Metric resource represents a calculation of a quantity based on events.
+    # Metrics are defined by the query that transforms raw usage events into
+    # meaningful values for your customers.
     # @return [Orb::Resources::Metrics]
     attr_reader :metrics
 
+    # The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be
+    # subscribed to by a customer. Plans define the billing behavior of the
+    # subscription. You can see more about how to configure prices in the
+    # [Price resource](/reference/price).
     # @return [Orb::Resources::Plans]
     attr_reader :plans
 
+    # The Price resource represents a price that can be billed on a subscription,
+    # resulting in a charge on an invoice in the form of an invoice line item. Prices
+    # take a quantity and determine an amount to bill.
+    #
+    # Orb supports a few different pricing models out of the box. Each of these models
+    # is serialized differently in a given Price object. The model_type field
+    # determines the key for the configuration object that is present.
+    #
+    # For more on the types of prices, see
+    # [the core concepts documentation](/core-concepts#plan-and-price)
     # @return [Orb::Resources::Prices]
     attr_reader :prices
 
     # @return [Orb::Resources::Subscriptions]
     attr_reader :subscriptions
 
+    # [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending,
+    # usage, or credit balance and trigger webhooks when a threshold is exceeded.
+    #
+    # Alerts created through the API can be scoped to either customers or
+    # subscriptions.
     # @return [Orb::Resources::Alerts]
     attr_reader :alerts
 
@@ -66,9 +133,14 @@ class Client < Orb::Internal::Transport::BaseClient
     # @return [Orb::Resources::SubscriptionChanges]
     attr_reader :subscription_changes
 
+    # The [Credit Ledger Entry resource](/product-catalog/prepurchase) models prepaid
+    # credits within Orb.
     # @return [Orb::Resources::CreditBlocks]
     attr_reader :credit_blocks
 
+    # The LicenseType resource represents a type of license that can be assigned to
+    # users. License types are used during billing by grouping metrics on the
+    # configured grouping key.
     # @return [Orb::Resources::LicenseTypes]
     attr_reader :license_types
 

lib/orb/internal/util.rb

@@ -490,6 +490,37 @@ def writable_enum(&blk)
       JSONL_CONTENT = %r{^application/(:?x-(?:n|l)djson)|(:?(?:x-)?jsonl)}
 
       class << self
+        # @api private
+        #
+        # @param query [Hash{Symbol=>Object}]
+        #
+        # @return [Hash{Symbol=>Object}]
+        def encode_query_params(query)
+          out = {}
+          query.each { write_query_param_element!(out, _1, _2) }
+          out
+        end
+
+        # @api private
+        #
+        # @param collection [Hash{Symbol=>Object}]
+        # @param key [String]
+        # @param element [Object]
+        #
+        # @return [nil]
+        private def write_query_param_element!(collection, key, element)
+          case element
+          in Hash
+            element.each do |name, value|
+              write_query_param_element!(collection, "#{key}[#{name}]", value)
+            end
+          in Array
+            collection["#{key}[]"] = element.map(&:to_s)
+          else
+            collection[key] = element.to_s
+          end
+        end
+
         # @api private
         #
         # @param y [Enumerator::Yielder]

lib/orb/models/billable_metric.rb

@@ -41,7 +41,14 @@ class BillableMetric < Orb::Internal::Type::BaseModel
       #   @return [Symbol, Orb::Models::BillableMetric::Status]
       required :status, enum: -> { Orb::BillableMetric::Status }
 
-      # @!method initialize(id:, description:, item:, metadata:, name:, status:)
+      # @!attribute parameter_definitions
+      #
+      #   @return [Array<Hash{Symbol=>Object}>, nil]
+      optional :parameter_definitions,
+               Orb::Internal::Type::ArrayOf[Orb::Internal::Type::HashOf[Orb::Internal::Type::Unknown]],
+               nil?: true
+
+      # @!method initialize(id:, description:, item:, metadata:, name:, status:, parameter_definitions: nil)
       #   Some parameter documentations has been truncated, see
       #   {Orb::Models::BillableMetric} for more details.
       #
@@ -60,6 +67,8 @@ class BillableMetric < Orb::Internal::Type::BaseModel
       #   @param name [String]
       #
       #   @param status [Symbol, Orb::Models::BillableMetric::Status]
+      #
+      #   @param parameter_definitions [Array<Hash{Symbol=>Object}>, nil]
 
       # @see Orb::Models::BillableMetric#status
       module Status

lib/orb/models/customers/credits/ledger_create_entry_by_external_id_params.rb

@@ -243,6 +243,12 @@ class InvoiceSettings < Orb::Internal::Type::BaseModel
             #   @return [String, nil]
             optional :item_id, String, nil?: true
 
+            # @!attribute mark_as_paid
+            #   If true, the new credits purchase invoice will be marked as paid.
+            #
+            #   @return [Boolean, nil]
+            optional :mark_as_paid, Orb::Internal::Type::Boolean
+
             # @!attribute memo
             #   An optional memo to display on the invoice.
             #
@@ -254,7 +260,8 @@ class InvoiceSettings < Orb::Internal::Type::BaseModel
             #   based on the invoice or issuance date, depending on the account's configured due
             #   date calculation method. A value of '0' here represents that the invoice is due
             #   on issue, whereas a value of '30' represents that the customer has 30 days to
-            #   pay the invoice. Do not set this field if you want to set a custom due date.
+            #   pay the invoice. You must set either `net_terms` or `custom_due_date`, but not
+            #   both.
             #
             #   @return [Integer, nil]
             optional :net_terms, Integer, nil?: true
@@ -266,7 +273,7 @@ class InvoiceSettings < Orb::Internal::Type::BaseModel
             #   @return [Boolean, nil]
             optional :require_successful_payment, Orb::Internal::Type::Boolean
 
-            # @!method initialize(auto_collection:, custom_due_date: nil, invoice_date: nil, item_id: nil, memo: nil, net_terms: nil, require_successful_payment: nil)
+            # @!method initialize(auto_collection:, custom_due_date: nil, invoice_date: nil, item_id: nil, mark_as_paid: nil, memo: nil, net_terms: nil, require_successful_payment: nil)
             #   Some parameter documentations has been truncated, see
             #   {Orb::Models::Customers::Credits::LedgerCreateEntryByExternalIDParams::InvoiceSettings}
             #   for more details.
@@ -284,6 +291,8 @@ class InvoiceSettings < Orb::Internal::Type::BaseModel
             #
             #   @param item_id [String, nil] The ID of the Item to be used for the invoice line item. If not provided, a defa
             #
+            #   @param mark_as_paid [Boolean] If true, the new credits purchase invoice will be marked as paid.
+            #
             #   @param memo [String, nil] An optional memo to display on the invoice.
             #
             #   @param net_terms [Integer, nil] The net terms determines the due date of the invoice. Due date is calculated bas

lib/orb/models/customers/credits/ledger_create_entry_params.rb

@@ -241,6 +241,12 @@ class InvoiceSettings < Orb::Internal::Type::BaseModel
             #   @return [String, nil]
             optional :item_id, String, nil?: true
 
+            # @!attribute mark_as_paid
+            #   If true, the new credits purchase invoice will be marked as paid.
+            #
+            #   @return [Boolean, nil]
+            optional :mark_as_paid, Orb::Internal::Type::Boolean
+
             # @!attribute memo
             #   An optional memo to display on the invoice.
             #
@@ -252,7 +258,8 @@ class InvoiceSettings < Orb::Internal::Type::BaseModel
             #   based on the invoice or issuance date, depending on the account's configured due
             #   date calculation method. A value of '0' here represents that the invoice is due
             #   on issue, whereas a value of '30' represents that the customer has 30 days to
-            #   pay the invoice. Do not set this field if you want to set a custom due date.
+            #   pay the invoice. You must set either `net_terms` or `custom_due_date`, but not
+            #   both.
             #
             #   @return [Integer, nil]
             optional :net_terms, Integer, nil?: true
@@ -264,7 +271,7 @@ class InvoiceSettings < Orb::Internal::Type::BaseModel
             #   @return [Boolean, nil]
             optional :require_successful_payment, Orb::Internal::Type::Boolean
 
-            # @!method initialize(auto_collection:, custom_due_date: nil, invoice_date: nil, item_id: nil, memo: nil, net_terms: nil, require_successful_payment: nil)
+            # @!method initialize(auto_collection:, custom_due_date: nil, invoice_date: nil, item_id: nil, mark_as_paid: nil, memo: nil, net_terms: nil, require_successful_payment: nil)
             #   Some parameter documentations has been truncated, see
             #   {Orb::Models::Customers::Credits::LedgerCreateEntryParams::InvoiceSettings} for
             #   more details.
@@ -282,6 +289,8 @@ class InvoiceSettings < Orb::Internal::Type::BaseModel
             #
             #   @param item_id [String, nil] The ID of the Item to be used for the invoice line item. If not provided, a defa
             #
+            #   @param mark_as_paid [Boolean] If true, the new credits purchase invoice will be marked as paid.
+            #
             #   @param memo [String, nil] An optional memo to display on the invoice.
             #
             #   @param net_terms [Integer, nil] The net terms determines the due date of the invoice. Due date is calculated bas