orb-billing 0.1.0.pre.alpha.33

data/lib/orb/resources/alerts.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Orb
+  module Resources
+    class Alerts
+      # This endpoint retrieves an alert by its ID.
+      #
+      # @overload retrieve(alert_id, request_options: {})
+      #
+      # @param alert_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Alert]
+      #
+      # @see Orb::Models::AlertRetrieveParams
+      def retrieve(alert_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["alerts/%1$s", alert_id],
+          model: Orb::Models::Alert,
+          options: params[:request_options]
+        )
+      end
+
+      # This endpoint updates the thresholds of an alert.
+      #
+      # @overload update(alert_configuration_id, thresholds:, request_options: {})
+      #
+      # @param alert_configuration_id [String]
+      # @param thresholds [Array<Orb::Models::AlertUpdateParams::Threshold>]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Alert]
+      #
+      # @see Orb::Models::AlertUpdateParams
+      def update(alert_configuration_id, params)
+        parsed, options = Orb::Models::AlertUpdateParams.dump_request(params)
+        @client.request(
+          method: :put,
+          path: ["alerts/%1$s", alert_configuration_id],
+          body: parsed,
+          model: Orb::Models::Alert,
+          options: options
+        )
+      end
+
+      # This endpoint returns a list of alerts within Orb.
+      #
+      #   The request must specify one of `customer_id`, `external_customer_id`, or
+      #   `subscription_id`.
+      #
+      #   If querying by subscripion_id, the endpoint will return the subscription level
+      #   alerts as well as the plan level alerts associated with the subscription.
+      #
+      #   The list of alerts is ordered starting from the most recently created alert.
+      #   This endpoint follows Orb's
+      #   [standardized pagination format](/api-reference/pagination).
+      #
+      # @overload list(created_at_gt: nil, created_at_gte: nil, created_at_lt: nil, created_at_lte: nil, cursor: nil, customer_id: nil, external_customer_id: nil, limit: nil, subscription_id: nil, request_options: {})
+      #
+      # @param created_at_gt [Time, nil]
+      # @param created_at_gte [Time, nil]
+      # @param created_at_lt [Time, nil]
+      # @param created_at_lte [Time, nil]
+      # @param cursor [String, nil]
+      # @param customer_id [String, nil]
+      # @param external_customer_id [String, nil]
+      # @param limit [Integer]
+      # @param subscription_id [String, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Page<Orb::Models::Alert>]
+      #
+      # @see Orb::Models::AlertListParams
+      def list(params = {})
+        parsed, options = Orb::Models::AlertListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "alerts",
+          query: parsed,
+          page: Orb::Page,
+          model: Orb::Models::Alert,
+          options: options
+        )
+      end
+
+      # This endpoint creates a new alert to monitor a customer's credit balance. There
+      #   are three types of alerts that can be scoped to customers:
+      #   `credit_balance_depleted`, `credit_balance_dropped`, and
+      #   `credit_balance_recovered`. Customers can have a maximum of one of each type of
+      #   alert per [credit balance currency](/product-catalog/prepurchase).
+      #   `credit_balance_dropped` alerts require a list of thresholds to be provided
+      #   while `credit_balance_depleted` and `credit_balance_recovered` alerts do not
+      #   require thresholds.
+      #
+      # @overload create_for_customer(customer_id, currency:, type:, thresholds: nil, request_options: {})
+      #
+      # @param customer_id [String]
+      # @param currency [String]
+      # @param type [Symbol, Orb::Models::AlertCreateForCustomerParams::Type]
+      # @param thresholds [Array<Orb::Models::AlertCreateForCustomerParams::Threshold>, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Alert]
+      #
+      # @see Orb::Models::AlertCreateForCustomerParams
+      def create_for_customer(customer_id, params)
+        parsed, options = Orb::Models::AlertCreateForCustomerParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["alerts/customer_id/%1$s", customer_id],
+          body: parsed,
+          model: Orb::Models::Alert,
+          options: options
+        )
+      end
+
+      # This endpoint creates a new alert to monitor a customer's credit balance. There
+      #   are three types of alerts that can be scoped to customers:
+      #   `credit_balance_depleted`, `credit_balance_dropped`, and
+      #   `credit_balance_recovered`. Customers can have a maximum of one of each type of
+      #   alert per [credit balance currency](/product-catalog/prepurchase).
+      #   `credit_balance_dropped` alerts require a list of thresholds to be provided
+      #   while `credit_balance_depleted` and `credit_balance_recovered` alerts do not
+      #   require thresholds.
+      #
+      # @overload create_for_external_customer(external_customer_id, currency:, type:, thresholds: nil, request_options: {})
+      #
+      # @param external_customer_id [String]
+      # @param currency [String]
+      # @param type [Symbol, Orb::Models::AlertCreateForExternalCustomerParams::Type]
+      # @param thresholds [Array<Orb::Models::AlertCreateForExternalCustomerParams::Threshold>, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Alert]
+      #
+      # @see Orb::Models::AlertCreateForExternalCustomerParams
+      def create_for_external_customer(external_customer_id, params)
+        parsed, options = Orb::Models::AlertCreateForExternalCustomerParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["alerts/external_customer_id/%1$s", external_customer_id],
+          body: parsed,
+          model: Orb::Models::Alert,
+          options: options
+        )
+      end
+
+      # This endpoint is used to create alerts at the subscription level.
+      #
+      #   Subscription level alerts can be one of two types: `usage_exceeded` or
+      #   `cost_exceeded`. A `usage_exceeded` alert is scoped to a particular metric and
+      #   is triggered when the usage of that metric exceeds predefined thresholds during
+      #   the current billing cycle. A `cost_exceeded` alert is triggered when the total
+      #   amount due during the current billing cycle surpasses predefined thresholds.
+      #   `cost_exceeded` alerts do not include burndown of pre-purchase credits. Each
+      #   subscription can have one `cost_exceeded` alert and one `usage_exceeded` alert
+      #   per metric that is a part of the subscription. Alerts are triggered based on
+      #   usage or cost conditions met during the current billing cycle.
+      #
+      # @overload create_for_subscription(subscription_id, thresholds:, type:, metric_id: nil, request_options: {})
+      #
+      # @param subscription_id [String]
+      # @param thresholds [Array<Orb::Models::AlertCreateForSubscriptionParams::Threshold>]
+      # @param type [Symbol, Orb::Models::AlertCreateForSubscriptionParams::Type]
+      # @param metric_id [String, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Alert]
+      #
+      # @see Orb::Models::AlertCreateForSubscriptionParams
+      def create_for_subscription(subscription_id, params)
+        parsed, options = Orb::Models::AlertCreateForSubscriptionParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["alerts/subscription_id/%1$s", subscription_id],
+          body: parsed,
+          model: Orb::Models::Alert,
+          options: options
+        )
+      end
+
+      # This endpoint allows you to disable an alert. To disable a plan-level alert for
+      #   a specific subscription, you must include the `subscription_id`. The
+      #   `subscription_id` is not required for customer or subscription level alerts.
+      #
+      # @overload disable(alert_configuration_id, subscription_id: nil, request_options: {})
+      #
+      # @param alert_configuration_id [String]
+      # @param subscription_id [String, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Alert]
+      #
+      # @see Orb::Models::AlertDisableParams
+      def disable(alert_configuration_id, params = {})
+        parsed, options = Orb::Models::AlertDisableParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["alerts/%1$s/disable", alert_configuration_id],
+          query: parsed,
+          model: Orb::Models::Alert,
+          options: options
+        )
+      end
+
+      # This endpoint allows you to enable an alert. To enable a plan-level alert for a
+      #   specific subscription, you must include the `subscription_id`. The
+      #   `subscription_id` is not required for customer or subscription level alerts.
+      #
+      # @overload enable(alert_configuration_id, subscription_id: nil, request_options: {})
+      #
+      # @param alert_configuration_id [String]
+      # @param subscription_id [String, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Alert]
+      #
+      # @see Orb::Models::AlertEnableParams
+      def enable(alert_configuration_id, params = {})
+        parsed, options = Orb::Models::AlertEnableParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["alerts/%1$s/enable", alert_configuration_id],
+          query: parsed,
+          model: Orb::Models::Alert,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Orb::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/orb/resources/coupons/subscriptions.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Orb
+  module Resources
+    class Coupons
+      class Subscriptions
+        # This endpoint returns a list of all subscriptions that have redeemed a given
+        #   coupon as a [paginated](/api-reference/pagination) list, ordered starting from
+        #   the most recently created subscription. For a full discussion of the
+        #   subscription resource, see [Subscription](/core-concepts#subscription).
+        #
+        # @overload list(coupon_id, cursor: nil, limit: nil, request_options: {})
+        #
+        # @param coupon_id [String]
+        # @param cursor [String, nil]
+        # @param limit [Integer]
+        # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Orb::Page<Orb::Models::Subscription>]
+        #
+        # @see Orb::Models::Coupons::SubscriptionListParams
+        def list(coupon_id, params = {})
+          parsed, options = Orb::Models::Coupons::SubscriptionListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["coupons/%1$s/subscriptions", coupon_id],
+            query: parsed,
+            page: Orb::Page,
+            model: Orb::Models::Subscription,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Orb::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/orb/resources/coupons.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Orb
+  module Resources
+    class Coupons
+      # @return [Orb::Resources::Coupons::Subscriptions]
+      attr_reader :subscriptions
+
+      # This endpoint allows the creation of coupons, which can then be redeemed at
+      #   subscription creation or plan change.
+      #
+      # @overload create(discount:, redemption_code:, duration_in_months: nil, max_redemptions: nil, request_options: {})
+      #
+      # @param discount [Orb::Models::CouponCreateParams::Discount::NewCouponPercentageDiscount, Orb::Models::CouponCreateParams::Discount::NewCouponAmountDiscount]
+      # @param redemption_code [String]
+      # @param duration_in_months [Integer, nil]
+      # @param max_redemptions [Integer, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Coupon]
+      #
+      # @see Orb::Models::CouponCreateParams
+      def create(params)
+        parsed, options = Orb::Models::CouponCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "coupons",
+          body: parsed,
+          model: Orb::Models::Coupon,
+          options: options
+        )
+      end
+
+      # This endpoint returns a list of all coupons for an account in a list format.
+      #
+      #   The list of coupons is ordered starting from the most recently created coupon.
+      #   The response also includes `pagination_metadata`, which lets the caller retrieve
+      #   the next page of results if they exist. More information about pagination can be
+      #   found in the Pagination-metadata schema.
+      #
+      # @overload list(cursor: nil, limit: nil, redemption_code: nil, show_archived: nil, request_options: {})
+      #
+      # @param cursor [String, nil]
+      # @param limit [Integer]
+      # @param redemption_code [String, nil]
+      # @param show_archived [Boolean, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Page<Orb::Models::Coupon>]
+      #
+      # @see Orb::Models::CouponListParams
+      def list(params = {})
+        parsed, options = Orb::Models::CouponListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "coupons",
+          query: parsed,
+          page: Orb::Page,
+          model: Orb::Models::Coupon,
+          options: options
+        )
+      end
+
+      # This endpoint allows a coupon to be archived. Archived coupons can no longer be
+      #   redeemed, and will be hidden from lists of active coupons. Additionally, once a
+      #   coupon is archived, its redemption code can be reused for a different coupon.
+      #
+      # @overload archive(coupon_id, request_options: {})
+      #
+      # @param coupon_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Coupon]
+      #
+      # @see Orb::Models::CouponArchiveParams
+      def archive(coupon_id, params = {})
+        @client.request(
+          method: :post,
+          path: ["coupons/%1$s/archive", coupon_id],
+          model: Orb::Models::Coupon,
+          options: params[:request_options]
+        )
+      end
+
+      # This endpoint retrieves a coupon by its ID. To fetch coupons by their redemption
+      #   code, use the [List coupons](list-coupons) endpoint with the redemption_code
+      #   parameter.
+      #
+      # @overload fetch(coupon_id, request_options: {})
+      #
+      # @param coupon_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::Coupon]
+      #
+      # @see Orb::Models::CouponFetchParams
+      def fetch(coupon_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["coupons/%1$s", coupon_id],
+          model: Orb::Models::Coupon,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Orb::Client]
+      def initialize(client:)
+        @client = client
+        @subscriptions = Orb::Resources::Coupons::Subscriptions.new(client: client)
+      end
+    end
+  end
+end

data/lib/orb/resources/credit_notes.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Orb
+  module Resources
+    class CreditNotes
+      # This endpoint is used to create a single
+      #   [`Credit Note`](/invoicing/credit-notes).
+      #
+      # @overload create(line_items:, memo: nil, reason: nil, request_options: {})
+      #
+      # @param line_items [Array<Orb::Models::CreditNoteCreateParams::LineItem>]
+      # @param memo [String, nil]
+      # @param reason [Symbol, Orb::Models::CreditNoteCreateParams::Reason, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::CreditNote]
+      #
+      # @see Orb::Models::CreditNoteCreateParams
+      def create(params)
+        parsed, options = Orb::Models::CreditNoteCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "credit_notes",
+          body: parsed,
+          model: Orb::Models::CreditNote,
+          options: options
+        )
+      end
+
+      # Get a paginated list of CreditNotes. Users can also filter by customer_id,
+      #   subscription_id, or external_customer_id. The credit notes will be returned in
+      #   reverse chronological order by `creation_time`.
+      #
+      # @overload list(created_at_gt: nil, created_at_gte: nil, created_at_lt: nil, created_at_lte: nil, cursor: nil, limit: nil, request_options: {})
+      #
+      # @param created_at_gt [Time, nil]
+      # @param created_at_gte [Time, nil]
+      # @param created_at_lt [Time, nil]
+      # @param created_at_lte [Time, nil]
+      # @param cursor [String, nil]
+      # @param limit [Integer]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Page<Orb::Models::CreditNote>]
+      #
+      # @see Orb::Models::CreditNoteListParams
+      def list(params = {})
+        parsed, options = Orb::Models::CreditNoteListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "credit_notes",
+          query: parsed,
+          page: Orb::Page,
+          model: Orb::Models::CreditNote,
+          options: options
+        )
+      end
+
+      # This endpoint is used to fetch a single [`Credit Note`](/invoicing/credit-notes)
+      #   given an identifier.
+      #
+      # @overload fetch(credit_note_id, request_options: {})
+      #
+      # @param credit_note_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Orb::Models::CreditNote]
+      #
+      # @see Orb::Models::CreditNoteFetchParams
+      def fetch(credit_note_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["credit_notes/%1$s", credit_note_id],
+          model: Orb::Models::CreditNote,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Orb::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/orb/resources/customers/balance_transactions.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Orb
+  module Resources
+    class Customers
+      class BalanceTransactions
+        # Creates an immutable balance transaction that updates the customer's balance and
+        #   returns back the newly created transaction.
+        #
+        # @overload create(customer_id, amount:, type:, description: nil, request_options: {})
+        #
+        # @param customer_id [String]
+        # @param amount [String]
+        # @param type [Symbol, Orb::Models::Customers::BalanceTransactionCreateParams::Type]
+        # @param description [String, nil]
+        # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Orb::Models::Customers::BalanceTransactionCreateResponse]
+        #
+        # @see Orb::Models::Customers::BalanceTransactionCreateParams
+        def create(customer_id, params)
+          parsed, options = Orb::Models::Customers::BalanceTransactionCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["customers/%1$s/balance_transactions", customer_id],
+            body: parsed,
+            model: Orb::Models::Customers::BalanceTransactionCreateResponse,
+            options: options
+          )
+        end
+
+        # ## The customer balance
+        #
+        #   The customer balance is an amount in the customer's currency, which Orb
+        #   automatically applies to subsequent invoices. This balance can be adjusted
+        #   manually via Orb's webapp on the customer details page. You can use this balance
+        #   to provide a fixed mid-period credit to the customer. Commonly, this is done due
+        #   to system downtime/SLA violation, or an adhoc adjustment discussed with the
+        #   customer.
+        #
+        #   If the balance is a positive value at the time of invoicing, it represents that
+        #   the customer has credit that should be used to offset the amount due on the next
+        #   issued invoice. In this case, Orb will automatically reduce the next invoice by
+        #   the balance amount, and roll over any remaining balance if the invoice is fully
+        #   discounted.
+        #
+        #   If the balance is a negative value at the time of invoicing, Orb will increase
+        #   the invoice's amount due with a positive adjustment, and reset the balance to 0.
+        #
+        #   This endpoint retrieves all customer balance transactions in reverse
+        #   chronological order for a single customer, providing a complete audit trail of
+        #   all adjustments and invoice applications.
+        #
+        #   ## Eligibility
+        #
+        #   The customer balance can only be applied to invoices or adjusted manually if
+        #   invoices are not synced to a separate invoicing provider. If a payment gateway
+        #   such as Stripe is used, the balance will be applied to the invoice before
+        #   forwarding payment to the gateway.
+        #
+        # @overload list(customer_id, cursor: nil, limit: nil, operation_time_gt: nil, operation_time_gte: nil, operation_time_lt: nil, operation_time_lte: nil, request_options: {})
+        #
+        # @param customer_id [String]
+        # @param cursor [String, nil]
+        # @param limit [Integer]
+        # @param operation_time_gt [Time, nil]
+        # @param operation_time_gte [Time, nil]
+        # @param operation_time_lt [Time, nil]
+        # @param operation_time_lte [Time, nil]
+        # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Orb::Page<Orb::Models::Customers::BalanceTransactionListResponse>]
+        #
+        # @see Orb::Models::Customers::BalanceTransactionListParams
+        def list(customer_id, params = {})
+          parsed, options = Orb::Models::Customers::BalanceTransactionListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["customers/%1$s/balance_transactions", customer_id],
+            query: parsed,
+            page: Orb::Page,
+            model: Orb::Models::Customers::BalanceTransactionListResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Orb::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end