orb-billing 1.48.0 → 1.50.0

data/rbi/orb/models/webhooks/sales_order_accounting_sync_succeeded_standard_webhook_event.rbi

@@ -612,6 +612,18 @@ module Orb
           sig { returns(T.nilable(Time)) }
           attr_accessor :scheduled_issue_at
 
+          # The latest `end_date` of the invoice's line items, including any line items
+          # hidden because they have zero quantity. This is `null` when the invoice has no
+          # line items.
+          sig { returns(T.nilable(Time)) }
+          attr_accessor :service_period_end
+
+          # The earliest `start_date` of the invoice's line items, including any line items
+          # hidden because they have zero quantity. This is `null` when the invoice has no
+          # line items.
+          sig { returns(T.nilable(Time)) }
+          attr_accessor :service_period_start
+
           sig { returns(T.nilable(Orb::Address)) }
           attr_reader :shipping_address
 
@@ -697,6 +709,8 @@ module Orb
               payment_received_at: T.nilable(Time),
               payment_started_at: T.nilable(Time),
               scheduled_issue_at: T.nilable(Time),
+              service_period_end: T.nilable(Time),
+              service_period_start: T.nilable(Time),
               shipping_address: T.nilable(Orb::Address::OrHash),
               status:
                 Orb::Webhooks::SalesOrderAccountingSyncSucceededStandardWebhookEvent::Invoice::Status::OrSymbol,
@@ -927,6 +941,14 @@ module Orb
             # If the invoice is in draft, this timestamp will reflect when the invoice is
             # scheduled to be issued.
             scheduled_issue_at:,
+            # The latest `end_date` of the invoice's line items, including any line items
+            # hidden because they have zero quantity. This is `null` when the invoice has no
+            # line items.
+            service_period_end:,
+            # The earliest `start_date` of the invoice's line items, including any line items
+            # hidden because they have zero quantity. This is `null` when the invoice has no
+            # line items.
+            service_period_start:,
             shipping_address:,
             status:,
             subscription:,
@@ -986,6 +1008,8 @@ module Orb
                 payment_received_at: T.nilable(Time),
                 payment_started_at: T.nilable(Time),
                 scheduled_issue_at: T.nilable(Time),
+                service_period_end: T.nilable(Time),
+                service_period_start: T.nilable(Time),
                 shipping_address: T.nilable(Orb::Address),
                 status:
                   Orb::Webhooks::SalesOrderAccountingSyncSucceededStandardWebhookEvent::Invoice::Status::TaggedSymbol,

data/rbi/orb/models.rbi

@@ -813,6 +813,8 @@ module Orb
 
   SubscriptionListParams = Orb::Models::SubscriptionListParams
 
+  SubscriptionListSummaryParams = Orb::Models::SubscriptionListSummaryParams
+
   SubscriptionMinified = Orb::Models::SubscriptionMinified
 
   SubscriptionPlanChangedWebhookEvent =

data/rbi/orb/resources/alerts.rbi

@@ -187,8 +187,9 @@ module Orb
       # before invoice-level adjustments and credits) denominated in the alert's
       # currency exceeds predefined thresholds during the current billing cycle;
       # `price_filters` can scope which prices contribute. Each plan can have one
-      # `cost_exceeded` alert and one `usage_exceeded` alert per metric that is a part
-      # of the plan.
+      # `cost_exceeded` alert, one `usage_exceeded` alert per metric that is a part of
+      # the plan, and up to 50 `spend_exceeded` alerts, one per combination of currency
+      # and `price_filters`, so separate products can each have their own spend alert.
       sig do
         params(
           plan_id: String,
@@ -243,8 +244,10 @@ module Orb
       # spend (the pricing subtotal, before invoice-level adjustments and credits)
       # denominated in the alert's currency exceeds predefined thresholds during the
       # current billing cycle; `price_filters` can scope which prices contribute. Each
-      # subscription can have one `cost_exceeded` alert and one `usage_exceeded` alert
-      # per metric that is a part of the subscription.
+      # subscription can have one `cost_exceeded` alert, one `usage_exceeded` alert per
+      # metric that is a part of the subscription, and up to 50 `spend_exceeded` alerts,
+      # one per combination of currency and `price_filters`, so separate products can
+      # each have their own spend alert.
       sig do
         params(
           subscription_id: String,

data/rbi/orb/resources/customers/credits.rbi

@@ -64,6 +64,66 @@ module Orb
         )
         end
 
+        # This endpoint returns a customer's credit balance in a single currency or custom
+        # pricing unit: the total available balance, the balance waiting on payment, and
+        # the next upcoming expiration.
+        #
+        # `balance` is the sum of `balance` across the customer's `active` credit blocks,
+        # as listed by
+        # [Fetch customer credit balance](/api-reference/credit/fetch-customer-credit-balance).
+        # Expired, depleted, and voided blocks are not included. Blocks in
+        # `pending_payment` status are totaled in `pending_payment_balance` instead, and
+        # become available once their invoice is paid.
+        #
+        # Note that `currency` defaults to credits if not specified. To use a real world
+        # currency, set `currency` to an ISO 4217 string. A customer with no credits in
+        # that currency returns a balance of `0`.
+        sig do
+          params(
+            customer_id: String,
+            currency: T.nilable(String),
+            request_options: Orb::RequestOptions::OrHash
+          ).returns(Orb::Models::Customers::CreditFetchBalanceResponse)
+        end
+        def fetch_balance(
+          customer_id,
+          # The ledger currency or custom pricing unit to use.
+          currency: nil,
+          request_options: {}
+        )
+        end
+
+        # This endpoint returns a customer's credit balance in a single currency or custom
+        # pricing unit: the total available balance, the balance waiting on payment, and
+        # the next upcoming expiration.
+        #
+        # `balance` is the sum of `balance` across the customer's `active` credit blocks,
+        # as listed by
+        # [Fetch customer credit balance](/api-reference/credit/fetch-customer-credit-balance).
+        # Expired, depleted, and voided blocks are not included. Blocks in
+        # `pending_payment` status are totaled in `pending_payment_balance` instead, and
+        # become available once their invoice is paid.
+        #
+        # Note that `currency` defaults to credits if not specified. To use a real world
+        # currency, set `currency` to an ISO 4217 string. A customer with no credits in
+        # that currency returns a balance of `0`.
+        sig do
+          params(
+            external_customer_id: String,
+            currency: T.nilable(String),
+            request_options: Orb::RequestOptions::OrHash
+          ).returns(
+            Orb::Models::Customers::CreditFetchBalanceByExternalIDResponse
+          )
+        end
+        def fetch_balance_by_external_id(
+          external_customer_id,
+          # The ledger currency or custom pricing unit to use.
+          currency: nil,
+          request_options: {}
+        )
+        end
+
         # Returns a paginated list of unexpired, non-zero credit blocks for a customer.
         #
         # If `include_all_blocks` is set to `true`, all credit blocks (including expired

data/rbi/orb/resources/subscriptions.rbi

@@ -923,6 +923,53 @@ module Orb
       )
       end
 
+      # This is a lighter-weight version of
+      # [List subscriptions](/api-reference/subscription/list-subscriptions), with the
+      # same filters, pagination and order. It returns each subscription's own fields,
+      # with its plan and customer as references, and leaves out price intervals,
+      # billing periods, plan phases and other derived fields, making it faster to
+      # respond. Fetch a subscription for those.
+      #
+      # This is the same summary of a subscription that standard
+      # [webhook payloads](/integrations-and-exports/webhook-payload-styles) carry.
+      sig do
+        params(
+          created_at_gt: T.nilable(Time),
+          created_at_gte: T.nilable(Time),
+          created_at_lt: T.nilable(Time),
+          created_at_lte: T.nilable(Time),
+          cursor: T.nilable(String),
+          customer_id: T.nilable(String),
+          external_customer_id: T.nilable(String),
+          external_plan_id: T.nilable(String),
+          limit: Integer,
+          plan_id: T.nilable(String),
+          status:
+            T.nilable(Orb::SubscriptionListSummaryParams::Status::OrSymbol),
+          request_options: Orb::RequestOptions::OrHash
+        ).returns(
+          Orb::Internal::Page[Orb::Models::SubscriptionListSummaryResponse]
+        )
+      end
+      def list_summary(
+        created_at_gt: nil,
+        created_at_gte: nil,
+        created_at_lt: nil,
+        created_at_lte: nil,
+        # Cursor for pagination. This can be populated by the `next_cursor` value returned
+        # from the initial request.
+        cursor: nil,
+        customer_id: nil,
+        external_customer_id: nil,
+        external_plan_id: nil,
+        # The number of items to fetch. Defaults to 20.
+        limit: nil,
+        plan_id: nil,
+        status: nil,
+        request_options: {}
+      )
+      end
+
       # This endpoint is used to add and edit subscription
       # [price intervals](/api-reference/price-interval/add-or-edit-price-intervals). By
       # making modifications to a subscription’s price intervals, you can

data/sig/orb/models/changed_subscription_resources.rbs

@@ -69,6 +69,8 @@ module Orb
           payment_received_at: Time?,
           payment_started_at: Time?,
           scheduled_issue_at: Time?,
+          service_period_end: Time?,
+          service_period_start: Time?,
           shipping_address: Orb::Address?,
           status: Orb::Models::ChangedSubscriptionResources::CreatedInvoice::status,
           subscription: Orb::SubscriptionMinified?,
@@ -152,6 +154,10 @@ module Orb
 
         attr_accessor scheduled_issue_at: Time?
 
+        attr_accessor service_period_end: Time?
+
+        attr_accessor service_period_start: Time?
+
         attr_accessor shipping_address: Orb::Address?
 
         attr_accessor status: Orb::Models::ChangedSubscriptionResources::CreatedInvoice::status
@@ -205,6 +211,8 @@ module Orb
           payment_received_at: Time?,
           payment_started_at: Time?,
           scheduled_issue_at: Time?,
+          service_period_end: Time?,
+          service_period_start: Time?,
           shipping_address: Orb::Address?,
           status: Orb::Models::ChangedSubscriptionResources::CreatedInvoice::status,
           subscription: Orb::SubscriptionMinified?,
@@ -252,6 +260,8 @@ module Orb
           payment_received_at: Time?,
           payment_started_at: Time?,
           scheduled_issue_at: Time?,
+          service_period_end: Time?,
+          service_period_start: Time?,
           shipping_address: Orb::Address?,
           status: Orb::Models::ChangedSubscriptionResources::CreatedInvoice::status,
           subscription: Orb::SubscriptionMinified?,

data/sig/orb/models/customers/credit_fetch_balance_by_external_id_params.rbs

@@ -0,0 +1,30 @@
+module Orb
+  module Models
+    module Customers
+      type credit_fetch_balance_by_external_id_params =
+        { external_customer_id: String, currency: String? }
+        & Orb::Internal::Type::request_parameters
+
+      class CreditFetchBalanceByExternalIDParams < Orb::Internal::Type::BaseModel
+        extend Orb::Internal::Type::RequestParameters::Converter
+        include Orb::Internal::Type::RequestParameters
+
+        attr_accessor external_customer_id: String
+
+        attr_accessor currency: String?
+
+        def initialize: (
+          external_customer_id: String,
+          ?currency: String?,
+          ?request_options: Orb::request_opts
+        ) -> void
+
+        def to_hash: -> {
+          external_customer_id: String,
+          currency: String?,
+          request_options: Orb::RequestOptions
+        }
+      end
+    end
+  end
+end

data/sig/orb/models/customers/credit_fetch_balance_by_external_id_response.rbs

@@ -0,0 +1,42 @@
+module Orb
+  module Models
+    module Customers
+      type credit_fetch_balance_by_external_id_response =
+        {
+          balance: Float,
+          currency: String?,
+          next_expiry_balance: Float?,
+          next_expiry_date: Time?,
+          pending_payment_balance: Float
+        }
+
+      class CreditFetchBalanceByExternalIDResponse < Orb::Internal::Type::BaseModel
+        attr_accessor balance: Float
+
+        attr_accessor currency: String?
+
+        attr_accessor next_expiry_balance: Float?
+
+        attr_accessor next_expiry_date: Time?
+
+        attr_accessor pending_payment_balance: Float
+
+        def initialize: (
+          balance: Float,
+          currency: String?,
+          next_expiry_balance: Float?,
+          next_expiry_date: Time?,
+          pending_payment_balance: Float
+        ) -> void
+
+        def to_hash: -> {
+          balance: Float,
+          currency: String?,
+          next_expiry_balance: Float?,
+          next_expiry_date: Time?,
+          pending_payment_balance: Float
+        }
+      end
+    end
+  end
+end

data/sig/orb/models/customers/credit_fetch_balance_params.rbs

@@ -0,0 +1,30 @@
+module Orb
+  module Models
+    module Customers
+      type credit_fetch_balance_params =
+        { customer_id: String, currency: String? }
+        & Orb::Internal::Type::request_parameters
+
+      class CreditFetchBalanceParams < Orb::Internal::Type::BaseModel
+        extend Orb::Internal::Type::RequestParameters::Converter
+        include Orb::Internal::Type::RequestParameters
+
+        attr_accessor customer_id: String
+
+        attr_accessor currency: String?
+
+        def initialize: (
+          customer_id: String,
+          ?currency: String?,
+          ?request_options: Orb::request_opts
+        ) -> void
+
+        def to_hash: -> {
+          customer_id: String,
+          currency: String?,
+          request_options: Orb::RequestOptions
+        }
+      end
+    end
+  end
+end

data/sig/orb/models/customers/credit_fetch_balance_response.rbs

@@ -0,0 +1,42 @@
+module Orb
+  module Models
+    module Customers
+      type credit_fetch_balance_response =
+        {
+          balance: Float,
+          currency: String?,
+          next_expiry_balance: Float?,
+          next_expiry_date: Time?,
+          pending_payment_balance: Float
+        }
+
+      class CreditFetchBalanceResponse < Orb::Internal::Type::BaseModel
+        attr_accessor balance: Float
+
+        attr_accessor currency: String?
+
+        attr_accessor next_expiry_balance: Float?
+
+        attr_accessor next_expiry_date: Time?
+
+        attr_accessor pending_payment_balance: Float
+
+        def initialize: (
+          balance: Float,
+          currency: String?,
+          next_expiry_balance: Float?,
+          next_expiry_date: Time?,
+          pending_payment_balance: Float
+        ) -> void
+
+        def to_hash: -> {
+          balance: Float,
+          currency: String?,
+          next_expiry_balance: Float?,
+          next_expiry_date: Time?,
+          pending_payment_balance: Float
+        }
+      end
+    end
+  end
+end

data/sig/orb/models/invoice.rbs

@@ -37,6 +37,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::Invoice::status,
         subscription: Orb::SubscriptionMinified?,
@@ -118,6 +120,10 @@ module Orb
 
       attr_accessor scheduled_issue_at: Time?
 
+      attr_accessor service_period_end: Time?
+
+      attr_accessor service_period_start: Time?
+
       attr_accessor shipping_address: Orb::Address?
 
       attr_accessor status: Orb::Models::Invoice::status
@@ -170,6 +176,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::Invoice::status,
         subscription: Orb::SubscriptionMinified?,
@@ -216,6 +224,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::Invoice::status,
         subscription: Orb::SubscriptionMinified?,

data/sig/orb/models/invoice_fetch_upcoming_response.rbs

@@ -36,6 +36,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::InvoiceFetchUpcomingResponse::status,
         subscription: Orb::SubscriptionMinified?,
@@ -116,6 +118,10 @@ module Orb
 
       attr_accessor scheduled_issue_at: Time?
 
+      attr_accessor service_period_end: Time?
+
+      attr_accessor service_period_start: Time?
+
       attr_accessor shipping_address: Orb::Address?
 
       attr_accessor status: Orb::Models::InvoiceFetchUpcomingResponse::status
@@ -169,6 +175,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::InvoiceFetchUpcomingResponse::status,
         subscription: Orb::SubscriptionMinified?,
@@ -215,6 +223,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::InvoiceFetchUpcomingResponse::status,
         subscription: Orb::SubscriptionMinified?,

data/sig/orb/models/invoice_issue_summary_response.rbs

@@ -29,6 +29,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::InvoiceIssueSummaryResponse::status,
         subscription: Orb::SubscriptionMinified?,
@@ -93,6 +95,10 @@ module Orb
 
       attr_accessor scheduled_issue_at: Time?
 
+      attr_accessor service_period_end: Time?
+
+      attr_accessor service_period_start: Time?
+
       attr_accessor shipping_address: Orb::Address?
 
       attr_accessor status: Orb::Models::InvoiceIssueSummaryResponse::status
@@ -135,6 +141,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::InvoiceIssueSummaryResponse::status,
         subscription: Orb::SubscriptionMinified?,
@@ -172,6 +180,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::InvoiceIssueSummaryResponse::status,
         subscription: Orb::SubscriptionMinified?,

data/sig/orb/models/invoice_issued_summary_webhook_event.rbs

@@ -70,6 +70,8 @@ module Orb
           payment_received_at: Time?,
           payment_started_at: Time?,
           scheduled_issue_at: Time?,
+          service_period_end: Time?,
+          service_period_start: Time?,
           shipping_address: Orb::Address?,
           status: Orb::Models::InvoiceIssuedSummaryWebhookEvent::Invoice::status,
           subscription: Orb::SubscriptionMinified?,
@@ -134,6 +136,10 @@ module Orb
 
         attr_accessor scheduled_issue_at: Time?
 
+        attr_accessor service_period_end: Time?
+
+        attr_accessor service_period_start: Time?
+
         attr_accessor shipping_address: Orb::Address?
 
         attr_accessor status: Orb::Models::InvoiceIssuedSummaryWebhookEvent::Invoice::status
@@ -176,6 +182,8 @@ module Orb
           payment_received_at: Time?,
           payment_started_at: Time?,
           scheduled_issue_at: Time?,
+          service_period_end: Time?,
+          service_period_start: Time?,
           shipping_address: Orb::Address?,
           status: Orb::Models::InvoiceIssuedSummaryWebhookEvent::Invoice::status,
           subscription: Orb::SubscriptionMinified?,
@@ -213,6 +221,8 @@ module Orb
           payment_received_at: Time?,
           payment_started_at: Time?,
           scheduled_issue_at: Time?,
+          service_period_end: Time?,
+          service_period_start: Time?,
           shipping_address: Orb::Address?,
           status: Orb::Models::InvoiceIssuedSummaryWebhookEvent::Invoice::status,
           subscription: Orb::SubscriptionMinified?,

data/sig/orb/models/invoice_list_summary_response.rbs

@@ -29,6 +29,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::InvoiceListSummaryResponse::status,
         subscription: Orb::SubscriptionMinified?,
@@ -93,6 +95,10 @@ module Orb
 
       attr_accessor scheduled_issue_at: Time?
 
+      attr_accessor service_period_end: Time?
+
+      attr_accessor service_period_start: Time?
+
       attr_accessor shipping_address: Orb::Address?
 
       attr_accessor status: Orb::Models::InvoiceListSummaryResponse::status
@@ -135,6 +141,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::InvoiceListSummaryResponse::status,
         subscription: Orb::SubscriptionMinified?,
@@ -172,6 +180,8 @@ module Orb
         payment_received_at: Time?,
         payment_started_at: Time?,
         scheduled_issue_at: Time?,
+        service_period_end: Time?,
+        service_period_start: Time?,
         shipping_address: Orb::Address?,
         status: Orb::Models::InvoiceListSummaryResponse::status,
         subscription: Orb::SubscriptionMinified?,

data/sig/orb/models/subscription_list_summary_params.rbs

@@ -0,0 +1,90 @@
+module Orb
+  module Models
+    type subscription_list_summary_params =
+      {
+        created_at_gt: Time?,
+        created_at_gte: Time?,
+        created_at_lt: Time?,
+        created_at_lte: Time?,
+        cursor: String?,
+        customer_id: String?,
+        external_customer_id: String?,
+        external_plan_id: String?,
+        limit: Integer,
+        plan_id: String?,
+        status: Orb::Models::SubscriptionListSummaryParams::status?
+      }
+      & Orb::Internal::Type::request_parameters
+
+    class SubscriptionListSummaryParams < Orb::Internal::Type::BaseModel
+      extend Orb::Internal::Type::RequestParameters::Converter
+      include Orb::Internal::Type::RequestParameters
+
+      attr_accessor created_at_gt: Time?
+
+      attr_accessor created_at_gte: Time?
+
+      attr_accessor created_at_lt: Time?
+
+      attr_accessor created_at_lte: Time?
+
+      attr_accessor cursor: String?
+
+      attr_accessor customer_id: String?
+
+      attr_accessor external_customer_id: String?
+
+      attr_accessor external_plan_id: String?
+
+      attr_reader limit: Integer?
+
+      def limit=: (Integer) -> Integer
+
+      attr_accessor plan_id: String?
+
+      attr_accessor status: Orb::Models::SubscriptionListSummaryParams::status?
+
+      def initialize: (
+        ?created_at_gt: Time?,
+        ?created_at_gte: Time?,
+        ?created_at_lt: Time?,
+        ?created_at_lte: Time?,
+        ?cursor: String?,
+        ?customer_id: String?,
+        ?external_customer_id: String?,
+        ?external_plan_id: String?,
+        ?limit: Integer,
+        ?plan_id: String?,
+        ?status: Orb::Models::SubscriptionListSummaryParams::status?,
+        ?request_options: Orb::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        created_at_gt: Time?,
+        created_at_gte: Time?,
+        created_at_lt: Time?,
+        created_at_lte: Time?,
+        cursor: String?,
+        customer_id: String?,
+        external_customer_id: String?,
+        external_plan_id: String?,
+        limit: Integer,
+        plan_id: String?,
+        status: Orb::Models::SubscriptionListSummaryParams::status?,
+        request_options: Orb::RequestOptions
+      }
+
+      type status = :active | :ended | :upcoming
+
+      module Status
+        extend Orb::Internal::Type::Enum
+
+        ACTIVE: :active
+        ENDED: :ended
+        UPCOMING: :upcoming
+
+        def self?.values: -> ::Array[Orb::Models::SubscriptionListSummaryParams::status]
+      end
+    end
+  end
+end