API Reference¶

This page gives an overview of all the public autumn classes, functions and methods. Everything that intended for public use is exposed in the autumn.* or autumn.aio.* namespaces.

Client¶

class autumn.client.Client(token, *, base_url=None, max_retries=5)[source]¶

The main client class for interacting with the Autumn API.

Example:

import autumn

client = autumn.Client(token="your_api_key")

# Attach a customer to a product
client.attach(
    customer_id="john_doe",
    product_id="chat_messages",
)

Note

This client should not be used in async contexts. Use AsyncClient instead. The AsyncClient class is a wrapper around the Client class that provides async support. It works the same, but you must await your method calls.

import asyncio

from autumn.aio import (
    Client,
)


async def main():
    client = Client(token="your_api_key")
    await client.attach(
        customer_id="john_doe",
        product_id="chat_messages",
    )


asyncio.run(main())

The async client requires aiohttp to be installed. You can install it via: pip install aiohttp.

Parameters:

token (str) – The API key to use for authentication.
max_retries (int) – The maximum number of retries to attempt for failed requests.
base_url (Optional[str]) – The base URL of the Autumn API. This is useful when you are self-hosting Autumn and need to point to your own instance.

customers¶

An interface to Autumn’s customer API.

Type:: Customers

features¶

An interface to Autumn’s feature API.

Type:: Features

products¶

An interface to Autumn’s product API.

Type:: Products

entities¶

An interface to Autumn’s entities API.

Type:: Entities

attach(customer_id, *, product_id=None, product_ids=None, products=None, success_url=None, force_checkout=False, features=None, entity_id=None, customer_data=None, free_trial=None, options=None, reward=None)[source]¶

Attach a customer to a product.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to attach.
product_id (Optional[str]) – The ID of the product to attach.
product_ids (Optional[List[str]]) – The IDs of the products to attach.
products (Optional[List[AttachProductOptions]]) – The products to attach.
success_url (Optional[str]) – The URL to redirect to after a successful attachment.
force_checkout (bool) – Whether to force the customer to checkout.
features (Optional[List[Feature]]) – The features to attach.
entity_id (Optional[str]) – The ID of the entity to attach.
customer_data (Optional[CustomerData]) – The customer data to attach.
free_trial (Optional[bool]) – Whether to attach a free trial.
options (Optional[List[FeatureOptions]]) – The options to attach.
reward (Optional[str | List[str]]) – The reward to attach. Can pass in an array too.

Returns:

The response from the API.

Return type:

AttachResponse

cancel(customer_id, product_id, *, entity_id=None, cancel_immediately=False)[source]¶

Cancel a product for a customer.

Parameters:

customer_id (str) – The ID of the customer to cancel the product for.
product_id (str) – The ID of the product to cancel.
entity_id (Optional[str]) – The ID of the entity to cancel the product for.
cancel_immediately (bool) – Whether to cancel the product immediately. If false, the product will be cancelled at the end of the billing cycle.

Returns:

The response from the API.

Return type:

CancelResponse

check(customer_id, *, product_id=None, feature_id=None, required_balance=1, send_event=False, with_preview=False, entity_id=None, customer_data=None)[source]¶

Check if a customer has access to a product or feature.

This function returns an awaitable coroutine when using the AsyncClient class.

You must pass either product_id or feature_id. Failure to pass one and only one will raise an assertion error.

Parameters:

customer_id (str) – The ID of the customer to check.
product_id (Optional[str]) – The ID of the product to check.
feature_id (Optional[str]) – The ID of the feature to check.
required_balance (Optional[int]) – The required balance to check.
send_event (bool) – Whether to record a usage event with checking access. The `required_balance field will be used as the usage value.
with_preview (bool) – If true, the response will include a preview object, which can be used to display information such as a paywall or upgrade confirmation.
entity_id (Optional[str]) – If using entity balances (eg, seats), the entity ID to check access for.
customer_data (Optional[CustomerData]) – Additional customer properties. These will be used if the customer’s properties are not already set.

Returns:

The response from the API.

Return type:

CheckResponse

checkout(customer_id, *, product_id=None, products=None, success_url=None, force_checkout=False, options=None, entity_id=None, customer_data=None, checkout_session_params=None, reward=None)[source]¶

Checkout a customer for a product.

Parameters:

customer_id (str) – The ID of the customer to checkout.
product_id (Optional[str]) – The ID of the product to checkout.
products (Optional[List[ProductOptions]]) – The products to checkout.
success_url (Optional[str]) – The URL to redirect to after a successful checkout.
force_checkout (bool) – Whether to force the customer to checkout.
entity_id (Optional[str]) – The ID of the entity to checkout.
customer_data (Optional[CustomerData]) – The customer data to checkout.
reward (Optional[str | List[str]]) – The reward to checkout. Can pass in an array too.

Return type:

CheckoutResponse

query(customer_id, feature_id, *, range='30d')[source]¶

Query usage analytics for a customer on a specific feature.

Parameters:

customer_id (str) – The ID of the customer to query for.
feature_id (Union[str, List[str]]) – The ID of the feature you want to query analytics for.
range (Literal["24h", "7d", "30d", "90d", "last_cycle"]) – Analytics time period.

Returns:

The response from the API.

Return type:

QueryResponse

track(customer_id, feature_id=None, *, value=1, entity_id=None, event_name=None, idempotency_key=None, properties=None, customer_data=None)[source]¶

Track a feature usage.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to track.
feature_id (Optional[str]) – The ID of the feature to track. This or the event_name must be provided.
value (int) – The amount of the feature to deduct.
entity_id (Optional[str]) – The ID of the entity to track.
event_name (Optional[str]) – The name of the event to track.
idempotency_key (Optional[str]) – A unique identifier for the track event. If not provided, the SDK will not generate one - the Autumn API does not expect one.
properties (Optional[Dict[str, Any]]) – Additional properties to track.
customer_data (Optional[CustomerData]) – Additional customer properties. These will be used if the customer’s properties are not already set.

Returns:

The response from the API.

Return type:

TrackResponse

class autumn.aio.client.AsyncClient(token, *, base_url=None, max_retries=5, session=None)[source]¶

Bases: Client

The async client class for interacting with the Autumn API.

This class is also exposed as autumn.Autumn.

The AsyncClient automatically retries requests up to 5 times, exponentially backing off between attempts.

Note that session creation is lazy. This means that the AsyncClient will not attempt to create a session until the first request is made.

Parameters:

token (str) – The API key to use for authentication.
base_url (Optional[str]) – The base URL of the Autumn API. This is useful when you are self-hosting Autumn and need to point to your own instance.
max_retries (int) – The maximum number of retries to attempt for failed requests.
session (Optional[ClientSession]) – The session to use for requests. If not provided, a new session will be created lazily.

customers¶

An interface to Autumn’s customer API.

Type:: Customers

features¶

An interface to Autumn’s feature API.

Type:: Features

products¶

An interface to Autumn’s product API.

Type:: Products

entities¶

An interface to Autumn’s entities API.

Type:: Entities

Attach a customer to a product.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to attach.
product_id (Optional[str]) – The ID of the product to attach.
product_ids (Optional[List[str]]) – The IDs of the products to attach.
products (Optional[List[AttachProductOptions]]) – The products to attach.
success_url (Optional[str]) – The URL to redirect to after a successful attachment.
force_checkout (bool) – Whether to force the customer to checkout.
features (Optional[List[Feature]]) – The features to attach.
entity_id (Optional[str]) – The ID of the entity to attach.
customer_data (Optional[CustomerData]) – The customer data to attach.
free_trial (Optional[bool]) – Whether to attach a free trial.
options (Optional[List[FeatureOptions]]) – The options to attach.
reward (Optional[str | List[str]]) – The reward to attach. Can pass in an array too.

Returns:

The response from the API.

Return type:

AttachResponse

cancel(customer_id, product_id, *, entity_id=None, cancel_immediately=False)¶

Cancel a product for a customer.

Parameters:

customer_id (str) – The ID of the customer to cancel the product for.
product_id (str) – The ID of the product to cancel.
entity_id (Optional[str]) – The ID of the entity to cancel the product for.
cancel_immediately (bool) – Whether to cancel the product immediately. If false, the product will be cancelled at the end of the billing cycle.

Returns:

The response from the API.

Return type:

CancelResponse

check(customer_id, *, product_id=None, feature_id=None, required_balance=1, send_event=False, with_preview=False, entity_id=None, customer_data=None)¶

Check if a customer has access to a product or feature.

This function returns an awaitable coroutine when using the AsyncClient class.

You must pass either product_id or feature_id. Failure to pass one and only one will raise an assertion error.

Parameters:

customer_id (str) – The ID of the customer to check.
product_id (Optional[str]) – The ID of the product to check.
feature_id (Optional[str]) – The ID of the feature to check.
required_balance (Optional[int]) – The required balance to check.
send_event (bool) – Whether to record a usage event with checking access. The `required_balance field will be used as the usage value.
with_preview (bool) – If true, the response will include a preview object, which can be used to display information such as a paywall or upgrade confirmation.
entity_id (Optional[str]) – If using entity balances (eg, seats), the entity ID to check access for.
customer_data (Optional[CustomerData]) – Additional customer properties. These will be used if the customer’s properties are not already set.

Returns:

The response from the API.

Return type:

CheckResponse

Checkout a customer for a product.

Parameters:

customer_id (str) – The ID of the customer to checkout.
product_id (Optional[str]) – The ID of the product to checkout.
products (Optional[List[ProductOptions]]) – The products to checkout.
success_url (Optional[str]) – The URL to redirect to after a successful checkout.
force_checkout (bool) – Whether to force the customer to checkout.
entity_id (Optional[str]) – The ID of the entity to checkout.
customer_data (Optional[CustomerData]) – The customer data to checkout.
reward (Optional[str | List[str]]) – The reward to checkout. Can pass in an array too.

Return type:

CheckoutResponse

async close()[source]¶

query(customer_id, feature_id, *, range='30d')¶

Query usage analytics for a customer on a specific feature.

Parameters:

customer_id (str) – The ID of the customer to query for.
feature_id (Union[str, List[str]]) – The ID of the feature you want to query analytics for.
range (Literal["24h", "7d", "30d", "90d", "last_cycle"]) – Analytics time period.

Returns:

The response from the API.

Return type:

QueryResponse

track(customer_id, feature_id=None, *, value=1, entity_id=None, event_name=None, idempotency_key=None, properties=None, customer_data=None)¶

Track a feature usage.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to track.
feature_id (Optional[str]) – The ID of the feature to track. This or the event_name must be provided.
value (int) – The amount of the feature to deduct.
entity_id (Optional[str]) – The ID of the entity to track.
event_name (Optional[str]) – The name of the event to track.
idempotency_key (Optional[str]) – A unique identifier for the track event. If not provided, the SDK will not generate one - the Autumn API does not expect one.
properties (Optional[Dict[str, Any]]) – Additional properties to track.
customer_data (Optional[CustomerData]) – Additional customer properties. These will be used if the customer’s properties are not already set.

Returns:

The response from the API.

Return type:

TrackResponse

API Features¶

Customers¶

class autumn.customers.Customers(http)[source]¶

An interface to Autumn’s customer API.

Warning

This class is not intended for public use. It is used internally by the autumn.Client class. Do not initialize this class directly.

create(id, *, email=None, name=None, stripe_id=None, metadata=None)[source]¶

Create a new customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

id (str) – The ID of the customer to create.
email (Optional[str]) – The customer’s email address.
name (Optional[str]) – The customer’s name.
stripe_id (Optional[str]) – The customer’s Stripe ID. This can be a new or existing ID.
metadata (Optional[Dict[str, Any]]) – Additional metadata to attach to the customer.

Returns:

The created customer.

Return type:

Customer

delete(customer_id)[source]¶

Delete a customer.

Parameters:

customer_id (str) – The ID of the customer to delete.

Return type:

Union[Empty, Coroutine[Any, Any, Empty]]

Returns:

Empty – An empty response.
|maybecoro|

get(customer_id, expand=None)[source]¶

Get a customer by their ID.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to get.
expand (Optional[List[Literal["invoices", "rewards", "trials_used", "entities", "referrals", "payment_method"]]]) – Additional fields to expand in the response.

Returns:

The customer.

Return type:

Customer

get_billing_portal(customer_id, *, return_url=None)[source]¶

Get a billing portal URL for a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to get a billing portal URL for.
return_url (Optional[str]) – The URL to return to after the customer has completed the billing portal.

Returns:

The billing portal URL.

Return type:

BillingPortalResponse

list(*, limit=10, offset=0)[source]¶

Return type:: Union[ListCustomerResponse, Coroutine[Any, Any, ListCustomerResponse]]

pricing_table(customer_id)[source]¶

Get a pricing table for a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:: customer_id (str) – The ID of the customer to get a pricing table for.
Returns:: The pricing table.
Return type:: PricingTableResponse

update(customer_id, *, name=None, email=None, fingerprint=None)[source]¶

Update a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to update.
name (Optional[str]) – The customer’s new name.
email (Optional[str]) – The customer’s new email address.
fingerprint (Optional[str]) – The customer’s new fingerprint.

Returns:

The updated customer.

Return type:

Customer

Features¶

class autumn.features.Features(http)[source]¶

An interface to Autumn’s feature API.

Warning

This class is not intended for public use. It is used internally by the autumn.Client class. Do not initialize this class directly.

set_balances(customer_id, balances)[source]¶

Set the balances of a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to set the balances for.
balances (List[Balance]) – The balances to set for the customer.

Returns:

This is a placeholder type. Treat it as None.

Return type:

Empty

set_usage(customer_id, feature_id, value)[source]¶

Set the usage of a feature for a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to set the usage for.
feature_id (str) – The ID of the feature to set the usage for.
value (int) – The amount the usage should be updated to.

Returns:

This is a placeholder type. Treat it as None.

Return type:

Empty

Products¶

class autumn.products.Products(http)[source]¶

An interface to Autumn’s product API.

Warning

This class is not intended for public use. It is used internally by the autumn.Client class. Do not initialize this class directly.

Example:

import autumn

client = autumn.Client(token="your_api_key")

product = client.products.create(
    id="chat_messages",
    name="Chat Messages",
)

print(product.name)  # Chat Messages

create(id, *, name, is_add_on=False, is_default=False, items=None, free_trial=None)[source]¶

Create a new product.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

id (str) – The ID of the product.
name (str) – The name of the product.
is_add_on (bool) – Whether the product is an add-on.
is_default (bool) – Whether the product is a default product.
items (Optional[List[ProductItem]]) – The items of the product.
free_trial (Optional[FreeTrial]) – The free trial configuration of the product.

Returns:

The response from the API.

Return type:

CreateProductResponse

delete(id)[source]¶

Delete a product.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:: id (str) – The ID of the product to delete.
Returns:: This is a placeholder type. Treat it as None.
Return type:: Empty

get(id)[source]¶

Get a product by its ID.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:: id (str) – The ID of the product to get.
Returns:: The response from the API.
Return type:: GetProductResponse

get_referral_code(customer_id, program_id)[source]¶

Get a referral code for a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to get a referral code for.
program_id (str) – The ID of the program to get a referral code for.

Returns:

The response from the API.

Return type:

ReferralCodeResponse

list(customer_id)[source]¶

List products for a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:: customer_id (str) – The ID of the customer to list products for.
Returns:: The response from the API.
Return type:: ListProductResponse

redeem_referral_code(code, customer_id, reward_id)[source]¶

Redeem a referral code for a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

code (str) – The code to redeem.
customer_id (str) – The ID of the customer to redeem the code for.
reward_id (str) – The ID of the reward to redeem.

Returns:

The response from the API.

Return type:

ReferralRedeemResponse

update(id, *, name, is_add_on=False, is_default=False, items=None, free_trial=None)[source]¶

Update a product.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

id (str) – The ID of the product to update.
name (str) – The new name of the product.
is_add_on (bool) – Whether the product is an add-on.
is_default (bool) – Whether the product is the default product.
items (Optional[List[ProductItem]]) – The new items of the product.
free_trial (Optional[FreeTrial]) – The new free trial of the product.

Returns:

This is a placeholder type. Treat it as None.

Return type:

Empty

Entities¶

class autumn.entities.Entities(http)[source]¶

An interface to Autumn’s entities API.

Warning

This class is not intended for public use. It is used internally by the autumn.Client class. Do not initialize this class directly.

create(customer_id, id, feature_id, name)[source]¶

Create an entity for a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to create the entity for.
id (str) – The ID of the entity to create.
feature_id (str) – The ID of the feature to create the entity for.
name (str) – The name of the entity to create.

Returns:

The created entity.

Return type:

Entity

delete(customer_id, entity_id)[source]¶

Delete an entity for a customer.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to delete the entity for.
entity_id (str) – The ID of the entity to delete.

Returns:

This is a placeholder type. Treat it as None.

Return type:

Empty

get(customer_id, entity_id, expand=None)[source]¶

Get an entity by their ID.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer to get.
entity_id (str) – The ID of the entity to get.
expand (Optional[List[Literal["invoices"]]]) – Additional fields to expand in the response.

Returns:

The entity.

Return type:

Entity

transfer(customer_id, to_entity_id, product_id, from_entity_id=None)[source]¶

Transfer a product from one entity to another.

This function returns an awaitable coroutine when using the AsyncClient class.

Parameters:

customer_id (str) – The ID of the customer who owns the entities.
to_entity_id (str) – The ID of the entity to transfer the product to.
product_id (str) – The ID of the product to transfer.
from_entity_id (Optional[str]) – The ID of the entity to transfer the product from. If not provided, transfers from the customer’s general balance.

Returns:

The result of the transfer operation.

Return type:

TransferProductResult

Exceptions¶

class autumn.error.AutumnError(message, code)[source]¶

Base exception for all Autumn errors.

message¶

The error message.

Type:: str

code¶

The error code.

Type:: str

add_note(note)[source]¶: Exception.add_note(note) – add a note to the exception

class autumn.error.AutumnValidationError(message, code)[source]¶

Exception raised when a validation error occurs. This is raised when the API returns a response that isn’t recognized by the library.

message¶

The error message.

Type:: str

code¶

The error code.

Type:: str

class autumn.error.AutumnHTTPError(message, code, status_code)[source]¶

Exception raised when an HTTP error occurs.

message¶

The error message. This can be an empty string.

Type:: str

code¶

The error code.

Type:: str

status_code¶

The HTTP status code.

Type:: int

attach_body(body)[source]¶

Return type:: Self