orb-billing 1.13.0 → 1.15.0

data/rbi/orb/resources/customers.rbi

@@ -225,11 +225,13 @@ module Orb
         # | Estonia                | `eu_vat`     | European VAT Number                                                                                     |
         # | Ethiopia               | `et_tin`     | Ethiopia Tax Identification Number                                                                      |
         # | European Union         | `eu_oss_vat` | European One Stop Shop VAT Number for non-Union scheme                                                  |
+        # | Faroe Islands          | `fo_vat`     | Faroe Islands VAT Number                                                                                |
         # | Finland                | `eu_vat`     | European VAT Number                                                                                     |
         # | France                 | `eu_vat`     | European VAT Number                                                                                     |
         # | Georgia                | `ge_vat`     | Georgian VAT                                                                                            |
         # | Germany                | `de_stn`     | German Tax Number (Steuernummer)                                                                        |
         # | Germany                | `eu_vat`     | European VAT Number                                                                                     |
+        # | Gibraltar              | `gi_tin`     | Gibraltar Tax Identification Number                                                                     |
         # | Greece                 | `eu_vat`     | European VAT Number                                                                                     |
         # | Guinea                 | `gn_nif`     | Guinea Tax Identification Number (Número de Identificação Fiscal)                                       |
         # | Hong Kong              | `hk_br`      | Hong Kong BR Number                                                                                     |
@@ -241,6 +243,7 @@ module Orb
         # | Ireland                | `eu_vat`     | European VAT Number                                                                                     |
         # | Israel                 | `il_vat`     | Israel VAT                                                                                              |
         # | Italy                  | `eu_vat`     | European VAT Number                                                                                     |
+        # | Italy                  | `it_cf`      | Italian Codice Fiscale Number                                                                           |
         # | Japan                  | `jp_cn`      | Japanese Corporate Number (_Hōjin Bangō_)                                                               |
         # | Japan                  | `jp_rn`      | Japanese Registered Foreign Businesses' Registration Number (_Tōroku Kokugai Jigyōsha no Tōroku Bangō_) |
         # | Japan                  | `jp_trn`     | Japanese Tax Registration Number (_Tōroku Bangō_)                                                       |
@@ -271,6 +274,7 @@ module Orb
         # | Norway                 | `no_vat`     | Norwegian VAT Number                                                                                    |
         # | Norway                 | `no_voec`    | Norwegian VAT on e-commerce Number                                                                      |
         # | Oman                   | `om_vat`     | Omani VAT Number                                                                                        |
+        # | Paraguay               | `py_ruc`     | Paraguayan RUC Number                                                                                   |
         # | Peru                   | `pe_ruc`     | Peruvian RUC Number                                                                                     |
         # | Philippines            | `ph_tin`     | Philippines Tax Identification Number                                                                   |
         # | Poland                 | `eu_vat`     | European VAT Number                                                                                     |
@@ -292,6 +296,7 @@ module Orb
         # | South Korea            | `kr_brn`     | Korean BRN                                                                                              |
         # | Spain                  | `es_cif`     | Spanish NIF Number (previously Spanish CIF Number)                                                      |
         # | Spain                  | `eu_vat`     | European VAT Number                                                                                     |
+        # | Sri Lanka              | `lk_vat`     | Sri Lanka VAT Number                                                                                    |
         # | Suriname               | `sr_fin`     | Suriname FIN Number                                                                                     |
         # | Sweden                 | `eu_vat`     | European VAT Number                                                                                     |
         # | Switzerland            | `ch_uid`     | Switzerland UID Number                                                                                  |
@@ -324,9 +329,10 @@ module Orb
 
       # This endpoint can be used to update the `payment_provider`,
       # `payment_provider_id`, `name`, `email`, `email_delivery`, `tax_id`,
-      # `auto_collection`, `metadata`, `shipping_address`, `billing_address`, and
-      # `additional_emails` of an existing customer. Other fields on a customer are
-      # currently immutable.
+      # `auto_collection`, `metadata`, `shipping_address`, `billing_address`,
+      # `additional_emails`, and `currency` of an existing customer. `currency` can only
+      # be set if it has not already been set on the customer. Other fields on a
+      # customer are currently immutable.
       sig do
         params(
           customer_id: String,
@@ -337,6 +343,7 @@ module Orb
           auto_issuance: T.nilable(T::Boolean),
           billing_address: T.nilable(Orb::AddressInput::OrHash),
           currency: T.nilable(String),
+          default_payment_method_id: T.nilable(String),
           email: T.nilable(String),
           email_delivery: T.nilable(T::Boolean),
           external_customer_id: T.nilable(String),
@@ -383,9 +390,14 @@ module Orb
         # will be inherited from the account-level setting.
         auto_issuance: nil,
         billing_address: nil,
-        # An ISO 4217 currency string used for the customer's invoices and balance. If not
-        # set at creation time, will be set at subscription creation time.
+        # An ISO 4217 currency string used for the customer's invoices and balance. This
+        # can only be set if the customer does not already have a currency configured. If
+        # not set at creation or update time, it will be set at subscription creation
+        # time.
         currency: nil,
+        # The Orb ID of the payment method to set as this customer's default. Pass `null`
+        # to clear the customer's default payment method.
+        default_payment_method_id: nil,
         # A valid customer email, to be used for invoicing and notifications.
         email: nil,
         email_delivery: nil,
@@ -477,11 +489,13 @@ module Orb
         # | Estonia                | `eu_vat`     | European VAT Number                                                                                     |
         # | Ethiopia               | `et_tin`     | Ethiopia Tax Identification Number                                                                      |
         # | European Union         | `eu_oss_vat` | European One Stop Shop VAT Number for non-Union scheme                                                  |
+        # | Faroe Islands          | `fo_vat`     | Faroe Islands VAT Number                                                                                |
         # | Finland                | `eu_vat`     | European VAT Number                                                                                     |
         # | France                 | `eu_vat`     | European VAT Number                                                                                     |
         # | Georgia                | `ge_vat`     | Georgian VAT                                                                                            |
         # | Germany                | `de_stn`     | German Tax Number (Steuernummer)                                                                        |
         # | Germany                | `eu_vat`     | European VAT Number                                                                                     |
+        # | Gibraltar              | `gi_tin`     | Gibraltar Tax Identification Number                                                                     |
         # | Greece                 | `eu_vat`     | European VAT Number                                                                                     |
         # | Guinea                 | `gn_nif`     | Guinea Tax Identification Number (Número de Identificação Fiscal)                                       |
         # | Hong Kong              | `hk_br`      | Hong Kong BR Number                                                                                     |
@@ -493,6 +507,7 @@ module Orb
         # | Ireland                | `eu_vat`     | European VAT Number                                                                                     |
         # | Israel                 | `il_vat`     | Israel VAT                                                                                              |
         # | Italy                  | `eu_vat`     | European VAT Number                                                                                     |
+        # | Italy                  | `it_cf`      | Italian Codice Fiscale Number                                                                           |
         # | Japan                  | `jp_cn`      | Japanese Corporate Number (_Hōjin Bangō_)                                                               |
         # | Japan                  | `jp_rn`      | Japanese Registered Foreign Businesses' Registration Number (_Tōroku Kokugai Jigyōsha no Tōroku Bangō_) |
         # | Japan                  | `jp_trn`     | Japanese Tax Registration Number (_Tōroku Bangō_)                                                       |
@@ -523,6 +538,7 @@ module Orb
         # | Norway                 | `no_vat`     | Norwegian VAT Number                                                                                    |
         # | Norway                 | `no_voec`    | Norwegian VAT on e-commerce Number                                                                      |
         # | Oman                   | `om_vat`     | Omani VAT Number                                                                                        |
+        # | Paraguay               | `py_ruc`     | Paraguayan RUC Number                                                                                   |
         # | Peru                   | `pe_ruc`     | Peruvian RUC Number                                                                                     |
         # | Philippines            | `ph_tin`     | Philippines Tax Identification Number                                                                   |
         # | Poland                 | `eu_vat`     | European VAT Number                                                                                     |
@@ -544,6 +560,7 @@ module Orb
         # | South Korea            | `kr_brn`     | Korean BRN                                                                                              |
         # | Spain                  | `es_cif`     | Spanish NIF Number (previously Spanish CIF Number)                                                      |
         # | Spain                  | `eu_vat`     | European VAT Number                                                                                     |
+        # | Sri Lanka              | `lk_vat`     | Sri Lanka VAT Number                                                                                    |
         # | Suriname               | `sr_fin`     | Suriname FIN Number                                                                                     |
         # | Sweden                 | `eu_vat`     | European VAT Number                                                                                     |
         # | Switzerland            | `ch_uid`     | Switzerland UID Number                                                                                  |
@@ -698,6 +715,7 @@ module Orb
           auto_issuance: T.nilable(T::Boolean),
           billing_address: T.nilable(Orb::AddressInput::OrHash),
           currency: T.nilable(String),
+          default_payment_method_id: T.nilable(String),
           email: T.nilable(String),
           email_delivery: T.nilable(T::Boolean),
           external_customer_id: T.nilable(String),
@@ -748,9 +766,14 @@ module Orb
         # will be inherited from the account-level setting.
         auto_issuance: nil,
         billing_address: nil,
-        # An ISO 4217 currency string used for the customer's invoices and balance. If not
-        # set at creation time, will be set at subscription creation time.
+        # An ISO 4217 currency string used for the customer's invoices and balance. This
+        # can only be set if the customer does not already have a currency configured. If
+        # not set at creation or update time, it will be set at subscription creation
+        # time.
         currency: nil,
+        # The Orb ID of the payment method to set as this customer's default. Pass `null`
+        # to clear the customer's default payment method.
+        default_payment_method_id: nil,
         # A valid customer email, to be used for invoicing and notifications.
         email: nil,
         email_delivery: nil,
@@ -842,11 +865,13 @@ module Orb
         # | Estonia                | `eu_vat`     | European VAT Number                                                                                     |
         # | Ethiopia               | `et_tin`     | Ethiopia Tax Identification Number                                                                      |
         # | European Union         | `eu_oss_vat` | European One Stop Shop VAT Number for non-Union scheme                                                  |
+        # | Faroe Islands          | `fo_vat`     | Faroe Islands VAT Number                                                                                |
         # | Finland                | `eu_vat`     | European VAT Number                                                                                     |
         # | France                 | `eu_vat`     | European VAT Number                                                                                     |
         # | Georgia                | `ge_vat`     | Georgian VAT                                                                                            |
         # | Germany                | `de_stn`     | German Tax Number (Steuernummer)                                                                        |
         # | Germany                | `eu_vat`     | European VAT Number                                                                                     |
+        # | Gibraltar              | `gi_tin`     | Gibraltar Tax Identification Number                                                                     |
         # | Greece                 | `eu_vat`     | European VAT Number                                                                                     |
         # | Guinea                 | `gn_nif`     | Guinea Tax Identification Number (Número de Identificação Fiscal)                                       |
         # | Hong Kong              | `hk_br`      | Hong Kong BR Number                                                                                     |
@@ -858,6 +883,7 @@ module Orb
         # | Ireland                | `eu_vat`     | European VAT Number                                                                                     |
         # | Israel                 | `il_vat`     | Israel VAT                                                                                              |
         # | Italy                  | `eu_vat`     | European VAT Number                                                                                     |
+        # | Italy                  | `it_cf`      | Italian Codice Fiscale Number                                                                           |
         # | Japan                  | `jp_cn`      | Japanese Corporate Number (_Hōjin Bangō_)                                                               |
         # | Japan                  | `jp_rn`      | Japanese Registered Foreign Businesses' Registration Number (_Tōroku Kokugai Jigyōsha no Tōroku Bangō_) |
         # | Japan                  | `jp_trn`     | Japanese Tax Registration Number (_Tōroku Bangō_)                                                       |
@@ -888,6 +914,7 @@ module Orb
         # | Norway                 | `no_vat`     | Norwegian VAT Number                                                                                    |
         # | Norway                 | `no_voec`    | Norwegian VAT on e-commerce Number                                                                      |
         # | Oman                   | `om_vat`     | Omani VAT Number                                                                                        |
+        # | Paraguay               | `py_ruc`     | Paraguayan RUC Number                                                                                   |
         # | Peru                   | `pe_ruc`     | Peruvian RUC Number                                                                                     |
         # | Philippines            | `ph_tin`     | Philippines Tax Identification Number                                                                   |
         # | Poland                 | `eu_vat`     | European VAT Number                                                                                     |
@@ -909,6 +936,7 @@ module Orb
         # | South Korea            | `kr_brn`     | Korean BRN                                                                                              |
         # | Spain                  | `es_cif`     | Spanish NIF Number (previously Spanish CIF Number)                                                      |
         # | Spain                  | `eu_vat`     | European VAT Number                                                                                     |
+        # | Sri Lanka              | `lk_vat`     | Sri Lanka VAT Number                                                                                    |
         # | Suriname               | `sr_fin`     | Suriname FIN Number                                                                                     |
         # | Sweden                 | `eu_vat`     | European VAT Number                                                                                     |
         # | Switzerland            | `ch_uid`     | Switzerland UID Number                                                                                  |

data/rbi/orb/resources/events/backfills.rbi

@@ -12,8 +12,8 @@ module Orb
         # 3 steps:
         #
         # 1. Create the backfill, specifying its parameters.
-        # 2. [Ingest](ingest) usage events, referencing the backfill (query parameter
-        #    `backfill_id`).
+        # 2. [Ingest](/api-reference/event/ingest-events) usage events, referencing the
+        #    backfill (query parameter `backfill_id`).
         # 3. [Close](close-backfill) the backfill, propagating the update in past usage
         #    throughout Orb.
         #
@@ -94,8 +94,7 @@ module Orb
         # The list of backfills is ordered starting from the most recently created
         # backfill. The response also includes
         # [`pagination_metadata`](/api-reference/pagination), 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](pagination).
+        # retrieve the next page of results if they exist.
         sig do
           params(
             cursor: T.nilable(String),

data/rbi/orb/resources/events.rbi

@@ -258,8 +258,8 @@ module Orb
       # billed for in the corresponding billing period.
       #
       # In general, Orb does not expect events with future dated timestamps. In cases
-      # where the timestamp is at least 24 hours ahead of the current time, the event
-      # will not be accepted as a valid event, and will throw validation errors.
+      # where the timestamp is 5 minutes ahead of the current time, the event will not
+      # be accepted as a valid event, and will throw validation errors.
       #
       # ## Event validation
       #
@@ -274,9 +274,9 @@ module Orb
       # - If the `external_customer_id` is specified, the customer in Orb does not need
       #   to exist. Events will be attributed to any future customers with the
       #   `external_customer_id` on subscription creation.
-      # - `timestamp` must conform to ISO 8601 and represent a timestamp at most 1 hour
-      #   in the future. This timestamp should be sent in UTC timezone (no timezone
-      #   offset).
+      # - `timestamp` must conform to ISO 8601 and represent a timestamp at most 5
+      #   minutes in the future. This timestamp should be sent in UTC timezone (no
+      #   timezone offset).
       #
       # ## Idempotency and retry semantics
       #
@@ -313,34 +313,7 @@ module Orb
       # request payload size, but please give us a heads up if you’re changing either of
       # these factors by an order of magnitude from initial setup.
       #
-      # ## Testing in debug mode
-      #
-      # The ingestion API supports a debug mode, which returns additional verbose output
-      # to indicate which event idempotency keys were newly ingested or duplicates from
-      # previous requests. To enable this mode, mark `debug=true` as a query parameter.
-      #
-      # If `debug=true` is not specified, the response will only contain
-      # `validation_failed`. Orb will still honor the idempotency guarantees set
-      # [here](/events-and-metrics/event-ingestion#event-volume-and-concurrency) in all
-      # cases.
-      #
-      # We strongly recommend that you only use debug mode as part of testing your
-      # initial Orb integration. Once you're ready to switch to production, disable
-      # debug mode to take advantage of improved performance and maximal throughput.
-      #
-      # #### Example: ingestion response with `debug=true`
-      #
-      # ```json
-      # {
-      #   "debug": {
-      #     "duplicate": [],
-      #     "ingested": ["B7E83HDMfJPAunXW", "SJs5DQJ3TnwSqEZE", "8SivfDsNKwCeAXim"]
-      #   },
-      #   "validation_failed": []
-      # }
-      # ```
-      #
-      # #### Example: ingestion response with `debug=false`
+      # #### Example: ingestion response
       #
       # ```json
       # {
@@ -361,8 +334,8 @@ module Orb
         # Query param: If this ingestion request is part of a backfill, this parameter
         # ties the ingested events to the backfill
         backfill_id: nil,
-        # Query param: Flag to enable additional debug information in the endpoint
-        # response
+        # Query param: Pending Deprecation: Flag to enable additional debug information in
+        # the endpoint response
         debug: nil,
         request_options: {}
       )

data/rbi/orb/resources/invoices.rbi

@@ -22,7 +22,8 @@ module Orb
                 Orb::PercentageDiscount::OrHash,
                 Orb::TrialDiscount::OrHash,
                 Orb::UsageDiscount::OrHash,
-                Orb::AmountDiscount::OrHash
+                Orb::AmountDiscount::OrHash,
+                Orb::Discount::TieredPercentage::OrHash
               )
             ),
           due_date: T.nilable(Orb::InvoiceCreateParams::DueDate::Variants),
@@ -38,8 +39,9 @@ module Orb
         # An ISO 4217 currency string. Must be the same as the customer's currency if it
         # is set.
         currency:,
-        # Optional invoice date to set. Must be in the past, if not set, `invoice_date` is
-        # set to the current time in the customer's timezone.
+        # An ISO 8601 date or timestamp, interpreted in the customer's timezone. Must be
+        # in the past. If a date is set without a time, `invoice_date` is set to midnight
+        # on the chosen date in the customer's timezone.
         invoice_date:,
         line_items:,
         # Determines whether this invoice will automatically attempt to charge a saved
@@ -136,6 +138,10 @@ module Orb
       # 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.
+      #
+      # If you don't need line item details, minimums, maximums, or discounts, prefer
+      # the [list invoices summary](/api-reference/invoice/list-invoices-summary)
+      # endpoint for better performance.
       sig do
         params(
           amount: T.nilable(String),
@@ -377,15 +383,23 @@ 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".
+      # This endpoint collects payment for an invoice. By default, it uses the
+      # customer's default payment method. Optionally, a shared payment token (SPT) can
+      # be provided to pay using agent-granted credentials instead. This action can only
+      # be taken on invoices with status "issued".
       sig do
         params(
           invoice_id: String,
+          shared_payment_token_id: String,
           request_options: Orb::RequestOptions::OrHash
         ).returns(Orb::Invoice)
       end
-      def pay(invoice_id, request_options: {})
+      def pay(
+        invoice_id,
+        # The ID of a shared payment token granted by an agent to use for this payment.
+        shared_payment_token_id:,
+        request_options: {}
+      )
       end
 
       # This endpoint allows an invoice's status to be set to the `void` status. This

data/rbi/orb/resources/licenses/external_licenses.rbi

@@ -15,7 +15,7 @@ module Orb
             subscription_id: String,
             cursor: T.nilable(String),
             end_date: T.nilable(Date),
-            group_by: T.nilable(T::Array[String]),
+            group_by: T.nilable(String),
             limit: Integer,
             start_date: T.nilable(Date),
             request_options: Orb::RequestOptions::OrHash

data/rbi/orb/resources/licenses/usage.rbi

@@ -14,7 +14,7 @@ module Orb
             subscription_id: String,
             cursor: T.nilable(String),
             end_date: T.nilable(Date),
-            group_by: T.nilable(T::Array[String]),
+            group_by: T.nilable(String),
             limit: Integer,
             start_date: T.nilable(Date),
             request_options: Orb::RequestOptions::OrHash
@@ -50,7 +50,7 @@ module Orb
             license_id: String,
             cursor: T.nilable(String),
             end_date: T.nilable(Date),
-            group_by: T.nilable(T::Array[String]),
+            group_by: T.nilable(String),
             limit: Integer,
             start_date: T.nilable(Date),
             request_options: Orb::RequestOptions::OrHash

data/rbi/orb/resources/metrics.rbi

@@ -56,9 +56,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.
+      # This endpoint is used to list [metrics](/core-concepts#metric). It returns
+      # information about the metrics including its name, description, and item.
       sig do
         params(
           created_at_gt: T.nilable(Time),
@@ -84,8 +83,9 @@ 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.
+      # 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.
       sig do
         params(
           metric_id: String,

data/rbi/orb/resources/plans/external_plan_id.rbi

@@ -8,13 +8,14 @@ module Orb
       # subscription. You can see more about how to configure prices in the
       # [Price resource](/reference/price).
       class ExternalPlanID
-        # This endpoint can be used to update the `external_plan_id`, and `metadata` of an
-        # existing plan.
+        # This endpoint can be used to update the `external_plan_id`, `description`, and
+        # `metadata` of an existing plan.
         #
         # Other fields on a plan are currently immutable.
         sig do
           params(
             other_external_plan_id: String,
+            description: T.nilable(String),
             external_plan_id: T.nilable(String),
             metadata: T.nilable(T::Hash[Symbol, T.nilable(String)]),
             request_options: Orb::RequestOptions::OrHash
@@ -22,6 +23,8 @@ module Orb
         end
         def update(
           other_external_plan_id,
+          # An optional user-defined description of the plan.
+          description: nil,
           # An optional user-defined ID for this plan resource, used throughout the system
           # as an alias for this Plan. Use this field to identify a plan by an existing
           # identifier in your system.

data/rbi/orb/resources/plans.rbi

@@ -30,6 +30,7 @@ module Orb
           adjustments:
             T.nilable(T::Array[Orb::PlanCreateParams::Adjustment::OrHash]),
           default_invoice_memo: T.nilable(String),
+          description: T.nilable(String),
           external_plan_id: T.nilable(String),
           metadata: T.nilable(T::Hash[Symbol, T.nilable(String)]),
           net_terms: T.nilable(Integer),
@@ -52,6 +53,8 @@ module Orb
         adjustments: nil,
         # Free-form text which is available on the invoice PDF and the Orb invoice portal.
         default_invoice_memo: nil,
+        # An optional user-defined description of the plan.
+        description: nil,
         external_plan_id: nil,
         # User-specified key/value pairs for the resource. Individual keys can be removed
         # by setting the value to `null`, and the entire metadata mapping can be cleared
@@ -71,13 +74,14 @@ module Orb
       )
       end
 
-      # This endpoint can be used to update the `external_plan_id`, and `metadata` of an
-      # existing plan.
+      # This endpoint can be used to update the `external_plan_id`, `description`, and
+      # `metadata` of an existing plan.
       #
       # Other fields on a plan are currently immutable.
       sig do
         params(
           plan_id: String,
+          description: T.nilable(String),
           external_plan_id: T.nilable(String),
           metadata: T.nilable(T::Hash[Symbol, T.nilable(String)]),
           request_options: Orb::RequestOptions::OrHash
@@ -85,6 +89,8 @@ module Orb
       end
       def update(
         plan_id,
+        # An optional user-defined description of the plan.
+        description: nil,
         # An optional user-defined ID for this plan resource, used throughout the system
         # as an alias for this Plan. Use this field to identify a plan by an existing
         # identifier in your system.
@@ -100,7 +106,7 @@ module Orb
       # 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
+      # [`pagination_metadata`](/api-reference/pagination) which lets the caller
       # retrieve the next page of results if they exist.
       sig do
         params(