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

Billing

Overview

Available Operations

• attach - Attaches a plan to a customer. Handles new subscriptions, upgrades and downgrades.

Use this endpoint to subscribe a customer to a plan, upgrade/downgrade between plans, or add an add-on product.

• preview_attach - Previews the billing changes that would occur when attaching a plan, without actually making any changes.

Use this endpoint to show customers what they will be charged before confirming a subscription change.

• update - Updates an existing subscription. Use to modify feature quantities, cancel, or change plan configuration.

Use this endpoint to update prepaid quantities, cancel a subscription (immediately or at end of cycle), or modify subscription settings.

• preview_update - Previews the billing changes that would occur when updating a subscription, without actually making any changes.

Use this endpoint to show customers prorated charges or refunds before confirming subscription modifications.

• open_customer_portal - Create a billing portal session for a customer to manage their subscription.
• setup_payment - Create a payment setup session for a customer to add or update their payment method.

attach

Attaches a plan to a customer. Handles new subscriptions, upgrades and downgrades.

Use this endpoint to subscribe a customer to a plan, upgrade/downgrade between plans, or add an add-on product.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.billing.attach(customer_id="cus_123", plan_id="pro_plan")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	The ID of the customer to attach the plan to.
plan_id	str	✔️	The ID of the plan.
entity_id	Optional[str]	➖	The ID of the entity to attach the plan to.
feature_quantities	List[models.BillingAttachFeatureQuantity]	➖	If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
version	Optional[float]	➖	The version of the plan to attach.
free_trial	OptionalNullable[models.BillingAttachFreeTrial]	➖	Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
customize	Optional[models.BillingAttachCustomize]	➖	Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.
invoice_mode	Optional[models.BillingAttachInvoiceMode]	➖	Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
billing_behavior	Optional[models.BillingAttachBillingBehavior]	➖	How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
discounts	List[models.BillingAttachDiscountUnion]	➖	List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
success_url	Optional[str]	➖	URL to redirect to after successful checkout.
new_billing_subscription	Optional[bool]	➖	Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
plan_schedule	Optional[models.BillingAttachPlanSchedule]	➖	When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.BillingAttachResponse

Errors

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

preview_attach

Previews the billing changes that would occur when attaching a plan, without actually making any changes.

Use this endpoint to show customers what they will be charged before confirming a subscription change.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.billing.preview_attach(customer_id="cus_123", plan_id="pro_plan")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	The ID of the customer to attach the plan to.
plan_id	str	✔️	The ID of the plan.
entity_id	Optional[str]	➖	The ID of the entity to attach the plan to.
feature_quantities	List[models.PreviewAttachFeatureQuantity]	➖	If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
version	Optional[float]	➖	The version of the plan to attach.
free_trial	OptionalNullable[models.PreviewAttachFreeTrial]	➖	Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
customize	Optional[models.PreviewAttachCustomize]	➖	Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.
invoice_mode	Optional[models.PreviewAttachInvoiceMode]	➖	Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
billing_behavior	Optional[models.PreviewAttachBillingBehavior]	➖	How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
discounts	List[models.PreviewAttachDiscountUnion]	➖	List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
success_url	Optional[str]	➖	URL to redirect to after successful checkout.
new_billing_subscription	Optional[bool]	➖	Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
plan_schedule	Optional[models.PreviewAttachPlanSchedule]	➖	When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.PreviewAttachResponse

Errors

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

update

Updates an existing subscription. Use to modify feature quantities, cancel, or change plan configuration.

Use this endpoint to update prepaid quantities, cancel a subscription (immediately or at end of cycle), or modify subscription settings.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.billing.update(customer_id="cus_123", plan_id="pro_plan", feature_quantities=[
        {
            "feature_id": "seats",
            "quantity": 10,
        },
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	The ID of the customer to attach the plan to.
plan_id	str	✔️	The ID of the plan.
entity_id	Optional[str]	➖	The ID of the entity to attach the plan to.
feature_quantities	List[models.BillingUpdateFeatureQuantity]	➖	If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
version	Optional[float]	➖	The version of the plan to attach.
free_trial	OptionalNullable[models.BillingUpdateFreeTrial]	➖	Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
customize	Optional[models.BillingUpdateCustomize]	➖	Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.
invoice_mode	Optional[models.BillingUpdateInvoiceMode]	➖	Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
billing_behavior	Optional[models.BillingUpdateBillingBehavior]	➖	How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
cancel_action	Optional[models.BillingUpdateCancelAction]	➖	Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.BillingUpdateResponse

Errors

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

preview_update

Previews the billing changes that would occur when updating a subscription, without actually making any changes.

Use this endpoint to show customers prorated charges or refunds before confirming subscription modifications.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.billing.preview_update(customer_id="cus_123", plan_id="pro_plan", feature_quantities=[
        {
            "feature_id": "seats",
            "quantity": 15,
        },
    ])

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	The ID of the customer to attach the plan to.
plan_id	str	✔️	The ID of the plan.
entity_id	Optional[str]	➖	The ID of the entity to attach the plan to.
feature_quantities	List[models.PreviewUpdateFeatureQuantity]	➖	If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
version	Optional[float]	➖	The version of the plan to attach.
free_trial	OptionalNullable[models.PreviewUpdateFreeTrial]	➖	Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
customize	Optional[models.PreviewUpdateCustomize]	➖	Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.
invoice_mode	Optional[models.PreviewUpdateInvoiceMode]	➖	Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
billing_behavior	Optional[models.PreviewUpdateBillingBehavior]	➖	How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
cancel_action	Optional[models.PreviewUpdateCancelAction]	➖	Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.PreviewUpdateResponse

Errors

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

open_customer_portal

Create a billing portal session for a customer to manage their subscription.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.billing.open_customer_portal(customer_id="cus_123", return_url="https://useautumn.com")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	The ID of the customer to open the billing portal for.
configuration_id	Optional[str]	➖	Stripe billing portal configuration ID. Create configurations in your Stripe dashboard.
return_url	Optional[str]	➖	URL to redirect to when back button is clicked in the billing portal
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.OpenCustomerPortalResponse

Errors

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

setup_payment

Create a payment setup session for a customer to add or update their payment method.

Example Usage

from autumn_sdk import Autumn


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

    res = autumn.billing.setup_payment(customer_id="cus_123", success_url="https://example.com/account/billing")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
customer_id	str	✔️	The ID of the customer
success_url	Optional[str]	➖	URL to redirect to after successful payment setup. Must start with either http:// or https://
customer_data	Optional[models.CustomerData]	➖	Customer details to set when creating a customer
checkout_session_params	Dict[str, Any]	➖	Additional parameters for the checkout session
retries	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.SetupPaymentResponse

Errors

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