orbcorp · stainless-app · Jul 16, 2025 · Jul 14, 2025 · Jul 16, 2025 · Jul 16, 2025
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "4.4.2"
+  ".": "4.5.0"
 }
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 116
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-0db984d367f9ae04249fb6c72789b0a38ef1785d156b438fe03290fa4e262a7d.yml
-openapi_spec_hash: c901c8b4fc2b0399a33b1346f8521850
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-612316c13276a207f56e2e2c7bbc68f4bb73de85e3661595a23f23d9ccc80276.yml
+openapi_spec_hash: 6e125f05e40521ec485edf6e15beec2e
 config_hash: 3c3524be9607afb24d2139ce26ce5389
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## 4.5.0 (2025-07-16)
+
+Full Changelog: [v4.4.2...v4.5.0](https://github.com/orbcorp/orb-python/compare/v4.4.2...v4.5.0)
+
+### Features
+
+* **api:** api update ([eefec6f](https://github.com/orbcorp/orb-python/commit/eefec6f4b2c23cb08343567c1a3a067cd17d9076))
+* clean up environment call outs ([fabad9f](https://github.com/orbcorp/orb-python/commit/fabad9ffbdf724b695a41c355ea53f5546889610))
+
 ## 4.4.2 (2025-07-11)
 
 Full Changelog: [v4.4.1...v4.4.2](https://github.com/orbcorp/orb-python/compare/v4.4.1...v4.4.2)

diff --git a/README.md b/README.md
@@ -83,15 +83,14 @@ pip install orb-billing[aiohttp]
 Then you can enable it by instantiating the client with `http_client=DefaultAioHttpClient()`:
 
 ```python
-import os
 import asyncio
 from orb import DefaultAioHttpClient
 from orb import AsyncOrb
 
 
 async def main() -> None:
     async with AsyncOrb(
-        api_key=os.environ.get("ORB_API_KEY"),  # This is the default and can be omitted
+        api_key="My API Key",
         http_client=DefaultAioHttpClient(),
     ) as client:
         customer = await client.customers.create(

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "orb-billing"
-version = "4.4.2"
+version = "4.5.0"
 description = "The official Python library for the orb API"
 dynamic = ["readme"]
 license = "Apache-2.0"

diff --git a/src/orb/_version.py b/src/orb/_version.py
@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "orb"
-__version__ = "4.4.2"  # x-release-please-version
+__version__ = "4.5.0"  # x-release-please-version
diff --git a/src/orb/resources/credit_notes.py b/src/orb/resources/credit_notes.py
@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Union, Iterable, Optional
-from datetime import datetime
+from datetime import date, datetime
 from typing_extensions import Literal
 
 import httpx
@@ -47,7 +47,9 @@ def create(
         *,
         line_items: Iterable[credit_note_create_params.LineItem],
         reason: Literal["duplicate", "fraudulent", "order_change", "product_unsatisfactory"],
+        end_date: Union[str, date, None] | NotGiven = NOT_GIVEN,
         memo: Optional[str] | NotGiven = NOT_GIVEN,
+        start_date: Union[str, date, None] | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -60,11 +62,46 @@ def create(
         This endpoint is used to create a single
         [`Credit Note`](/invoicing/credit-notes).
 
+        The credit note service period configuration supports two explicit modes:
+
+        1. Global service periods: Specify start_date and end_date at the credit note
+           level. These dates will be applied to all line items uniformly.
+
+        2. Individual service periods: Specify start_date and end_date for each line
+           item. When using this mode, ALL line items must have individual periods
+           specified.
+
+        3. Default behavior: If no service periods are specified (neither global nor
+           individual), the original invoice line item service periods will be used.
+
+        Note: Mixing global and individual service periods in the same request is not
+        allowed to prevent confusion.
+
+        Service period dates are normalized to the start of the day in the customer's
+        timezone to ensure consistent handling across different timezones.
+
+        Date Format: Use start_date and end_date with format "YYYY-MM-DD" (e.g.,
+        "2023-09-22") to match other Orb APIs like /v1/invoice_line_items.
+
+        Note: Both start_date and end_date are inclusive - the service period will cover
+        both the start date and end date completely (from start of start_date to end of
+        end_date).
+
         Args:
           reason: An optional reason for the credit note.
 
+          end_date: A date string to specify the global credit note service period end date in the
+              customer's timezone. This will be applied to all line items that don't have
+              their own individual service periods specified. If not provided, line items will
+              use their original invoice line item service periods. This date is inclusive.
+
           memo: An optional memo to attach to the credit note.
 
+          start_date: A date string to specify the global credit note service period start date in the
+              customer's timezone. This will be applied to all line items that don't have
+              their own individual service periods specified. If not provided, line items will
+              use their original invoice line item service periods. This date is inclusive.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -81,7 +118,9 @@ def create(
                 {
                     "line_items": line_items,
                     "reason": reason,
+                    "end_date": end_date,
                     "memo": memo,
+                    "start_date": start_date,
                 },
                 credit_note_create_params.CreditNoteCreateParams,
             ),
@@ -214,7 +253,9 @@ async def create(
         *,
         line_items: Iterable[credit_note_create_params.LineItem],
         reason: Literal["duplicate", "fraudulent", "order_change", "product_unsatisfactory"],
+        end_date: Union[str, date, None] | NotGiven = NOT_GIVEN,
         memo: Optional[str] | NotGiven = NOT_GIVEN,
+        start_date: Union[str, date, None] | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -227,11 +268,46 @@ async def create(
         This endpoint is used to create a single
         [`Credit Note`](/invoicing/credit-notes).
 
+        The credit note service period configuration supports two explicit modes:
+
+        1. Global service periods: Specify start_date and end_date at the credit note
+           level. These dates will be applied to all line items uniformly.
+
+        2. Individual service periods: Specify start_date and end_date for each line
+           item. When using this mode, ALL line items must have individual periods
+           specified.
+
+        3. Default behavior: If no service periods are specified (neither global nor
+           individual), the original invoice line item service periods will be used.
+
+        Note: Mixing global and individual service periods in the same request is not
+        allowed to prevent confusion.
+
+        Service period dates are normalized to the start of the day in the customer's
+        timezone to ensure consistent handling across different timezones.
+
+        Date Format: Use start_date and end_date with format "YYYY-MM-DD" (e.g.,
+        "2023-09-22") to match other Orb APIs like /v1/invoice_line_items.
+
+        Note: Both start_date and end_date are inclusive - the service period will cover
+        both the start date and end date completely (from start of start_date to end of
+        end_date).
+
         Args:
           reason: An optional reason for the credit note.
 
+          end_date: A date string to specify the global credit note service period end date in the
+              customer's timezone. This will be applied to all line items that don't have
+              their own individual service periods specified. If not provided, line items will
+              use their original invoice line item service periods. This date is inclusive.
+
           memo: An optional memo to attach to the credit note.
 
+          start_date: A date string to specify the global credit note service period start date in the
+              customer's timezone. This will be applied to all line items that don't have
+              their own individual service periods specified. If not provided, line items will
+              use their original invoice line item service periods. This date is inclusive.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -248,7 +324,9 @@ async def create(
                 {
                     "line_items": line_items,
                     "reason": reason,
+                    "end_date": end_date,
                     "memo": memo,
+                    "start_date": start_date,
                 },
                 credit_note_create_params.CreditNoteCreateParams,
             ),

diff --git a/src/orb/resources/customers/costs.py b/src/orb/resources/customers/costs.py
@@ -111,17 +111,17 @@ def list(
 
         A customer that uses a few API calls a day but has a minimum commitment might
         exhibit the following pattern for their subtotal and total in the first few days
-        of the month. Here, we assume that each API call is $2.50, the customer's plan
-        has a monthly minimum of $50 for this price, and that the subscription's billing
-        period bounds are aligned to the first of the month:
+        of the month. Here, we assume that each API call is \\$$2.50, the customer's plan
+        has a monthly minimum of \\$$50 for this price, and that the subscription's
+        billing period bounds are aligned to the first of the month:
 
         | timeframe_start | timeframe_end | Cumulative usage | Subtotal | Total (incl. commitment) |
         | --------------- | ------------- | ---------------- | -------- | ------------------------ |
-        | 2023-02-01      | 2023-02-02    | 9                | $22.50   | $50.00                   |
-        | 2023-02-01      | 2023-02-03    | 19               | $47.50   | $50.00                   |
-        | 2023-02-01      | 2023-02-04    | 20               | $50.00   | $50.00                   |
-        | 2023-02-01      | 2023-02-05    | 28               | $70.00   | $70.00                   |
-        | 2023-02-01      | 2023-02-06    | 36               | $90.00   | $90.00                   |
+        | 2023-02-01      | 2023-02-02    | 9                | \\$$22.50  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-03    | 19               | \\$$47.50  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-04    | 20               | \\$$50.00  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-05    | 28               | \\$$70.00  | \\$$70.00                  |
+        | 2023-02-01      | 2023-02-06    | 36               | \\$$90.00  | \\$$90.00                  |
 
         ### Periodic values
 
@@ -287,17 +287,17 @@ def list_by_external_id(
 
         A customer that uses a few API calls a day but has a minimum commitment might
         exhibit the following pattern for their subtotal and total in the first few days
-        of the month. Here, we assume that each API call is $2.50, the customer's plan
-        has a monthly minimum of $50 for this price, and that the subscription's billing
-        period bounds are aligned to the first of the month:
+        of the month. Here, we assume that each API call is \\$$2.50, the customer's plan
+        has a monthly minimum of \\$$50 for this price, and that the subscription's
+        billing period bounds are aligned to the first of the month:
 
         | timeframe_start | timeframe_end | Cumulative usage | Subtotal | Total (incl. commitment) |
         | --------------- | ------------- | ---------------- | -------- | ------------------------ |
-        | 2023-02-01      | 2023-02-02    | 9                | $22.50   | $50.00                   |
-        | 2023-02-01      | 2023-02-03    | 19               | $47.50   | $50.00                   |
-        | 2023-02-01      | 2023-02-04    | 20               | $50.00   | $50.00                   |
-        | 2023-02-01      | 2023-02-05    | 28               | $70.00   | $70.00                   |
-        | 2023-02-01      | 2023-02-06    | 36               | $90.00   | $90.00                   |
+        | 2023-02-01      | 2023-02-02    | 9                | \\$$22.50  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-03    | 19               | \\$$47.50  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-04    | 20               | \\$$50.00  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-05    | 28               | \\$$70.00  | \\$$70.00                  |
+        | 2023-02-01      | 2023-02-06    | 36               | \\$$90.00  | \\$$90.00                  |
 
         ### Periodic values
 
@@ -486,17 +486,17 @@ async def list(
 
         A customer that uses a few API calls a day but has a minimum commitment might
         exhibit the following pattern for their subtotal and total in the first few days
-        of the month. Here, we assume that each API call is $2.50, the customer's plan
-        has a monthly minimum of $50 for this price, and that the subscription's billing
-        period bounds are aligned to the first of the month:
+        of the month. Here, we assume that each API call is \\$$2.50, the customer's plan
+        has a monthly minimum of \\$$50 for this price, and that the subscription's
+        billing period bounds are aligned to the first of the month:
 
         | timeframe_start | timeframe_end | Cumulative usage | Subtotal | Total (incl. commitment) |
         | --------------- | ------------- | ---------------- | -------- | ------------------------ |
-        | 2023-02-01      | 2023-02-02    | 9                | $22.50   | $50.00                   |
-        | 2023-02-01      | 2023-02-03    | 19               | $47.50   | $50.00                   |
-        | 2023-02-01      | 2023-02-04    | 20               | $50.00   | $50.00                   |
-        | 2023-02-01      | 2023-02-05    | 28               | $70.00   | $70.00                   |
-        | 2023-02-01      | 2023-02-06    | 36               | $90.00   | $90.00                   |
+        | 2023-02-01      | 2023-02-02    | 9                | \\$$22.50  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-03    | 19               | \\$$47.50  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-04    | 20               | \\$$50.00  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-05    | 28               | \\$$70.00  | \\$$70.00                  |
+        | 2023-02-01      | 2023-02-06    | 36               | \\$$90.00  | \\$$90.00                  |
 
         ### Periodic values
 
@@ -662,17 +662,17 @@ async def list_by_external_id(
 
         A customer that uses a few API calls a day but has a minimum commitment might
         exhibit the following pattern for their subtotal and total in the first few days
-        of the month. Here, we assume that each API call is $2.50, the customer's plan
-        has a monthly minimum of $50 for this price, and that the subscription's billing
-        period bounds are aligned to the first of the month:
+        of the month. Here, we assume that each API call is \\$$2.50, the customer's plan
+        has a monthly minimum of \\$$50 for this price, and that the subscription's
+        billing period bounds are aligned to the first of the month:
 
         | timeframe_start | timeframe_end | Cumulative usage | Subtotal | Total (incl. commitment) |
         | --------------- | ------------- | ---------------- | -------- | ------------------------ |
-        | 2023-02-01      | 2023-02-02    | 9                | $22.50   | $50.00                   |
-        | 2023-02-01      | 2023-02-03    | 19               | $47.50   | $50.00                   |
-        | 2023-02-01      | 2023-02-04    | 20               | $50.00   | $50.00                   |
-        | 2023-02-01      | 2023-02-05    | 28               | $70.00   | $70.00                   |
-        | 2023-02-01      | 2023-02-06    | 36               | $90.00   | $90.00                   |
+        | 2023-02-01      | 2023-02-02    | 9                | \\$$22.50  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-03    | 19               | \\$$47.50  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-04    | 20               | \\$$50.00  | \\$$50.00                  |
+        | 2023-02-01      | 2023-02-05    | 28               | \\$$70.00  | \\$$70.00                  |
+        | 2023-02-01      | 2023-02-06    | 36               | \\$$90.00  | \\$$90.00                  |
 
         ### Periodic values
 

diff --git a/src/orb/resources/customers/credits/ledger.py b/src/orb/resources/customers/credits/ledger.py
@@ -123,8 +123,8 @@ def list(
         deductions take place from a non-expiring credit block.
 
         If there are multiple blocks with the same expiration date, Orb will deduct from
-        the block with the _lower cost basis_ first (e.g. trial credits with a $0 cost
-        basis before paid credits with a $5.00 cost basis).
+        the block with the _lower cost basis_ first (e.g. trial credits with a \\$$0 cost
+        basis before paid credits with a \\$$5.00 cost basis).
 
         It's also possible for a single usage event's deduction to _span_ credit blocks.
         In this case, Orb will deduct from the next block, ending at the credit block
@@ -2069,8 +2069,8 @@ def list_by_external_id(
         deductions take place from a non-expiring credit block.
 
         If there are multiple blocks with the same expiration date, Orb will deduct from
-        the block with the _lower cost basis_ first (e.g. trial credits with a $0 cost
-        basis before paid credits with a $5.00 cost basis).
+        the block with the _lower cost basis_ first (e.g. trial credits with a \\$$0 cost
+        basis before paid credits with a \\$$5.00 cost basis).
 
         It's also possible for a single usage event's deduction to _span_ credit blocks.
         In this case, Orb will deduct from the next block, ending at the credit block
@@ -2254,8 +2254,8 @@ def list(
         deductions take place from a non-expiring credit block.
 
         If there are multiple blocks with the same expiration date, Orb will deduct from
-        the block with the _lower cost basis_ first (e.g. trial credits with a $0 cost
-        basis before paid credits with a $5.00 cost basis).
+        the block with the _lower cost basis_ first (e.g. trial credits with a \\$$0 cost
+        basis before paid credits with a \\$$5.00 cost basis).
 
         It's also possible for a single usage event's deduction to _span_ credit blocks.
         In this case, Orb will deduct from the next block, ending at the credit block
@@ -4200,8 +4200,8 @@ def list_by_external_id(
         deductions take place from a non-expiring credit block.
 
         If there are multiple blocks with the same expiration date, Orb will deduct from
-        the block with the _lower cost basis_ first (e.g. trial credits with a $0 cost
-        basis before paid credits with a $5.00 cost basis).
+        the block with the _lower cost basis_ first (e.g. trial credits with a \\$$0 cost
+        basis before paid credits with a \\$$5.00 cost basis).
 
         It's also possible for a single usage event's deduction to _span_ credit blocks.
         In this case, Orb will deduct from the next block, ending at the credit block