orb-billing 0.1.0.pre.alpha.37 → 0.1.0.pre.alpha.39

data/lib/orb/resources/invoices.rb

@@ -34,10 +34,10 @@ module Orb
       end
 
       # This endpoint allows you to update the `metadata` property on an invoice. If you
-      #   pass null for the metadata value, it will clear any existing metadata for that
-      #   invoice.
+      # pass null for the metadata value, it will clear any existing metadata for that
+      # invoice.
       #
-      #   `metadata` can be modified regardless of invoice state.
+      # `metadata` can be modified regardless of invoice state.
       #
       # @overload update(invoice_id, metadata: nil, request_options: {})
       #
@@ -60,18 +60,18 @@ module Orb
       end
 
       # This endpoint returns a list of all [`Invoice`](/core-concepts#invoice)s for an
-      #   account in a list format.
+      # account in a list format.
       #
-      #   The list of invoices is ordered starting from the most recently issued invoice
-      #   date. The response also includes
-      #   [`pagination_metadata`](/api-reference/pagination), which lets the caller
-      #   retrieve the next page of results if they exist.
+      # The list of invoices is ordered starting from the most recently issued invoice
+      # date. The response also includes
+      # [`pagination_metadata`](/api-reference/pagination), which lets the caller
+      # retrieve the next page of results if they exist.
       #
-      #   By default, this only returns invoices that are `issued`, `paid`, or `synced`.
+      # By default, this only returns invoices that are `issued`, `paid`, or `synced`.
       #
-      #   When fetching any `draft` invoices, this returns the last-computed invoice
-      #   values for each draft invoice, which may not always be up-to-date since Orb
-      #   regularly refreshes invoices asynchronously.
+      # When fetching any `draft` invoices, this returns the last-computed invoice
+      # values for each draft invoice, which may not always be up-to-date since Orb
+      # regularly refreshes invoices asynchronously.
       #
       # @overload list(amount: nil, amount_gt: nil, amount_lt: nil, cursor: nil, customer_id: nil, date_type: nil, due_date: nil, due_date_window: nil, due_date_gt: nil, due_date_lt: nil, external_customer_id: nil, invoice_date_gt: nil, invoice_date_gte: nil, invoice_date_lt: nil, invoice_date_lte: nil, is_recurring: nil, limit: nil, status: nil, subscription_id: nil, request_options: {})
       #
@@ -104,7 +104,16 @@ module Orb
         @client.request(
           method: :get,
           path: "invoices",
-          query: parsed,
+          query: parsed.transform_keys(
+            amount_gt: "amount[gt]",
+            amount_lt: "amount[lt]",
+            due_date_gt: "due_date[gt]",
+            due_date_lt: "due_date[lt]",
+            invoice_date_gt: "invoice_date[gt]",
+            invoice_date_gte: "invoice_date[gte]",
+            invoice_date_lt: "invoice_date[lt]",
+            invoice_date_lte: "invoice_date[lte]"
+          ),
           page: Orb::Internal::Page,
           model: Orb::Models::Invoice,
           options: options
@@ -112,7 +121,7 @@ module Orb
       end
 
       # This endpoint is used to fetch an [`Invoice`](/core-concepts#invoice) given an
-      #   identifier.
+      # identifier.
       #
       # @overload fetch(invoice_id, request_options: {})
       #
@@ -132,8 +141,8 @@ module Orb
       end
 
       # This endpoint can be used to fetch the upcoming
-      #   [invoice](/core-concepts#invoice) for the current billing period given a
-      #   subscription.
+      # [invoice](/core-concepts#invoice) for the current billing period given a
+      # subscription.
       #
       # @overload fetch_upcoming(subscription_id:, request_options: {})
       #
@@ -155,11 +164,11 @@ module Orb
       end
 
       # This endpoint allows an eligible invoice to be issued manually. This is only
-      #   possible with invoices where status is `draft`, `will_auto_issue` is false, and
-      #   an `eligible_to_issue_at` is a time in the past. Issuing an invoice could
-      #   possibly trigger side effects, some of which could be customer-visible (e.g.
-      #   sending emails, auto-collecting payment, syncing the invoice to external
-      #   providers, etc).
+      # possible with invoices where status is `draft`, `will_auto_issue` is false, and
+      # an `eligible_to_issue_at` is a time in the past. Issuing an invoice could
+      # possibly trigger side effects, some of which could be customer-visible (e.g.
+      # sending emails, auto-collecting payment, syncing the invoice to external
+      # providers, etc).
       #
       # @overload issue(invoice_id, synchronous: nil, request_options: {})
       #
@@ -182,7 +191,7 @@ module Orb
       end
 
       # This endpoint allows an invoice's status to be set the `paid` status. This can
-      #   only be done to invoices that are in the `issued` status.
+      # only be done to invoices that are in the `issued` status.
       #
       # @overload mark_paid(invoice_id, payment_received_date:, external_id: nil, notes: nil, request_options: {})
       #
@@ -207,7 +216,7 @@ module Orb
       end
 
       # This endpoint collects payment for an invoice using the customer's default
-      #   payment method. This action can only be taken on invoices with status "issued".
+      # payment method. This action can only be taken on invoices with status "issued".
       #
       # @overload pay(invoice_id, request_options: {})
       #
@@ -227,16 +236,16 @@ module Orb
       end
 
       # This endpoint allows an invoice's status to be set the `void` status. This can
-      #   only be done to invoices that are in the `issued` status.
+      # only be done to invoices that are in the `issued` status.
       #
-      #   If the associated invoice has used the customer balance to change the amount
-      #   due, the customer balance operation will be reverted. For example, if the
-      #   invoice used $10 of customer balance, that amount will be added back to the
-      #   customer balance upon voiding.
+      # If the associated invoice has used the customer balance to change the amount
+      # due, the customer balance operation will be reverted. For example, if the
+      # invoice used $10 of customer balance, that amount will be added back to the
+      # customer balance upon voiding.
       #
-      #   If the invoice was used to purchase a credit block, but the invoice is not yet
-      #   paid, the credit block will be voided. If the invoice was created due to a
-      #   top-up, the top-up will be disabled.
+      # If the invoice was used to purchase a credit block, but the invoice is not yet
+      # paid, the credit block will be voided. If the invoice was created due to a
+      # top-up, the top-up will be disabled.
       #
       # @overload void(invoice_id, request_options: {})
       #

data/lib/orb/resources/items.rb

@@ -42,7 +42,7 @@ module Orb
       end
 
       # This endpoint returns a list of all Items, ordered in descending order by
-      #   creation time.
+      # creation time.
       #
       # @overload list(cursor: nil, limit: nil, request_options: {})
       #

data/lib/orb/resources/metrics.rb

@@ -4,8 +4,8 @@ module Orb
   module Resources
     class Metrics
       # This endpoint is used to create a [metric](/core-concepts###metric) using a SQL
-      #   string. See [SQL support](/extensibility/advanced-metrics#sql-support) for a
-      #   description of constructing SQL queries with examples.
+      # string. See [SQL support](/extensibility/advanced-metrics#sql-support) for a
+      # description of constructing SQL queries with examples.
       #
       # @overload create(description:, item_id:, name:, sql:, metadata: nil, request_options: {})
       #
@@ -31,8 +31,8 @@ module Orb
       end
 
       # This endpoint allows you to update the `metadata` property on a metric. If you
-      #   pass `null` for the metadata value, it will clear any existing metadata for that
-      #   invoice.
+      # pass `null` for the metadata value, it will clear any existing metadata for that
+      # invoice.
       #
       # @overload update(metric_id, metadata: nil, request_options: {})
       #
@@ -55,8 +55,8 @@ module Orb
       end
 
       # This endpoint is used to fetch [metric](/core-concepts##metric) details given a
-      #   metric identifier. It returns information about the metrics including its name,
-      #   description, and item.
+      # metric identifier. It returns information about the metrics including its name,
+      # description, and item.
       #
       # @overload list(created_at_gt: nil, created_at_gte: nil, created_at_lt: nil, created_at_lte: nil, cursor: nil, limit: nil, request_options: {})
       #
@@ -76,7 +76,12 @@ module Orb
         @client.request(
           method: :get,
           path: "metrics",
-          query: parsed,
+          query: parsed.transform_keys(
+            created_at_gt: "created_at[gt]",
+            created_at_gte: "created_at[gte]",
+            created_at_lt: "created_at[lt]",
+            created_at_lte: "created_at[lte]"
+          ),
           page: Orb::Internal::Page,
           model: Orb::Models::BillableMetric,
           options: options
@@ -84,7 +89,7 @@ module Orb
       end
 
       # This endpoint is used to list [metrics](/core-concepts#metric). It returns
-      #   information about the metrics including its name, description, and item.
+      # information about the metrics including its name, description, and item.
       #
       # @overload fetch(metric_id, request_options: {})
       #

data/lib/orb/resources/plans/external_plan_id.rb

@@ -5,9 +5,9 @@ module Orb
     class Plans
       class ExternalPlanID
         # This endpoint can be used to update the `external_plan_id`, and `metadata` of an
-        #   existing plan.
+        # existing plan.
         #
-        #   Other fields on a customer are currently immutable.
+        # Other fields on a customer are currently immutable.
         #
         # @overload update(other_external_plan_id, external_plan_id: nil, metadata: nil, request_options: {})
         #
@@ -31,21 +31,21 @@ module Orb
         end
 
         # This endpoint is used to fetch [plan](/core-concepts##plan-and-price) details
-        #   given an external_plan_id identifier. It returns information about the prices
-        #   included in the plan and their configuration, as well as the product that the
-        #   plan is attached to.
+        # given an external_plan_id identifier. It returns information about the prices
+        # included in the plan and their configuration, as well as the product that the
+        # plan is attached to.
         #
-        #   If multiple plans are found to contain the specified external_plan_id, the
-        #   active plans will take priority over archived ones, and among those, the
-        #   endpoint will return the most recently created plan.
+        # If multiple plans are found to contain the specified external_plan_id, the
+        # active plans will take priority over archived ones, and among those, the
+        # endpoint will return the most recently created plan.
         #
-        #   ## Serialized prices
+        # ## Serialized prices
         #
-        #   Orb supports a few different pricing models out of the box. Each of these models
-        #   is serialized differently in a given [Price](/core-concepts#plan-and-price)
-        #   object. The `model_type` field determines the key for the configuration object
-        #   that is present. A detailed explanation of price types can be found in the
-        #   [Price schema](/core-concepts#plan-and-price). "
+        # Orb supports a few different pricing models out of the box. Each of these models
+        # is serialized differently in a given [Price](/core-concepts#plan-and-price)
+        # object. The `model_type` field determines the key for the configuration object
+        # that is present. A detailed explanation of price types can be found in the
+        # [Price schema](/core-concepts#plan-and-price). "
         #
         # @overload fetch(external_plan_id, request_options: {})
         #

data/lib/orb/resources/plans.rb

@@ -29,9 +29,9 @@ module Orb
       end
 
       # This endpoint can be used to update the `external_plan_id`, and `metadata` of an
-      #   existing plan.
+      # existing plan.
       #
-      #   Other fields on a customer are currently immutable.
+      # Other fields on a customer are currently immutable.
       #
       # @overload update(plan_id, external_plan_id: nil, metadata: nil, request_options: {})
       #
@@ -55,10 +55,10 @@ module Orb
       end
 
       # This endpoint returns a list of all [plans](/core-concepts#plan-and-price) for
-      #   an account in a list format. The list of plans is ordered starting from the most
-      #   recently created plan. The response also includes
-      #   [`pagination_metadata`](/api-reference/pagination), which lets the caller
-      #   retrieve the next page of results if they exist.
+      # an account in a list format. The list of plans is ordered starting from the most
+      # recently created plan. The response also includes
+      # [`pagination_metadata`](/api-reference/pagination), which lets the caller
+      # retrieve the next page of results if they exist.
       #
       # @overload list(created_at_gt: nil, created_at_gte: nil, created_at_lt: nil, created_at_lte: nil, cursor: nil, limit: nil, status: nil, request_options: {})
       #
@@ -79,7 +79,12 @@ module Orb
         @client.request(
           method: :get,
           path: "plans",
-          query: parsed,
+          query: parsed.transform_keys(
+            created_at_gt: "created_at[gt]",
+            created_at_gte: "created_at[gte]",
+            created_at_lt: "created_at[lt]",
+            created_at_lte: "created_at[lte]"
+          ),
           page: Orb::Internal::Page,
           model: Orb::Models::Plan,
           options: options
@@ -87,22 +92,22 @@ module Orb
       end
 
       # This endpoint is used to fetch [plan](/core-concepts#plan-and-price) details
-      #   given a plan identifier. It returns information about the prices included in the
-      #   plan and their configuration, as well as the product that the plan is attached
-      #   to.
+      # given a plan identifier. It returns information about the prices included in the
+      # plan and their configuration, as well as the product that the plan is attached
+      # to.
       #
-      #   ## Serialized prices
+      # ## Serialized prices
       #
-      #   Orb supports a few different pricing models out of the box. Each of these models
-      #   is serialized differently in a given [Price](/core-concepts#plan-and-price)
-      #   object. The `model_type` field determines the key for the configuration object
-      #   that is present. A detailed explanation of price types can be found in the
-      #   [Price schema](/core-concepts#plan-and-price).
+      # Orb supports a few different pricing models out of the box. Each of these models
+      # is serialized differently in a given [Price](/core-concepts#plan-and-price)
+      # object. The `model_type` field determines the key for the configuration object
+      # that is present. A detailed explanation of price types can be found in the
+      # [Price schema](/core-concepts#plan-and-price).
       #
-      #   ## Phases
+      # ## Phases
       #
-      #   Orb supports plan phases, also known as contract ramps. For plans with phases,
-      #   the serialized prices refer to all prices across all phases.
+      # Orb supports plan phases, also known as contract ramps. For plans with phases,
+      # the serialized prices refer to all prices across all phases.
       #
       # @overload fetch(plan_id, request_options: {})
       #

data/lib/orb/resources/prices/external_price_id.rb

@@ -5,8 +5,8 @@ module Orb
     class Prices
       class ExternalPriceID
         # This endpoint allows you to update the `metadata` property on a price. If you
-        #   pass null for the metadata value, it will clear any existing metadata for that
-        #   price.
+        # pass null for the metadata value, it will clear any existing metadata for that
+        # price.
         #
         # @overload update(external_price_id, metadata: nil, request_options: {})
         #
@@ -29,8 +29,8 @@ module Orb
         end
 
         # This endpoint returns a price given an external price id. See the
-        #   [price creation API](/api-reference/price/create-price) for more information
-        #   about external price aliases.
+        # [price creation API](/api-reference/price/create-price) for more information
+        # about external price aliases.
         #
         # @overload fetch(external_price_id, request_options: {})
         #

data/lib/orb/resources/prices.rb

@@ -7,15 +7,15 @@ module Orb
       attr_reader :external_price_id
 
       # This endpoint is used to create a [price](/product-catalog/price-configuration).
-      #   A price created using this endpoint is always an add-on, meaning that it’s not
-      #   associated with a specific plan and can instead be individually added to
-      #   subscriptions, including subscriptions on different plans.
+      # A price created using this endpoint is always an add-on, meaning that it’s not
+      # associated with a specific plan and can instead be individually added to
+      # subscriptions, including subscriptions on different plans.
       #
-      #   An `external_price_id` can be optionally specified as an alias to allow
-      #   ergonomic interaction with prices in the Orb API.
+      # An `external_price_id` can be optionally specified as an alias to allow
+      # ergonomic interaction with prices in the Orb API.
       #
-      #   See the [Price resource](/product-catalog/price-configuration) for the
-      #   specification of different price model configurations possible in this endpoint.
+      # See the [Price resource](/product-catalog/price-configuration) for the
+      # specification of different price model configurations possible in this endpoint.
       #
       # @overload create(cadence:, currency:, item_id:, model_type:, name:, unit_config:, package_config:, matrix_config:, matrix_with_allocation_config:, tiered_config:, tiered_bps_config:, bps_config:, bulk_bps_config:, bulk_config:, threshold_total_amount_config:, tiered_package_config:, grouped_tiered_config:, max_group_tiered_package_config:, tiered_with_minimum_config:, package_with_allocation_config:, tiered_package_with_minimum_config:, unit_with_percent_config:, tiered_with_proration_config:, unit_with_proration_config:, grouped_allocation_config:, grouped_with_prorated_minimum_config:, grouped_with_metered_minimum_config:, matrix_with_display_name_config:, bulk_with_proration_config:, grouped_tiered_package_config:, scalable_matrix_with_unit_pricing_config:, scalable_matrix_with_tiered_pricing_config:, cumulative_grouped_bulk_config:, billable_metric_id: nil, billed_in_advance: nil, billing_cycle_configuration: nil, conversion_rate: nil, external_price_id: nil, fixed_price_quantity: nil, invoice_grouping_key: nil, invoicing_cycle_configuration: nil, metadata: nil, request_options: {})
       #
@@ -72,8 +72,8 @@ module Orb
       end
 
       # This endpoint allows you to update the `metadata` property on a price. If you
-      #   pass null for the metadata value, it will clear any existing metadata for that
-      #   price.
+      # pass null for the metadata value, it will clear any existing metadata for that
+      # price.
       #
       # @overload update(price_id, metadata: nil, request_options: {})
       #
@@ -96,7 +96,7 @@ module Orb
       end
 
       # This endpoint is used to list all add-on prices created using the
-      #   [price creation endpoint](/api-reference/price/create-price).
+      # [price creation endpoint](/api-reference/price/create-price).
       #
       # @overload list(cursor: nil, limit: nil, request_options: {})
       #
@@ -120,26 +120,26 @@ module Orb
       end
 
       # This endpoint is used to evaluate the output of a price for a given customer and
-      #   time range. It enables filtering and grouping the output using
-      #   [computed properties](/extensibility/advanced-metrics#computed-properties),
-      #   supporting the following workflows:
-      #
-      #   1. Showing detailed usage and costs to the end customer.
-      #   2. Auditing subtotals on invoice line items.
-      #
-      #   For these workflows, the expressiveness of computed properties in both the
-      #   filters and grouping is critical. For example, if you'd like to show your
-      #   customer their usage grouped by hour and another property, you can do so with
-      #   the following `grouping_keys`:
-      #   `["hour_floor_timestamp_millis(timestamp_millis)", "my_property"]`. If you'd
-      #   like to examine a customer's usage for a specific property value, you can do so
-      #   with the following `filter`:
-      #   `my_property = 'foo' AND my_other_property = 'bar'`.
-      #
-      #   By default, the start of the time range must be no more than 100 days ago and
-      #   the length of the results must be no greater than 1000. Note that this is a POST
-      #   endpoint rather than a GET endpoint because it employs a JSON body rather than
-      #   query parameters.
+      # time range. It enables filtering and grouping the output using
+      # [computed properties](/extensibility/advanced-metrics#computed-properties),
+      # supporting the following workflows:
+      #
+      # 1. Showing detailed usage and costs to the end customer.
+      # 2. Auditing subtotals on invoice line items.
+      #
+      # For these workflows, the expressiveness of computed properties in both the
+      # filters and grouping is critical. For example, if you'd like to show your
+      # customer their usage grouped by hour and another property, you can do so with
+      # the following `grouping_keys`:
+      # `["hour_floor_timestamp_millis(timestamp_millis)", "my_property"]`. If you'd
+      # like to examine a customer's usage for a specific property value, you can do so
+      # with the following `filter`:
+      # `my_property = 'foo' AND my_other_property = 'bar'`.
+      #
+      # By default, the start of the time range must be no more than 100 days ago and
+      # the length of the results must be no greater than 1000. Note that this is a POST
+      # endpoint rather than a GET endpoint because it employs a JSON body rather than
+      # query parameters.
       #
       # @overload evaluate(price_id, timeframe_end:, timeframe_start:, customer_id: nil, external_customer_id: nil, filter: nil, grouping_keys: nil, request_options: {})
       #

data/lib/orb/resources/subscription_changes.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Orb
+  module Resources
+    class SubscriptionChanges
+      # This endpoint returns a subscription change given an identifier.
+      #
+      # A subscription change is created by including
+      # `Create-Pending-Subscription-Change: True` in the header of a subscription
+      # mutation API call (e.g.
+      # [create subscription endpoint](/api-reference/subscription/create-subscription),
+      # [schedule plan change endpoint](/api-reference/subscription/schedule-plan-change),
+      # ...). The subscription change will be referenced by the
+      # `pending_subscription_change` field in the response.
+      #
+      # @overload retrieve(subscription_change_id, request_options: {})
+      #
+      # @param subscription_change_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::SubscriptionChangeRetrieveResponse]
+      #
+      # @see Orb::Models::SubscriptionChangeRetrieveParams
+      def retrieve(subscription_change_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["subscription_changes/%1$s", subscription_change_id],
+          model: Orb::Models::SubscriptionChangeRetrieveResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Apply a subscription change to perform the intended action. If a positive amount
+      # is passed with a request to this endpoint, any eligible invoices that were
+      # created will be issued immediately if they only contain in-advance fees.
+      #
+      # @overload apply(subscription_change_id, description: nil, previously_collected_amount: nil, request_options: {})
+      #
+      # @param subscription_change_id [String]
+      # @param description [String, nil]
+      # @param previously_collected_amount [String, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::SubscriptionChangeApplyResponse]
+      #
+      # @see Orb::Models::SubscriptionChangeApplyParams
+      def apply(subscription_change_id, params = {})
+        parsed, options = Orb::Models::SubscriptionChangeApplyParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["subscription_changes/%1$s/apply", subscription_change_id],
+          body: parsed,
+          model: Orb::Models::SubscriptionChangeApplyResponse,
+          options: options
+        )
+      end
+
+      # Cancel a subscription change. The change can no longer be applied. A
+      # subscription can only have one "pending" change at a time - use this endpoint to
+      # cancel an existing change before creating a new one.
+      #
+      # @overload cancel(subscription_change_id, request_options: {})
+      #
+      # @param subscription_change_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::SubscriptionChangeCancelResponse]
+      #
+      # @see Orb::Models::SubscriptionChangeCancelParams
+      def cancel(subscription_change_id, params = {})
+        @client.request(
+          method: :post,
+          path: ["subscription_changes/%1$s/cancel", subscription_change_id],
+          model: Orb::Models::SubscriptionChangeCancelResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Orb::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end