cfw-autumn/others/python-sdk/docs/sdks/balances/README.md

Balances

Overview

Available Operations

• create - Create a balance for a customer feature.
• update - Update a customer balance.

create

Create a balance for a customer feature.

Example Usage

from autumn_sdk import Autumn


with Autumn(
    x_api_version="2.1",
    secret_key="<YOUR_BEARER_TOKEN_HERE>",
) as autumn:

    res = autumn.balances.create(customer_id="cus_123", feature_id="api_calls", included=1000, reset={
        "interval": "month",
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	The ID of the customer.
feature_id	str	✔️	The ID of the feature.
entity_id	Optional[str]	➖	The ID of the entity for entity-scoped balances (e.g., per-seat limits).
included	Optional[float]	➖	The initial balance amount to grant. For metered features, this is the number of units the customer can use.
unlimited	Optional[bool]	➖	If true, the balance has unlimited usage. Cannot be combined with 'included'.
reset	Optional[models.CreateBalanceReset]	➖	Reset configuration for the balance. If not provided, the balance is a one-time grant that never resets.
expires_at	Optional[float]	➖	Unix timestamp (milliseconds) when the balance expires. Mutually exclusive with reset.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.CreateBalanceResponse

Errors

Error Type	Status Code	Content Type
errors.AutumnDefaultError	4XX, 5XX	*/*

update

Update a customer balance.

Example Usage

from autumn_sdk import Autumn


with Autumn(
    x_api_version="2.1",
    secret_key="<YOUR_BEARER_TOKEN_HERE>",
) as autumn:

    res = autumn.balances.update(customer_id="cus_123", feature_id="api_calls", remaining=5)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	The ID of the customer.
feature_id	str	✔️	The ID of the feature.
entity_id	Optional[str]	➖	The ID of the entity for entity-scoped balances (e.g., per-seat limits).
remaining	Optional[float]	➖	Set the remaining balance to this exact value. Cannot be combined with add_to_balance.
add_to_balance	Optional[float]	➖	Add this amount to the current balance. Use negative values to subtract. Cannot be combined with current_balance.
interval	Optional[models.UpdateBalanceInterval]	➖	Target a specific balance by its reset interval. Use when the customer has multiple balances for the same feature with different reset intervals.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.UpdateBalanceResponse

Errors

Error Type	Status Code	Content Type
errors.AutumnDefaultError	4XX, 5XX	*/*