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

Customers

Overview

Available Operations

• get_or_create - Creates a customer if they do not exist, or returns the existing customer by your external customer ID.

Use this as the primary entrypoint before billing operations so the customer record is always present and up to date.

• list - Lists customers with pagination and optional filters.
• update - Updates an existing customer by ID.
• delete - Deletes a customer by ID.

get_or_create

Creates a customer if they do not exist, or returns the existing customer by your external customer ID.

Use this as the primary entrypoint before billing operations so the customer record is always present and up to date.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.customers.get_or_create(customer_id="cus_123", name="John Doe", email="john@example.com")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	Nullable[str]	✔️	N/A
name	OptionalNullable[str]	➖	Customer's name
email	OptionalNullable[str]	➖	Customer's email address
fingerprint	OptionalNullable[str]	➖	Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
metadata	Dict[str, Any]	➖	Additional metadata for the customer
stripe_id	OptionalNullable[str]	➖	Stripe customer ID if you already have one
create_in_stripe	Optional[bool]	➖	Whether to create the customer in Stripe
auto_enable_plan_id	Optional[str]	➖	The ID of the free plan to auto-enable for the customer
send_email_receipts	Optional[bool]	➖	Whether to send email receipts to this customer
expand	List[models.CustomerExpand]	➖	Customer expand options
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.Customer

Errors

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

list

Lists customers with pagination and optional filters.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.customers.list(request={})

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
request	models.ListCustomersParams	✔️	The request object to use for the request.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.ListCustomersResponse

Errors

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

update

Updates an existing customer by ID.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.customers.update(customer_id="cus_123", name="Jane Doe", email="jane@example.com")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	ID of the customer to update
name	OptionalNullable[str]	➖	Customer's name
email	OptionalNullable[str]	➖	Customer's email address
fingerprint	OptionalNullable[str]	➖	Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
metadata	Dict[str, Any]	➖	Additional metadata for the customer
stripe_id	OptionalNullable[str]	➖	Stripe customer ID if you already have one
send_email_receipts	Optional[bool]	➖	Whether to send email receipts to this customer
new_customer_id	Optional[str]	➖	Your unique identifier for the customer
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.UpdateCustomerResponse

Errors

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

delete

Deletes a customer by ID.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.customers.delete(customer_id="cus_123", delete_in_stripe=False)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	ID of the customer to delete
delete_in_stripe	Optional[bool]	➖	Whether to also delete the customer in Stripe
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.DeleteCustomerResponse

Errors

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