info: title: Autumn API version: 2.1.0 servers: - url: http://localhost:8080 description: Production server openapi: 3.1.1 components: schemas: CustomerId: type: string title: CustomerId description: Your unique identifier for the customer CustomerData: type: object properties: name: anyOf: - type: string - type: "null" description: Customer's name email: anyOf: - type: string format: email - type: "null" description: Customer's email address fingerprint: anyOf: - type: string - type: "null" description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" description: Additional metadata for the customer stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID if you already have one create_in_stripe: type: boolean description: Whether to create the customer in Stripe auto_enable_plan_id: type: string description: The ID of the free plan to auto-enable for the customer send_email_receipts: type: boolean description: Whether to send email receipts to this customer title: CustomerData description: Customer details to set when creating a customer CustomerExpand: enum: - invoices - trials_used - rewards - entities - referrals - payment_method - subscriptions.plan - purchases.plan - balances.feature title: CustomerExpand Customer: type: object properties: id: anyOf: - type: string - type: "null" description: Your unique identifier for the customer. name: anyOf: - type: string - type: "null" description: The name of the customer. email: anyOf: - type: string - type: "null" description: The email address of the customer. created_at: type: number description: Timestamp of customer creation in milliseconds since epoch. fingerprint: anyOf: - type: string - type: "null" description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID. env: enum: - sandbox - live description: The environment this customer was created in. metadata: type: object propertyNames: {} additionalProperties: {} description: The metadata for the customer. send_email_receipts: type: boolean description: Whether to send email receipts to the customer. subscriptions: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" plan_id: type: string auto_enable: type: boolean add_on: type: boolean status: enum: - active - scheduled - expired past_due: type: boolean canceled_at: anyOf: - type: number - type: "null" expires_at: anyOf: - type: number - type: "null" trial_ends_at: anyOf: - type: number - type: "null" started_at: type: number current_period_start: anyOf: - type: number - type: "null" current_period_end: anyOf: - type: number - type: "null" quantity: type: number required: - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" plan_id: type: string expires_at: anyOf: - type: number - type: "null" started_at: type: number quantity: type: number required: - plan_id - expires_at - started_at - quantity balances: type: object propertyNames: type: string additionalProperties: type: object properties: feature_id: type: string feature: type: object properties: id: type: string name: type: string type: enum: - boolean - metered - credit_system consumable: type: boolean event_names: type: array items: type: string credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost display: type: object properties: singular: anyOf: - type: string - type: "null" plural: anyOf: - type: string - type: "null" archived: type: boolean required: - id - name - type - consumable - archived granted: type: number remaining: type: number minimum: 0 usage: type: number unlimited: type: boolean overage_allowed: type: boolean max_purchase: anyOf: - type: number - type: "null" next_reset_at: anyOf: - type: number - type: "null" breakdown: type: array items: type: object properties: id: type: string default: "" plan_id: anyOf: - type: string - type: "null" included_grant: type: number prepaid_grant: type: number remaining: type: number usage: type: number unlimited: type: boolean reset: anyOf: - type: object properties: interval: anyOf: - enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year - const: multiple interval_count: type: number resets_at: anyOf: - type: number - type: "null" required: - interval - resets_at - type: "null" price: anyOf: - type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount billing_units: type: number billing_method: enum: - prepaid - usage_based max_purchase: anyOf: - type: number - type: "null" required: - billing_units - billing_method - max_purchase - type: "null" expires_at: anyOf: - type: number - type: "null" required: - plan_id - included_grant - prepaid_grant - remaining - usage - unlimited - reset - price - expires_at rollovers: type: array items: type: object properties: balance: type: number expires_at: type: number required: - balance - expires_at required: - feature_id - granted - remaining - usage - unlimited - overage_allowed - max_purchase - next_reset_at invoices: type: array items: type: object properties: plan_ids: type: array items: type: string description: Array of plan IDs included in this invoice stripe_id: type: string description: The Stripe invoice ID status: type: string description: The status of the invoice total: type: number description: The total amount of the invoice currency: type: string description: The currency code for the invoice created_at: type: number description: Timestamp when the invoice was created hosted_invoice_url: anyOf: - type: string - type: "null" description: URL to the Stripe-hosted invoice page required: - plan_ids - stripe_id - status - total - currency - created_at entities: type: array items: type: object properties: autumn_id: type: string id: anyOf: - type: string - type: "null" description: The unique identifier of the entity name: anyOf: - type: string - type: "null" description: The name of the entity customer_id: anyOf: - type: string - type: "null" description: The customer ID this entity belongs to feature_id: anyOf: - type: string - type: "null" description: The feature ID this entity belongs to created_at: type: number description: Unix timestamp when the entity was created env: enum: - sandbox - live description: The environment (sandbox/live) required: - id - name - created_at - env trials_used: type: array items: type: object properties: plan_id: type: string customer_id: type: string fingerprint: anyOf: - type: string - type: "null" required: - plan_id - customer_id rewards: anyOf: - type: object properties: discounts: type: array items: type: object properties: id: type: string description: The unique identifier for this discount name: type: string description: The name of the discount or coupon type: enum: - percentage_discount - fixed_discount - free_product - invoice_credits description: The type of reward discount_value: type: number description: The discount value (percentage or fixed amount) duration_type: enum: - one_off - months - forever description: How long the discount lasts duration_value: anyOf: - type: number - type: "null" description: Number of billing periods the discount applies for repeating durations currency: anyOf: - type: string - type: "null" description: The currency code for fixed amount discounts start: anyOf: - type: number - type: "null" description: Timestamp when the discount becomes active end: anyOf: - type: number - type: "null" description: Timestamp when the discount expires subscription_id: anyOf: - type: string - type: "null" description: The Stripe subscription ID this discount is applied to total_discount_amount: anyOf: - type: number - type: "null" description: Total amount saved from this discount required: - id - name - type - discount_value - duration_type description: Array of active discounts applied to the customer required: - discounts - type: "null" referrals: type: array items: type: object properties: program_id: type: string customer: type: object properties: id: type: string name: anyOf: - type: string - type: "null" email: anyOf: - type: string - type: "null" required: - id reward_applied: type: boolean created_at: type: number required: - program_id - customer - reward_applied - created_at payment_method: anyOf: - {} - type: "null" required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - subscriptions - purchases - balances examples: - &a2 id: cus_123 created_at: 1717000000 name: John Doe email: john@example.com fingerprint: "1234567890" stripe_id: cus_123 env: sandbox metadata: {} subscriptions: - id: sub_123 created_at: 1717000000 plan_id: plan_123 status: active quantity: 1 interval: month interval_count: 1 purchases: [] balances: balance_1: id: balance_1 amount: 100 currency: USD created_at: 1717000000 updated_at: 1717000000 Plan: type: object properties: id: type: string name: type: string description: anyOf: - type: string - type: "null" group: anyOf: - type: string - type: "null" version: type: number add_on: type: boolean auto_enable: type: boolean price: anyOf: - type: object properties: amount: type: number interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number display: type: object properties: primary_text: type: string secondary_text: type: string required: - primary_text required: - amount - interval - type: "null" items: type: array items: type: object properties: feature_id: type: string feature: type: object properties: id: type: string description: The ID of the feature, used to refer to it in other API calls like /track or /check. name: anyOf: - type: string - type: "null" description: The name of the feature. type: enum: - static - boolean - single_use - continuous_use - credit_system description: The type of the feature display: anyOf: - type: object properties: singular: type: string description: The singular display name for the feature. plural: type: string description: The plural display name for the feature. required: - singular - plural - type: "null" description: Singular and plural display names for the feature. credit_schema: anyOf: - type: array items: type: object properties: metered_feature_id: type: string description: The ID of the metered feature (should be a single_use feature). credit_cost: type: number description: The credit cost of the metered feature. required: - metered_feature_id - credit_cost - type: "null" description: Credit cost schema for credit system features. archived: anyOf: - type: boolean - type: "null" description: Whether or not the feature is archived. required: - id - type included: type: number unlimited: type: boolean reset: anyOf: - type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year interval_count: type: number required: - interval - type: "null" price: anyOf: - type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number billing_units: type: number billing_method: enum: - prepaid - usage_based max_purchase: anyOf: - type: number - type: "null" required: - interval - billing_units - billing_method - max_purchase - type: "null" display: type: object properties: primary_text: type: string secondary_text: type: string required: - primary_text rollover: type: object properties: max: anyOf: - type: number - type: "null" expiry_duration_type: enum: - month - forever expiry_duration_length: type: number required: - max - expiry_duration_type proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations required: - feature_id - included - unlimited - reset - price free_trial: type: object properties: duration_length: type: number duration_type: enum: - day - month - year card_required: type: boolean required: - duration_length - duration_type - card_required created_at: type: number env: enum: - sandbox - live archived: type: boolean base_variant_id: anyOf: - type: string - type: "null" customer_eligibility: type: object properties: trial_available: type: boolean scenario: enum: - scheduled - active - new - renew - upgrade - downgrade - cancel - expired - past_due required: - scenario required: - id - name - description - group - version - add_on - auto_enable - price - items - created_at - env - archived - base_variant_id securitySchemes: secretKey: type: http scheme: bearer bearerFormat: JWT paths: /v1/customers.get_or_create: post: operationId: getOrCreateCustomer description: >- 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. tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: anyOf: - $ref: "#/components/schemas/CustomerId" - type: "null" name: anyOf: - type: string - type: "null" description: Customer's name email: anyOf: - type: string format: email - type: "null" description: Customer's email address fingerprint: anyOf: - type: string - type: "null" description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" description: Additional metadata for the customer stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID if you already have one create_in_stripe: type: boolean description: Whether to create the customer in Stripe auto_enable_plan_id: type: string description: The ID of the free plan to auto-enable for the customer send_email_receipts: type: boolean description: Whether to send email receipts to this customer expand: type: array items: $ref: "#/components/schemas/CustomerExpand" description: Customer expand options required: - customer_id title: GetOrCreateCustomerParams examples: - &a1 customer_id: cus_123 name: John Doe email: john@example.com example: *a1 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/Customer" example: *a2 x-speakeasy-name-override: getOrCreate parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.customers.getOrCreate({ customerId: "cus_123", name: "John Doe", email: "john@example.com", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.customers.get_or_create( customer_id="cus_123", name="John Doe", email="john@example.com", ) /v1/customers.list: post: operationId: listCustomers description: Lists customers with pagination and optional filters. tags: - customers requestBody: required: false content: application/json: schema: type: object properties: offset: type: integer minimum: 0 maximum: 9007199254740991 default: 0 description: Number of items to skip limit: type: integer minimum: 1 maximum: 1000 default: 10 description: Number of items to return. Default 10, max 1000. plans: type: array items: type: object properties: id: type: string versions: type: array items: type: number required: - id description: Filter by plan ID and version. Returns customers with active subscriptions to this plan. subscription_status: enum: - active - scheduled description: Filter by customer product status. Defaults to active and scheduled search: type: string description: Search customers by id, name, or email title: ListCustomersParams examples: - &a3 limit: 10 offset: 0 example: *a3 responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: anyOf: - type: string - type: "null" description: Your unique identifier for the customer. name: anyOf: - type: string - type: "null" description: The name of the customer. email: anyOf: - type: string - type: "null" description: The email address of the customer. created_at: type: number description: Timestamp of customer creation in milliseconds since epoch. fingerprint: anyOf: - type: string - type: "null" description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID. env: enum: - sandbox - live description: The environment this customer was created in. metadata: type: object propertyNames: {} additionalProperties: {} description: The metadata for the customer. send_email_receipts: type: boolean description: Whether to send email receipts to the customer. subscriptions: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" plan_id: type: string auto_enable: type: boolean add_on: type: boolean status: enum: - active - scheduled - expired past_due: type: boolean canceled_at: anyOf: - type: number - type: "null" expires_at: anyOf: - type: number - type: "null" trial_ends_at: anyOf: - type: number - type: "null" started_at: type: number current_period_start: anyOf: - type: number - type: "null" current_period_end: anyOf: - type: number - type: "null" quantity: type: number required: - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" plan_id: type: string expires_at: anyOf: - type: number - type: "null" started_at: type: number quantity: type: number required: - plan_id - expires_at - started_at - quantity balances: type: object propertyNames: type: string additionalProperties: type: object properties: feature_id: type: string feature: type: object properties: id: type: string name: type: string type: enum: - boolean - metered - credit_system consumable: type: boolean event_names: type: array items: type: string credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost display: type: object properties: singular: anyOf: - type: string - type: "null" plural: anyOf: - type: string - type: "null" archived: type: boolean required: - id - name - type - consumable - archived granted: type: number remaining: type: number minimum: 0 usage: type: number unlimited: type: boolean overage_allowed: type: boolean max_purchase: anyOf: - type: number - type: "null" next_reset_at: anyOf: - type: number - type: "null" breakdown: type: array items: type: object properties: id: type: string default: "" plan_id: anyOf: - type: string - type: "null" included_grant: type: number prepaid_grant: type: number remaining: type: number usage: type: number unlimited: type: boolean reset: anyOf: - type: object properties: interval: anyOf: - enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year - const: multiple interval_count: type: number resets_at: anyOf: - type: number - type: "null" required: - interval - resets_at - type: "null" price: anyOf: - type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - {} - {} amount: type: number required: - amount billing_units: type: number billing_method: enum: - prepaid - usage_based max_purchase: anyOf: - type: number - type: "null" required: - billing_units - billing_method - max_purchase - type: "null" expires_at: anyOf: - type: number - type: "null" required: - plan_id - included_grant - prepaid_grant - remaining - usage - unlimited - reset - price - expires_at rollovers: type: array items: type: object properties: balance: type: number expires_at: type: number required: - balance - expires_at required: - feature_id - granted - remaining - usage - unlimited - overage_allowed - max_purchase - next_reset_at required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - subscriptions - purchases - balances description: Array of items for current page has_more: type: boolean description: Whether more results exist after this page offset: type: number description: Current offset position limit: type: number description: Limit passed in the request total: type: number description: Total number of items returned in the current page required: - list - has_more - offset - limit - total x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.customers.list({}); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.customers.list(request={}) /v1/customers.update: post: operationId: updateCustomer description: Updates an existing customer by ID. tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string title: CustomerId description: ID of the customer to update name: anyOf: - type: string - type: "null" description: Customer's name email: anyOf: - type: string format: email - type: "null" description: Customer's email address fingerprint: anyOf: - type: string - type: "null" description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" description: Additional metadata for the customer stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID if you already have one send_email_receipts: type: boolean description: Whether to send email receipts to this customer new_customer_id: $ref: "#/components/schemas/CustomerId" description: New ID for the customer required: - customer_id title: UpdateCustomerParams examples: - &a4 customer_id: cus_123 name: Jane Doe email: jane@example.com example: *a4 responses: "200": description: OK content: application/json: schema: type: object properties: id: anyOf: - type: string - type: "null" description: Your unique identifier for the customer. name: anyOf: - type: string - type: "null" description: The name of the customer. email: anyOf: - type: string - type: "null" description: The email address of the customer. created_at: type: number description: Timestamp of customer creation in milliseconds since epoch. fingerprint: anyOf: - type: string - type: "null" description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." stripe_id: anyOf: - type: string - type: "null" description: Stripe customer ID. env: enum: - sandbox - live description: The environment this customer was created in. metadata: type: object propertyNames: {} additionalProperties: {} description: The metadata for the customer. send_email_receipts: type: boolean description: Whether to send email receipts to the customer. subscriptions: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" plan_id: type: string auto_enable: type: boolean add_on: type: boolean status: enum: - active - scheduled - expired past_due: type: boolean canceled_at: anyOf: - type: number - type: "null" expires_at: anyOf: - type: number - type: "null" trial_ends_at: anyOf: - type: number - type: "null" started_at: type: number current_period_start: anyOf: - type: number - type: "null" current_period_end: anyOf: - type: number - type: "null" quantity: type: number required: - plan_id - auto_enable - add_on - status - past_due - canceled_at - expires_at - trial_ends_at - started_at - current_period_start - current_period_end - quantity purchases: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" plan_id: type: string expires_at: anyOf: - type: number - type: "null" started_at: type: number quantity: type: number required: - plan_id - expires_at - started_at - quantity balances: type: object propertyNames: type: string additionalProperties: type: object properties: feature_id: type: string feature: type: object properties: id: type: string name: type: string type: enum: - boolean - metered - credit_system consumable: type: boolean event_names: type: array items: type: string credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost display: type: object properties: singular: anyOf: - type: string - type: "null" plural: anyOf: - type: string - type: "null" archived: type: boolean required: - id - name - type - consumable - archived granted: type: number remaining: type: number minimum: 0 usage: type: number unlimited: type: boolean overage_allowed: type: boolean max_purchase: anyOf: - type: number - type: "null" next_reset_at: anyOf: - type: number - type: "null" breakdown: type: array items: type: object properties: id: type: string default: "" plan_id: anyOf: - type: string - type: "null" included_grant: type: number prepaid_grant: type: number remaining: type: number usage: type: number unlimited: type: boolean reset: anyOf: - type: object properties: interval: anyOf: - enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year - const: multiple interval_count: type: number resets_at: anyOf: - type: number - type: "null" required: - interval - resets_at - type: "null" price: anyOf: - type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount billing_units: type: number billing_method: enum: - prepaid - usage_based max_purchase: anyOf: - type: number - type: "null" required: - billing_units - billing_method - max_purchase - type: "null" expires_at: anyOf: - type: number - type: "null" required: - plan_id - included_grant - prepaid_grant - remaining - usage - unlimited - reset - price - expires_at rollovers: type: array items: type: object properties: balance: type: number expires_at: type: number required: - balance - expires_at required: - feature_id - granted - remaining - usage - unlimited - overage_allowed - max_purchase - next_reset_at required: - id - name - email - created_at - fingerprint - stripe_id - env - metadata - send_email_receipts - subscriptions - purchases - balances x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.customers.update({ customerId: "cus_123", name: "Jane Doe", email: "jane@example.com", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.customers.update( customer_id="cus_123", name="Jane Doe", email="jane@example.com", ) /v1/customers.delete: post: operationId: deleteCustomer description: Deletes a customer by ID. tags: - customers requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string title: CustomerId description: ID of the customer to delete delete_in_stripe: type: boolean default: false description: Whether to also delete the customer in Stripe required: - customer_id title: DeleteCustomerParams examples: - &a5 customer_id: cus_123 delete_in_stripe: false example: *a5 responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: delete parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.customers.delete({ customerId: "cus_123", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.customers.delete( customer_id="cus_123", delete_in_stripe=False, ) /v1/plans.list: post: operationId: listPlans summary: List all plans tags: - plans requestBody: required: false content: application/json: schema: type: object properties: customer_id: type: string entity_id: type: string include_archived: type: boolean responses: "200": description: OK content: application/json: schema: type: object properties: list: type: array items: $ref: "#/components/schemas/Plan" required: - list x-speakeasy-name-override: list parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.plans.list(); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.plans.list() /v1/billing.attach: post: operationId: billingAttach description: Attaches a plan to a customer. Handles new subscriptions, upgrades and downgrades. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: anyOf: - type: string - type: "null" description: The ID of the entity to attach the plan to. feature_quantities: anyOf: - type: array items: type: object properties: feature_id: type: string quantity: type: number minimum: 0 adjustable: type: boolean required: - feature_id - type: "null" description: 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: type: number description: The version of the plan to attach. free_trial: anyOf: - type: object properties: duration_length: type: number duration_type: enum: - day - month - year default: month card_required: type: boolean default: true required: - duration_length - type: "null" customize: type: object properties: price: anyOf: - type: object properties: amount: type: number interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number required: - amount - interval - type: "null" items: type: array items: type: object properties: feature_id: type: string included: type: number unlimited: type: boolean reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year interval_count: type: number required: - interval price: type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number default: 1 billing_units: type: number default: 1 billing_method: enum: - prepaid - usage_based max_purchase: type: number required: - interval - billing_method proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations required: - on_increase - on_decrease rollover: type: object properties: max: type: number expiry_duration_type: enum: - month - forever expiry_duration_length: type: number required: - expiry_duration_type required: - feature_id description: Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. plan_id: type: string invoice_mode: type: object properties: enabled: type: boolean enable_plan_immediately: type: boolean default: false finalize: type: boolean default: true required: - enabled discounts: type: array items: anyOf: - type: object properties: reward_id: type: string required: - reward_id - type: object properties: promotion_code: type: string required: - promotion_code redirect_mode: enum: - always - if_required - never default: always success_url: type: string new_billing_subscription: type: boolean plan_schedule: enum: - immediate - end_of_cycle billing_behavior: enum: - prorate_immediately - next_cycle_only required: - customer_id - plan_id responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string entity_id: type: string invoice: type: object properties: status: anyOf: - type: string - type: "null" stripe_id: type: string total: type: number currency: type: string hosted_invoice_url: anyOf: - type: string - type: "null" required: - status - stripe_id - total - currency - hosted_invoice_url payment_url: anyOf: - type: string - type: "null" required_action: type: object properties: code: enum: - 3ds_required - payment_method_required - payment_failed reason: type: string required: - code - reason required: - customer_id - payment_url x-speakeasy-name-override: attach parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.attach({ customerId: "", planId: "", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.attach( customer_id="", plan_id="", redirect_mode="always", ) /v1/billing.preview_attach: post: operationId: billingPreviewAttach description: Preview billing changes before attaching a plan. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: anyOf: - type: string - type: "null" description: The ID of the entity to attach the plan to. feature_quantities: anyOf: - type: array items: type: object properties: feature_id: type: string quantity: type: number minimum: 0 adjustable: type: boolean required: - feature_id - type: "null" description: 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: type: number description: The version of the plan to attach. free_trial: anyOf: - type: object properties: duration_length: type: number duration_type: enum: - day - month - year default: month card_required: type: boolean default: true required: - duration_length - type: "null" customize: type: object properties: price: anyOf: - type: object properties: amount: type: number interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number required: - amount - interval - type: "null" items: type: array items: type: object properties: feature_id: type: string included: type: number unlimited: type: boolean reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year interval_count: type: number required: - interval price: type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number default: 1 billing_units: type: number default: 1 billing_method: enum: - prepaid - usage_based max_purchase: type: number required: - interval - billing_method proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations required: - on_increase - on_decrease rollover: type: object properties: max: type: number expiry_duration_type: enum: - month - forever expiry_duration_length: type: number required: - expiry_duration_type required: - feature_id description: Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. plan_id: type: string invoice_mode: type: object properties: enabled: type: boolean enable_plan_immediately: type: boolean default: false finalize: type: boolean default: true required: - enabled discounts: type: array items: anyOf: - type: object properties: reward_id: type: string required: - reward_id - type: object properties: promotion_code: type: string required: - promotion_code redirect_mode: enum: - always - if_required - never default: always success_url: type: string new_billing_subscription: type: boolean plan_schedule: enum: - immediate - end_of_cycle billing_behavior: enum: - prorate_immediately - next_cycle_only required: - customer_id - plan_id responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string line_items: type: array items: type: object properties: title: type: string description: type: string amount: type: number discounts: type: array items: type: object properties: amountOff: type: number percentOff: type: number stripeCouponId: type: string couponName: type: string required: - amountOff default: [] plan_id: type: string total_quantity: type: number paid_quantity: type: number deferred_for_trial: type: boolean effective_period: type: object properties: start: type: number end: type: number required: - start - end is_base: type: boolean required: - title - description - amount - plan_id - total_quantity - paid_quantity total: type: number currency: type: string period_start: type: number period_end: type: number next_cycle: type: object properties: starts_at: type: number total: type: number line_items: type: array items: type: object properties: title: type: string description: type: string amount: type: number discounts: type: array items: type: object properties: amountOff: type: number percentOff: type: number stripeCouponId: type: string couponName: type: string required: - amountOff default: [] plan_id: type: string total_quantity: type: number paid_quantity: type: number deferred_for_trial: type: boolean effective_period: type: object properties: start: type: number end: type: number required: - start - end is_base: type: boolean required: - title - description - amount - plan_id - total_quantity - paid_quantity required: - starts_at - total - line_items incoming: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" feature_quantities: type: array items: type: object properties: feature_id: type: string quantity: type: number required: - feature_id - quantity balances: type: object propertyNames: type: string additionalProperties: type: object properties: feature_id: type: string feature: type: object properties: id: type: string name: type: string type: enum: - boolean - metered - credit_system consumable: type: boolean event_names: type: array items: type: string credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost display: type: object properties: singular: anyOf: - type: string - type: "null" plural: anyOf: - type: string - type: "null" archived: type: boolean required: - id - name - type - consumable - archived granted: type: number remaining: type: number minimum: 0 usage: type: number unlimited: type: boolean overage_allowed: type: boolean max_purchase: anyOf: - type: number - type: "null" next_reset_at: anyOf: - type: number - type: "null" breakdown: type: array items: type: object properties: id: type: string default: "" plan_id: anyOf: - type: string - type: "null" included_grant: type: number prepaid_grant: type: number remaining: type: number usage: type: number unlimited: type: boolean reset: anyOf: - type: object properties: interval: anyOf: - enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year - const: multiple interval_count: type: number resets_at: anyOf: - type: number - type: "null" required: - interval - resets_at - type: "null" price: anyOf: - type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - {} - {} amount: type: number required: - amount billing_units: type: number billing_method: enum: - prepaid - usage_based max_purchase: anyOf: - type: number - type: "null" required: - billing_units - billing_method - max_purchase - type: "null" expires_at: anyOf: - type: number - type: "null" required: - plan_id - included_grant - prepaid_grant - remaining - usage - unlimited - reset - price - expires_at rollovers: type: array items: type: object properties: balance: type: number expires_at: type: number required: - balance - expires_at required: - feature_id - granted - remaining - usage - unlimited - overage_allowed - max_purchase - next_reset_at period_start: type: number period_end: type: number required: - plan - feature_quantities - balances outgoing: type: array items: type: object properties: plan: $ref: "#/components/schemas/Plan" feature_quantities: type: array items: type: object properties: feature_id: type: string quantity: type: number required: - feature_id - quantity balances: type: object propertyNames: type: string additionalProperties: type: object properties: feature_id: type: string feature: type: object properties: id: type: string name: type: string type: enum: - boolean - metered - credit_system consumable: type: boolean event_names: type: array items: type: string credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost display: type: object properties: singular: anyOf: - type: string - type: "null" plural: anyOf: - type: string - type: "null" archived: type: boolean required: - id - name - type - consumable - archived granted: type: number remaining: type: number minimum: 0 usage: type: number unlimited: type: boolean overage_allowed: type: boolean max_purchase: anyOf: - type: number - type: "null" next_reset_at: anyOf: - type: number - type: "null" breakdown: type: array items: type: object properties: id: type: string default: "" plan_id: anyOf: - type: string - type: "null" included_grant: type: number prepaid_grant: type: number remaining: type: number usage: type: number unlimited: type: boolean reset: anyOf: - type: object properties: interval: anyOf: - enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year - const: multiple interval_count: type: number resets_at: anyOf: - type: number - type: "null" required: - interval - resets_at - type: "null" price: anyOf: - type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - {} - {} amount: type: number required: - amount billing_units: type: number billing_method: enum: - prepaid - usage_based max_purchase: anyOf: - type: number - type: "null" required: - billing_units - billing_method - max_purchase - type: "null" expires_at: anyOf: - type: number - type: "null" required: - plan_id - included_grant - prepaid_grant - remaining - usage - unlimited - reset - price - expires_at rollovers: type: array items: type: object properties: balance: type: number expires_at: type: number required: - balance - expires_at required: - feature_id - granted - remaining - usage - unlimited - overage_allowed - max_purchase - next_reset_at period_start: type: number period_end: type: number required: - plan - feature_quantities - balances redirect_type: anyOf: - enum: - stripe_checkout - autumn_checkout - type: "null" required: - customer_id - line_items - total - currency - incoming - outgoing - redirect_type x-speakeasy-name-override: previewAttach parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.previewAttach({ customerId: "", planId: "", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.preview_attach( customer_id="", plan_id="", redirect_mode="always", ) /v1/billing.update: post: operationId: billingUpdate description: Update an existing subscription. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: anyOf: - type: string - type: "null" description: The ID of the entity to attach the plan to. feature_quantities: anyOf: - type: array items: type: object properties: feature_id: type: string quantity: type: number minimum: 0 adjustable: type: boolean required: - feature_id - type: "null" description: 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: type: number description: The version of the plan to attach. free_trial: anyOf: - type: object properties: duration_length: type: number duration_type: enum: - day - month - year default: month card_required: type: boolean default: true required: - duration_length - type: "null" customize: type: object properties: price: anyOf: - type: object properties: amount: type: number interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number required: - amount - interval - type: "null" items: type: array items: type: object properties: feature_id: type: string included: type: number unlimited: type: boolean reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year interval_count: type: number required: - interval price: type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number default: 1 billing_units: type: number default: 1 billing_method: enum: - prepaid - usage_based max_purchase: type: number required: - interval - billing_method proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations required: - on_increase - on_decrease rollover: type: object properties: max: type: number expiry_duration_type: enum: - month - forever expiry_duration_length: type: number required: - expiry_duration_type required: - feature_id description: Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. plan_id: type: string invoice_mode: type: object properties: enabled: type: boolean enable_plan_immediately: type: boolean default: false finalize: type: boolean default: true required: - enabled cancel_action: enum: - cancel_immediately - cancel_end_of_cycle - uncancel billing_behavior: enum: - prorate_immediately - next_cycle_only required: - customer_id responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string entity_id: type: string invoice: type: object properties: status: anyOf: - type: string - type: "null" stripe_id: type: string total: type: number currency: type: string hosted_invoice_url: anyOf: - type: string - type: "null" required: - status - stripe_id - total - currency - hosted_invoice_url payment_url: anyOf: - type: string - type: "null" required_action: type: object properties: code: enum: - 3ds_required - payment_method_required - payment_failed reason: type: string required: - code - reason required: - customer_id - payment_url x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.update({ customerId: "", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.update(customer_id="") /v1/billing.preview_update: post: operationId: billingPreviewUpdate description: Preview billing changes before updating a subscription. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer to attach the plan to. entity_id: anyOf: - type: string - type: "null" description: The ID of the entity to attach the plan to. feature_quantities: anyOf: - type: array items: type: object properties: feature_id: type: string quantity: type: number minimum: 0 adjustable: type: boolean required: - feature_id - type: "null" description: 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: type: number description: The version of the plan to attach. free_trial: anyOf: - type: object properties: duration_length: type: number duration_type: enum: - day - month - year default: month card_required: type: boolean default: true required: - duration_length - type: "null" customize: type: object properties: price: anyOf: - type: object properties: amount: type: number interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number required: - amount - interval - type: "null" items: type: array items: type: object properties: feature_id: type: string included: type: number unlimited: type: boolean reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year interval_count: type: number required: - interval price: type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount interval: enum: - one_off - week - month - quarter - semi_annual - year interval_count: type: number default: 1 billing_units: type: number default: 1 billing_method: enum: - prepaid - usage_based max_purchase: type: number required: - interval - billing_method proration: type: object properties: on_increase: enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle on_decrease: enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations required: - on_increase - on_decrease rollover: type: object properties: max: type: number expiry_duration_type: enum: - month - forever expiry_duration_length: type: number required: - expiry_duration_type required: - feature_id description: Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both. plan_id: type: string invoice_mode: type: object properties: enabled: type: boolean enable_plan_immediately: type: boolean default: false finalize: type: boolean default: true required: - enabled cancel_action: enum: - cancel_immediately - cancel_end_of_cycle - uncancel billing_behavior: enum: - prorate_immediately - next_cycle_only required: - customer_id responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string line_items: type: array items: type: object properties: title: type: string description: type: string amount: type: number discounts: type: array items: type: object properties: amountOff: type: number percentOff: type: number stripeCouponId: type: string couponName: type: string required: - amountOff default: [] plan_id: type: string total_quantity: type: number paid_quantity: type: number deferred_for_trial: type: boolean effective_period: type: object properties: start: type: number end: type: number required: - start - end is_base: type: boolean required: - title - description - amount - plan_id - total_quantity - paid_quantity total: type: number currency: type: string period_start: type: number period_end: type: number next_cycle: type: object properties: starts_at: type: number total: type: number line_items: type: array items: type: object properties: title: type: string description: type: string amount: type: number discounts: type: array items: type: object properties: amountOff: type: number percentOff: type: number stripeCouponId: type: string couponName: type: string required: - amountOff default: [] plan_id: type: string total_quantity: type: number paid_quantity: type: number deferred_for_trial: type: boolean effective_period: type: object properties: start: type: number end: type: number required: - start - end is_base: type: boolean required: - title - description - amount - plan_id - total_quantity - paid_quantity required: - starts_at - total - line_items required: - customer_id - line_items - total - currency x-speakeasy-name-override: previewUpdate parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.previewUpdate({ customerId: "", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.preview_update(customer_id="") /v1/billing.setup_payment: post: operationId: billingSetupPayment description: Create a setup payment session for a customer. tags: - billing requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer success_url: type: string description: URL to redirect to after successful payment setup. Must start with either http:// or https:// customer_data: $ref: "#/components/schemas/CustomerData" checkout_session_params: type: object propertyNames: type: string additionalProperties: {} description: Additional parameters for the checkout session required: - customer_id responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer url: type: string description: URL to the payment setup page required: - customer_id - url x-speakeasy-name-override: setupPayment parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.billing.setupPayment({ customerId: "", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.billing.setup_payment(customer_id="") /v1/balances.create: post: operationId: balancesCreate description: Create a balance for a customer feature. tags: - balances requestBody: required: true content: application/json: schema: type: object properties: feature_id: type: string description: The feature ID to create the balance for customer_id: type: string description: The customer ID to assign the balance to entity_id: type: string description: Entity ID for entity-scoped balances included: type: number description: The initial balance amount to grant unlimited: type: boolean description: Whether the balance is unlimited reset: type: object properties: interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year interval_count: type: number required: - interval description: Reset configuration for the balance expires_at: type: number description: Unix timestamp (milliseconds) when the balance expires granted_balance: type: number required: - feature_id - customer_id responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: create parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.create({ featureId: "", customerId: "", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.create( feature_id="", customer_id="", ) /v1/balances.update: post: operationId: balancesUpdate description: Update a customer balance. tags: - balances requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer. entity_id: type: string description: The ID of the entity to update balance for (if using entity balances). feature_id: type: string description: The ID of the feature to update balance for. current_balance: type: number description: The new balance value to set. interval: enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year description: The interval to update balance for. granted_balance: type: number usage: type: number customer_entitlement_id: type: string next_reset_at: type: number add_to_balance: type: number required: - customer_id - feature_id responses: "200": description: OK content: application/json: schema: type: object properties: success: type: boolean required: - success x-speakeasy-name-override: update parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.update({ customerId: "", featureId: "", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.update( customer_id="", feature_id="", ) /v1/balances.check: post: operationId: balancesCheck description: Check whether usage is allowed for a customer feature. tags: - balances requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string description: ID which you provided when creating the customer feature_id: type: string description: ID of the feature to check access to. entity_id: type: string description: If using entity balances (eg, seats), the entity ID to check access for. required_balance: type: number description: If you know the amount of the feature the end user is consuming in advance. If their balance is below this quantity, allowed will be false. properties: type: object propertyNames: type: string additionalProperties: {} send_event: type: boolean description: If true, a usage event will be recorded together with checking access. The required_balance field will be used as the usage value. with_preview: type: boolean description: If true, the response will include a preview object, which can be used to display information such as a paywall or upgrade confirmation. required: - customer_id - feature_id responses: "200": description: OK content: application/json: schema: type: object properties: allowed: type: boolean customer_id: type: string entity_id: anyOf: - type: string - type: "null" required_balance: type: number balance: anyOf: - type: object properties: feature_id: type: string feature: type: object properties: id: type: string name: type: string type: enum: - boolean - metered - credit_system consumable: type: boolean event_names: type: array items: type: string credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost display: type: object properties: singular: anyOf: - type: string - type: "null" plural: anyOf: - type: string - type: "null" archived: type: boolean required: - id - name - type - consumable - archived granted: type: number remaining: type: number minimum: 0 usage: type: number unlimited: type: boolean overage_allowed: type: boolean max_purchase: anyOf: - type: number - type: "null" next_reset_at: anyOf: - type: number - type: "null" breakdown: type: array items: type: object properties: id: type: string default: "" plan_id: anyOf: - type: string - type: "null" included_grant: type: number prepaid_grant: type: number remaining: type: number usage: type: number unlimited: type: boolean reset: anyOf: - type: object properties: interval: anyOf: - enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year - const: multiple interval_count: type: number resets_at: anyOf: - type: number - type: "null" required: - interval - resets_at - type: "null" price: anyOf: - type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount billing_units: type: number billing_method: enum: - prepaid - usage_based max_purchase: anyOf: - type: number - type: "null" required: - billing_units - billing_method - max_purchase - type: "null" expires_at: anyOf: - type: number - type: "null" required: - plan_id - included_grant - prepaid_grant - remaining - usage - unlimited - reset - price - expires_at rollovers: type: array items: type: object properties: balance: type: number expires_at: type: number required: - balance - expires_at required: - feature_id - granted - remaining - usage - unlimited - overage_allowed - max_purchase - next_reset_at - type: "null" preview: type: object properties: scenario: enum: - usage_limit - feature_flag title: type: string message: type: string feature_id: type: string feature_name: type: string products: type: array items: type: object properties: id: type: string description: The ID of the product you set when creating the product name: type: string description: The name of the product group: anyOf: - type: string - type: "null" description: Product group which this product belongs to env: enum: - sandbox - live description: The environment of the product is_add_on: type: boolean description: Whether the product is an add-on and can be purchased alongside other products is_default: type: boolean description: Whether the product is the default product archived: type: boolean description: Whether this product has been archived and is no longer available version: type: number description: The current version of the product created_at: type: number description: The timestamp of when the product was created in milliseconds since epoch items: type: array items: type: object properties: type: anyOf: - enum: - feature - priced_feature - price - type: "null" description: The type of the product item feature_id: anyOf: - type: string - type: "null" description: The feature ID of the product item. If the item is a fixed price, should be `null` feature_type: anyOf: - enum: - single_use - continuous_use - boolean - static - type: "null" description: Single use features are used once and then depleted, like API calls or credits. Continuous use features are those being used on an ongoing-basis, like storage or seats. included_usage: anyOf: - anyOf: - type: number - const: inf - type: "null" description: The amount of usage included for this feature. interval: anyOf: - enum: - minute - hour - day - week - month - quarter - semi_annual - year - type: "null" description: The reset or billing interval of the product item. If null, feature will have no reset date, and if there's a price, it will be billed one-off. interval_count: anyOf: - type: number - type: "null" description: The interval count of the product item. price: anyOf: - type: number - type: "null" description: The price of the product item. Should be `null` if tiered pricing is set. tiers: anyOf: - type: array items: type: object properties: to: anyOf: - type: number - const: inf description: The maximum amount of usage for this tier. amount: type: number description: The price of the product item for this tier. required: - to - amount - type: "null" description: Tiered pricing for the product item. Not applicable for fixed price items. usage_model: anyOf: - enum: - prepaid - pay_per_use - type: "null" description: Whether the feature should be prepaid upfront or billed for how much they use end of billing period. billing_units: anyOf: - type: number - type: "null" description: The amount per billing unit (eg. $9 / 250 units) reset_usage_when_enabled: anyOf: - type: boolean - type: "null" description: Whether the usage should be reset when the product is enabled. entity_feature_id: anyOf: - type: string - type: "null" description: The entity feature ID of the product item if applicable. display: anyOf: - type: object properties: primary_text: type: string secondary_text: anyOf: - type: string - type: "null" required: - primary_text - type: "null" description: The display of the product item. quantity: anyOf: - type: number - type: "null" description: Used in customer context. Quantity of the feature the customer has prepaid for. next_cycle_quantity: anyOf: - type: number - type: "null" description: Used in customer context. Quantity of the feature the customer will prepay for in the next cycle. config: anyOf: - type: object properties: rollover: anyOf: - type: object properties: max: anyOf: - type: number - type: "null" duration: enum: - month - forever default: month length: type: number required: - max - length - type: "null" on_increase: anyOf: - enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle - type: "null" on_decrease: anyOf: - enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations - type: "null" - type: "null" description: Configuration for rollover and proration behavior of the feature. description: Product item defining features and pricing within a product description: Array of product items that define the product's features and pricing free_trial: anyOf: - type: object properties: duration: enum: - day - month - year description: The duration type of the free trial length: type: number description: The length of the duration type specified unique_fingerprint: type: boolean description: Whether the free trial is limited to one per customer fingerprint card_required: type: boolean description: Whether the free trial requires a card. If false, the customer can attach the product without going through a checkout flow or having a card on file. trial_available: anyOf: - type: boolean default: true - type: "null" description: Used in customer context. Whether the free trial is available for the customer if they were to attach the product. required: - duration - length - unique_fingerprint - card_required - type: "null" description: Free trial configuration for this product, if available base_variant_id: anyOf: - type: string - type: "null" description: ID of the base variant this product is derived from scenario: enum: - scheduled - active - new - renew - upgrade - downgrade - cancel - expired - past_due description: Scenario for when this product is used in attach flows properties: type: object properties: is_free: type: boolean description: True if the product has no base price or usage prices is_one_off: type: boolean description: True if the product only contains a one-time price interval_group: anyOf: - type: string - type: "null" description: The billing interval group for recurring products (e.g., 'monthly', 'yearly') has_trial: anyOf: - type: boolean - type: "null" description: True if the product includes a free trial updateable: anyOf: - type: boolean - type: "null" description: True if the product can be updated after creation (only applicable if there are prepaid recurring prices) required: - is_free - is_one_off required: - id - name - group - env - is_add_on - is_default - archived - version - created_at - items - free_trial - base_variant_id required: - scenario - title - message - feature_id - feature_name - products required: - allowed - customer_id - balance x-speakeasy-name-override: check parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.check({ customerId: "", featureId: "", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.check( customer_id="", feature_id="", ) /v1/balances.track: post: operationId: balancesTrack description: Track usage for a customer feature. tags: - balances requestBody: required: true content: application/json: schema: type: object properties: customer_id: type: string minLength: 1 description: ID which you provided when creating the customer feature_id: type: string description: ID of the feature to track usage for. Required if event_name is not provided. Use this for direct feature tracking. event_name: type: string minLength: 1 description: An [event name](/features/tracking-usage#using-event-names) can be used in place of feature_id. This can be used if multiple features are tracked in the same event. value: type: number description: The amount of usage to record. Defaults to 1. Can be negative to increase the balance (e.g., when removing a seat). properties: type: object propertyNames: type: string additionalProperties: {} description: Additional properties to attach to this usage event. idempotency_key: type: string description: Unique key to prevent duplicate event recording. Use this to safely retry requests without creating duplicate usage records. entity_id: type: string description: If using [entity balances](/features/feature-entities) (eg, seats), the entity ID to track usage for. required: - customer_id responses: "200": description: OK content: application/json: schema: type: object properties: customer_id: type: string description: The ID of the customer entity_id: type: string description: The ID of the entity (if provided) event_name: type: string description: The name of the event value: type: number balance: anyOf: - type: object properties: feature_id: type: string feature: type: object properties: id: type: string name: type: string type: enum: - boolean - metered - credit_system consumable: type: boolean event_names: type: array items: type: string credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost display: type: object properties: singular: anyOf: - type: string - type: "null" plural: anyOf: - type: string - type: "null" archived: type: boolean required: - id - name - type - consumable - archived granted: type: number remaining: type: number minimum: 0 usage: type: number unlimited: type: boolean overage_allowed: type: boolean max_purchase: anyOf: - type: number - type: "null" next_reset_at: anyOf: - type: number - type: "null" breakdown: type: array items: type: object properties: id: type: string default: "" plan_id: anyOf: - type: string - type: "null" included_grant: type: number prepaid_grant: type: number remaining: type: number usage: type: number unlimited: type: boolean reset: anyOf: - type: object properties: interval: anyOf: - enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year - const: multiple interval_count: type: number resets_at: anyOf: - type: number - type: "null" required: - interval - resets_at - type: "null" price: anyOf: - type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount billing_units: type: number billing_method: enum: - prepaid - usage_based max_purchase: anyOf: - type: number - type: "null" required: - billing_units - billing_method - max_purchase - type: "null" expires_at: anyOf: - type: number - type: "null" required: - plan_id - included_grant - prepaid_grant - remaining - usage - unlimited - reset - price - expires_at rollovers: type: array items: type: object properties: balance: type: number expires_at: type: number required: - balance - expires_at required: - feature_id - granted - remaining - usage - unlimited - overage_allowed - max_purchase - next_reset_at - type: "null" balances: type: object propertyNames: type: string additionalProperties: type: object properties: feature_id: type: string feature: type: object properties: id: type: string name: type: string type: enum: - boolean - metered - credit_system consumable: type: boolean event_names: type: array items: type: string credit_schema: type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost display: type: object properties: singular: anyOf: - type: string - type: "null" plural: anyOf: - type: string - type: "null" archived: type: boolean required: - id - name - type - consumable - archived granted: type: number remaining: type: number minimum: 0 usage: type: number unlimited: type: boolean overage_allowed: type: boolean max_purchase: anyOf: - type: number - type: "null" next_reset_at: anyOf: - type: number - type: "null" breakdown: type: array items: type: object properties: id: type: string default: "" plan_id: anyOf: - type: string - type: "null" included_grant: type: number prepaid_grant: type: number remaining: type: number usage: type: number unlimited: type: boolean reset: anyOf: - type: object properties: interval: anyOf: - enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year - const: multiple interval_count: type: number resets_at: anyOf: - type: number - type: "null" required: - interval - resets_at - type: "null" price: anyOf: - type: object properties: amount: type: number tiers: type: array items: type: object properties: to: anyOf: - type: number - const: inf amount: type: number required: - to - amount billing_units: type: number billing_method: enum: - prepaid - usage_based max_purchase: anyOf: - type: number - type: "null" required: - billing_units - billing_method - max_purchase - type: "null" expires_at: anyOf: - type: number - type: "null" required: - plan_id - included_grant - prepaid_grant - remaining - usage - unlimited - reset - price - expires_at rollovers: type: array items: type: object properties: balance: type: number expires_at: type: number required: - balance - expires_at required: - feature_id - granted - remaining - usage - unlimited - overage_allowed - max_purchase - next_reset_at required: - customer_id - value - balance x-speakeasy-name-override: track parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true x-codeSamples: - lang: typescript label: Typescript (SDK) source: |- import { Autumn } from 'autumn-js' const autumn = new Autumn() const result = await autumn.balances.track({ customerId: "", }); - lang: python label: Python (SDK) source: |- from autumn_sdk import Autumn autumn = Autumn(secret_key="am_sk_test...") res = autumn.balances.track(customer_id="") security: - secretKey: [] x-speakeasy-globals: parameters: - name: x-api-version in: header required: true schema: type: string default: "2.1" x-speakeasy-globals-hidden: true