openapi: 3.1.0 info: title: Autumn API version: 1.2.0 servers: - url: https://api.useautumn.com/v1 description: Production server security: - secretKey: [] paths: /products: get: summary: List Products tags: - products responses: "200": description: "" content: application/json: schema: type: object properties: list: type: array items: $ref: "#/components/schemas/Product" required: - list additionalProperties: false x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.products.list(); post: summary: Create Product tags: - products requestBody: content: application/json: schema: type: object properties: id: description: The ID of the product. Used to identify the product in other API calls like checkout or update product. type: string pattern: ^[a-zA-Z0-9_-]+$ name: description: The name of the product type: string description: description: The description of the product anyOf: - type: string - type: "null" is_add_on: description: Whether the product is an add-on. Add-on products can be attached multiple times and don't to through upgrade / downgrade flows. default: false type: boolean is_default: description: Whether the product is the default product. Default products are enabled by default for new customers. default: false type: boolean group: description: Product group which this product belongs to. Products within a group have upgrade / downgrade logic when the customer moves between them. anyOf: - type: string - type: "null" items: description: Array of product items that define the product's features and pricing type: array items: type: object properties: type: description: The type of the product item. anyOf: - type: string enum: - feature - priced_feature - price - type: "null" feature_id: description: The feature ID of the product item. Should be null for fixed price items. anyOf: - type: string - type: "null" included_usage: description: The amount of usage included for this feature (per interval). anyOf: - anyOf: - type: number - type: string const: inf - type: "null" interval: 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. anyOf: - type: string enum: - minute - hour - day - week - month - quarter - semi_annual - year - type: "null" interval_count: description: Interval count of the feature. anyOf: - type: number - type: "null" entity_feature_id: description: The feature ID of the entity (like seats) to track sub-balances for. anyOf: - type: string - type: "null" usage_model: description: Whether the feature should be prepaid upfront or billed for how much they use end of billing period. anyOf: - type: string enum: - prepaid - pay_per_use - type: "null" price: description: The price of the product item. Should be null if tiered pricing is set. anyOf: - type: number - type: "null" tiers: description: Tiered pricing for the product item. Not applicable for fixed price items. anyOf: - type: array items: type: object properties: to: description: The maximum amount of usage for this tier. example: 100 anyOf: - type: number - type: string const: inf amount: description: The price of the product item for this tier. example: 10 type: number required: - to - amount - type: "null" billing_units: description: The billing units of the product item (eg $1 for 30 credits). anyOf: - type: number - type: "null" reset_usage_when_enabled: description: Whether the usage should be reset when the product is enabled. anyOf: - type: boolean - type: "null" required: - interval free_trial: description: Free trial configuration for this product, if available anyOf: - $ref: "#/components/schemas/FreeTrialConfig" - type: "null" required: - id - name responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Product" x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.products.create({ id: 'id', name: 'name' }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) product = autumn.products.create( id="id", name="name", ) print(product.id) /products/{product_id}: get: summary: Get Product tags: - products parameters: - in: path name: product_id schema: type: string required: true responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Product" x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.products.get('product_id'); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) product = autumn.products.get( "product_id", ) print(product.id) post: summary: Update Product tags: - products parameters: - in: path name: product_id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: id: description: The ID of the product. Used to identify the product in other API calls like checkout or update product. type: string pattern: ^[a-zA-Z0-9_-]+$ name: description: The name of the product type: string is_add_on: description: Whether the product is an add-on. Add-on products can be attached multiple times and don't to through upgrade / downgrade flows. type: boolean is_default: description: Whether the product is the default product. Default products are enabled by default for new customers. type: boolean description: description: The description of the product anyOf: - type: string - type: "null" group: description: Product group which this product belongs to. Products within a group have upgrade / downgrade logic when the customer moves between them. anyOf: - type: string - type: "null" archived: description: Archive this product using this flag. Archived products are hidden on the dashboard. type: boolean items: type: array items: type: object properties: type: description: The type of the product item. anyOf: - type: string enum: - feature - priced_feature - price - type: "null" feature_id: description: The feature ID of the product item. Should be null for fixed price items. anyOf: - type: string - type: "null" included_usage: description: The amount of usage included for this feature (per interval). anyOf: - anyOf: - type: number - type: string const: inf - type: "null" interval: 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. anyOf: - type: string enum: - minute - hour - day - week - month - quarter - semi_annual - year - type: "null" interval_count: description: Interval count of the feature. anyOf: - type: number - type: "null" entity_feature_id: description: The feature ID of the entity (like seats) to track sub-balances for. anyOf: - type: string - type: "null" usage_model: description: Whether the feature should be prepaid upfront or billed for how much they use end of billing period. anyOf: - type: string enum: - prepaid - pay_per_use - type: "null" price: description: The price of the product item. Should be null if tiered pricing is set. anyOf: - type: number - type: "null" tiers: description: Tiered pricing for the product item. Not applicable for fixed price items. anyOf: - type: array items: type: object properties: to: description: The maximum amount of usage for this tier. example: 100 anyOf: - type: number - type: string const: inf amount: description: The price of the product item for this tier. example: 10 type: number required: - to - amount - type: "null" billing_units: description: The billing units of the product item (eg $1 for 30 credits). anyOf: - type: number - type: "null" reset_usage_when_enabled: description: Whether the usage should be reset when the product is enabled. anyOf: - type: boolean - type: "null" required: - interval free_trial: description: Free trial configuration for this product, if available anyOf: - $ref: "#/components/schemas/FreeTrialConfig" - type: "null" responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Product" delete: summary: Delete Product tags: - products parameters: - in: path name: product_id schema: type: string required: true - in: query name: all_versions schema: type: boolean responses: "200": description: "" content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.products.delete('product_id'); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) product = autumn.products.delete( product_id="product_id", ) print(product.success) /features: get: summary: List Features tags: - features responses: "200": description: "" content: application/json: schema: type: object properties: list: type: array items: $ref: "#/components/schemas/Feature" required: - list additionalProperties: false x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.features.list(); post: summary: Create Feature tags: - features requestBody: content: application/json: schema: type: object properties: id: description: The ID of the feature. This is used to refer to it in other API calls like /track or /check. type: string pattern: ^[a-zA-Z0-9_-]+$ name: description: The name of the feature. anyOf: - type: string - type: "null" type: description: The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. type: string enum: - static - boolean - single_use - continuous_use - credit_system display: description: Singular and plural display names for the feature in your user interface. anyOf: - type: object properties: singular: type: string plural: type: string required: - singular - plural - type: "null" credit_schema: description: A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. anyOf: - type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost - type: "null" required: - id - type responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Feature" /features/{feature_id}: get: summary: Get Feature tags: - features parameters: - in: path name: feature_id schema: type: string required: true responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Feature" x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.features.get('feature_id'); post: summary: Update Feature tags: - features parameters: - in: path name: feature_id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: id: description: The ID of the feature. This is used to refer to it in other API calls like /track or /check. type: string pattern: ^[a-zA-Z0-9_-]+$ name: description: The name of the feature. type: string type: description: The type of the feature. 'single_use' features are consumed, like API calls, tokens, or messages. 'continuous_use' features are allocated, like seats, workspaces, or projects. 'credit_system' features are schemas that unify multiple 'single_use' features into a single credit system. type: string enum: - static - boolean - single_use - continuous_use - credit_system display: description: Singular and plural display names for the feature in your user interface. type: object properties: singular: type: string plural: type: string required: - singular - plural credit_schema: description: A schema that maps 'single_use' feature IDs to credit costs. Applicable only for 'credit_system' features. type: array items: type: object properties: metered_feature_id: type: string credit_cost: type: number required: - metered_feature_id - credit_cost archived: description: Whether the feature is archived. Archived features are hidden from the dashboard and list features endpoint. type: boolean responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Feature" x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.features.update('feature_id'); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) feature = autumn.features.update( feature_id="feature_id", ) print(feature.id) delete: summary: Delete Feature tags: - features parameters: - in: path name: feature_id schema: type: string required: true responses: "200": description: "" content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false /track: post: summary: Track Event tags: - core requestBody: content: application/json: schema: type: object properties: customer_id: description: ID which you provided when creating the customer type: string feature_id: description: ID of the feature to track usage for. Required if event_name is not provided. Use this for direct feature tracking. type: string event_name: 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. type: string value: description: The amount of usage to record. Defaults to 1. Can be negative to increase the balance (e.g., when removing a seat). type: number properties: description: Additional properties to attach to this usage event. type: object propertyNames: type: string additionalProperties: {} idempotency_key: description: Unique key to prevent duplicate event recording. Use this to safely retry requests without creating duplicate usage records. type: string customer_data: description: Additional customer properties. These will be used to create or update the customer if they don't exist or their properties are not already set. $ref: "#/components/schemas/CustomerData" entity_id: description: If using [entity balances](/features/feature-entities) (eg, seats), the entity ID to track usage for. type: string overage_behavior: description: How to handle usage when balance is insufficient. 'cap' limits usage to available balance, 'reject' prevents the usage entirely. type: string enum: - cap - reject required: - customer_id responses: "200": description: "" content: application/json: schema: example: customer_id: customer_123 feature_id: api_tokens type: object properties: customer_id: description: The ID of the customer type: string entity_id: description: The ID of the entity (if provided) type: string event_name: description: The name of the event type: string feature_id: description: The ID of the feature (if provided) type: string required: - customer_id additionalProperties: false x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.track({ customer_id: 'x' }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) response = autumn.track( customer_id="x", ) print(response.id) /check: post: summary: Check Feature Access tags: - core requestBody: content: application/json: schema: type: object properties: customer_id: description: ID which you provided when creating the customer type: string feature_id: description: ID of the feature to check access to. Required if product_id is not provided. type: string entity_id: description: If using entity balances (eg, seats), the entity ID to check access for. type: string customer_data: description: Properties used if customer is automatically created. Will also update if the name or email is not already set. $ref: "#/components/schemas/CustomerData" required_balance: 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. type: number send_event: description: If true, a usage event will be recorded together with checking access. The required_balance field will be used as the usage value. type: boolean with_preview: description: If true, the response will include a preview object, which can be used to display information such as a paywall or upgrade confirmation. type: boolean required: - customer_id - feature_id responses: "200": description: "" content: application/json: schema: example: allowed: true code: feature_found customer_id: customer_123 feature_id: api_tokens required_balance: 5 interval: month interval_count: 1 unlimited: false balance: 350 usage: 150 included_usage: 500 next_reset_at: 1731507600000 overage_allowed: false type: object properties: allowed: description: Whether the customer has access to the feature type: boolean code: description: Code describing the result of the check type: string customer_id: description: ID of the customer type: string feature_id: description: ID of the feature type: string entity_id: description: ID of the entity anyOf: - type: string - type: "null" required_balance: description: Balance of the feature the customer is required to have. type: number interval: description: The billing interval (e.g., 'month', 'year') or 'multiple' if the feature has different intervals across subscriptions anyOf: - anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: string const: multiple - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" unlimited: description: Whether the feature has unlimited usage with no restrictions or limits anyOf: - type: boolean - type: "null" balance: description: The remaining available balance across all subscriptions for this feature (or all time for allocated features) anyOf: - type: number - type: "null" usage: description: The total cumulative usage consumed in the current cycle across all subscriptions (or all time for allocated features) anyOf: - type: number - type: "null" included_usage: description: The total amount of usage included in the customer's plan(s) for this feature anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next cycle anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the included usage. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" breakdown: description: Detailed breakdown by interval for features with multiple intervals anyOf: - type: array items: type: object properties: interval: description: The reset interval for this feature breakdown anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" balance: description: The remaining available balance for this interval. Only present for metered features anyOf: - type: number - type: "null" usage: description: The total amount of usage consumed in the current cycle anyOf: - type: number - type: "null" included_usage: description: The amount of usage included in the customer's plan for this interval anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next billing period anyOf: - type: number - type: "null" usage_limit: description: The maximum usage allowed for this feature. null if unlimited or no limit is set anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the usage limit. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" required: - interval additionalProperties: false - type: "null" usage_limit: description: If this feature has a price, the usage limit indicates the maximum amount of usage the customer can use of this feature. anyOf: - type: number - type: "null" required: - allowed - code - customer_id - feature_id additionalProperties: false x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.check({ customer_id: 'customer_id', feature_id: 'feature_id' }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) response = autumn.check( customer_id="customer_id", feature_id="feature_id", ) print(response.customer_id) /usage: post: summary: Set Usage description: Set usage for a feature. This is similar to /track instead of incrementing usage, it sets the usage value to exactly what is provided. tags: - core requestBody: content: application/json: schema: type: object properties: customer_id: description: The ID of the customer. type: string feature_id: description: The ID of the feature to set usage for. type: string value: description: The value you want to set this customer's usage of the feature to. type: number entity_id: description: The ID of the entity to set usage for. type: string customer_data: $ref: "#/components/schemas/CustomerData" required: - customer_id - feature_id - value responses: "200": description: "" content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.usage({ customer_id: 'x', feature_id: 'feature_id', value: 0, }); /customers: get: summary: List Customers tags: - customers parameters: - in: query name: limit schema: description: Maximum number of customers to return default: 10 type: integer description: Maximum number of customers to return - in: query name: offset schema: description: Number of customers to skip before returning results default: 0 type: integer description: Number of customers to skip before returning results responses: "200": description: "" content: application/json: schema: type: object properties: list: type: array items: type: object properties: id: description: Your unique identifier for the customer. anyOf: - type: string - type: "null" created_at: description: Timestamp of customer creation in milliseconds since epoch. type: number name: description: The name of the customer. anyOf: - type: string - type: "null" email: description: The email address of the customer. anyOf: - type: string - type: "null" fingerprint: description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." anyOf: - type: string - type: "null" stripe_id: description: Stripe customer ID. default: null anyOf: - type: string - type: "null" env: description: The environment this customer was created in. type: string enum: - sandbox - live metadata: description: The metadata for the customer. default: {} type: object propertyNames: {} additionalProperties: {} products: description: The products the customer has access to. type: array items: $ref: "#/components/schemas/CustomerProduct" features: description: The features a customer has access to as a dictionary of feature IDs to customer feature objects. type: object propertyNames: type: string additionalProperties: type: object properties: id: description: The ID of the feature type: string type: description: The type of the feature type: string enum: - static - boolean - single_use - continuous_use - credit_system name: description: The name of the feature anyOf: - type: string - type: "null" interval: description: The billing interval (e.g., 'month', 'year') or 'multiple' if the feature has different intervals across subscriptions anyOf: - anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: string const: multiple - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" unlimited: description: Whether the feature has unlimited usage with no restrictions or limits anyOf: - type: boolean - type: "null" balance: description: The remaining available balance across all subscriptions for this feature (or all time for allocated features) anyOf: - type: number - type: "null" usage: description: The total cumulative usage consumed in the current cycle across all subscriptions (or all time for allocated features) anyOf: - type: number - type: "null" included_usage: description: The total amount of usage included in the customer's plan(s) for this feature anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next cycle anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the included usage. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" breakdown: description: Detailed breakdown by interval for features with multiple intervals anyOf: - type: array items: type: object properties: interval: description: The reset interval for this feature breakdown anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" balance: description: The remaining available balance for this interval. Only present for metered features anyOf: - type: number - type: "null" usage: description: The total amount of usage consumed in the current cycle anyOf: - type: number - type: "null" included_usage: description: The amount of usage included in the customer's plan for this interval anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next billing period anyOf: - type: number - type: "null" usage_limit: description: The maximum usage allowed for this feature. null if unlimited or no limit is set anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the usage limit. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" required: - interval additionalProperties: false - type: "null" usage_limit: description: If this feature has a price, the usage limit indicates the maximum amount of usage the customer can use of this feature. anyOf: - type: number - type: "null" required: - id - type additionalProperties: false rewards: description: The rewards for the customer. Returned only if rewards is provided in the expand parameter. anyOf: - type: object properties: discounts: description: Array of active discounts applied to the customer example: - id: disc_123456 name: SUMMER20 type: percentage discount_value: 20 type: array items: type: object properties: id: description: The unique identifier for this discount example: disc_123456 type: string name: description: The name of the discount or coupon example: SUMMER20 type: string type: description: The type of reward example: percentage type: string enum: - percentage_discount - fixed_discount - free_product - invoice_credits discount_value: description: The discount value (percentage or fixed amount) example: 20 type: number duration_type: description: How long the discount lasts example: forever type: string enum: - one_off - months - forever duration_value: description: Number of billing periods the discount applies for repeating durations example: 3 anyOf: - type: number - type: "null" currency: description: The currency code for fixed amount discounts example: usd anyOf: - type: string - type: "null" start: description: Timestamp when the discount becomes active example: 1759247877000 anyOf: - type: number - type: "null" end: description: Timestamp when the discount expires example: 1761839877000 anyOf: - type: number - type: "null" subscription_id: description: The Stripe subscription ID this discount is applied to example: sub_1A2B3C4D5E6F7G8H anyOf: - type: string - type: "null" total_discount_amount: description: Total amount saved from this discount example: 599 anyOf: - type: number - type: "null" required: - id - name - type - discount_value - duration_type additionalProperties: false required: - discounts additionalProperties: false - type: "null" upcoming_invoice: description: The upcoming invoice for the customer. Returned only if upcoming_invoice is provided in the expand parameter. anyOf: - type: object properties: lines: type: array items: type: object properties: product_id: anyOf: - type: string - type: "null" description: type: string amount: type: number required: - description - amount additionalProperties: false discounts: type: array items: type: object properties: id: description: The unique identifier for this discount example: disc_123456 type: string name: description: The name of the discount or coupon example: SUMMER20 type: string type: description: The type of reward example: percentage type: string enum: - percentage_discount - fixed_discount - free_product - invoice_credits discount_value: description: The discount value (percentage or fixed amount) example: 20 type: number duration_type: description: How long the discount lasts example: forever type: string enum: - one_off - months - forever duration_value: description: Number of billing periods the discount applies for repeating durations example: 3 anyOf: - type: number - type: "null" currency: description: The currency code for fixed amount discounts example: usd anyOf: - type: string - type: "null" start: description: Timestamp when the discount becomes active example: 1759247877000 anyOf: - type: number - type: "null" end: description: Timestamp when the discount expires example: 1761839877000 anyOf: - type: number - type: "null" subscription_id: description: The Stripe subscription ID this discount is applied to example: sub_1A2B3C4D5E6F7G8H anyOf: - type: string - type: "null" total_discount_amount: description: Total amount saved from this discount example: 599 anyOf: - type: number - type: "null" required: - id - name - type - discount_value - duration_type additionalProperties: false subtotal: type: number total: type: number currency: type: string required: - lines - discounts - subtotal - total - currency additionalProperties: false - type: "null" required: - id - created_at - name - email - fingerprint - stripe_id - env - metadata - products - features additionalProperties: false total: description: Total number of customers available type: integer limit: description: Maximum number of customers returned type: integer offset: description: Number of customers skipped before returning results type: integer required: - list - total - limit - offset additionalProperties: false x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.customers.list(); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) customers = autumn.customers.list() print(customers.limit) post: summary: Create Customer tags: - customers parameters: - in: query name: expand schema: type: array items: type: string enum: - invoices - trials_used - rewards - entities - referrals - payment_method requestBody: content: application/json: schema: type: object properties: id: description: Your unique identifier for the customer anyOf: - type: string - type: "null" name: description: Customer's name anyOf: - type: string - type: "null" email: description: Customer's email address anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" fingerprint: description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse type: string metadata: description: Additional metadata for the customer anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" stripe_id: description: Stripe customer ID if you already have one type: string required: - id responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Customer" x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.customers.create({ id: 'id' }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) customer = autumn.customers.create( id="id", ) print(customer.id) /customers/{customer_id}: get: summary: Get Customer tags: - customers parameters: - in: path name: customer_id schema: description: The ID of the customer. type: string required: true description: The ID of the customer. - in: query name: expand schema: type: array items: type: string enum: - invoices - trials_used - rewards - entities - referrals - payment_method responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Customer" x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.customers.get('customer_id'); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) customer = autumn.customers.get( customer_id="customer_id", ) print(customer.id) post: summary: Update Customer tags: - customers parameters: - in: path name: customer_id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: id: description: New unique identifier for the customer. type: string name: description: The customer's name. anyOf: - type: string - type: "null" email: description: Customer's email address anyOf: - type: string format: email pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: "null" fingerprint: description: Unique identifier (eg, serial number) to detect duplicate customers. anyOf: - type: string - type: "null" metadata: description: Additional metadata for the customer (set individual keys to null to delete them). anyOf: - type: object propertyNames: {} additionalProperties: {} - type: "null" stripe_id: description: Stripe customer ID. anyOf: - type: string - type: "null" responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Customer" x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.customers.update('customer_id'); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) customer = autumn.customers.update( customer_id="customer_id", ) print(customer.id) delete: summary: Delete Customer tags: - customers parameters: - in: path name: customer_id schema: type: string required: true - in: query name: delete_in_stripe schema: description: Whether to delete the customer and cancel all existing subscriptions in Stripe. default: false type: boolean description: Whether to delete the customer and cancel all existing subscriptions in Stripe. responses: "200": description: "" content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.customers.delete('customer_id'); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) customer = autumn.customers.delete( customer_id="customer_id", ) print(customer.success) /customers/{customer_id}/billing_portal: post: summary: Get Billing Portal URL tags: - customers parameters: - in: path name: customer_id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: return_url: description: URL to redirect to when back button is clicked in the billing portal. type: string responses: "200": description: "" content: application/json: schema: type: object properties: customer_id: description: The ID of the customer type: string url: description: URL to the billing portal type: string required: - customer_id - url additionalProperties: false x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.customers.billingPortal('customer_id'); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) response = autumn.customers.billing_portal( customer_id="customer_id", ) print(response.customer_id) /customers/{customer_id}/balances: post: summary: Set Feature Balances description: Set the balance of a feature for a specific customer tags: - customers parameters: - in: path name: customer_id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: balances: type: array items: type: object properties: feature_id: description: The ID of the feature to update balance for. type: string balance: description: The new balance value. type: number required: - feature_id - balance entity_id: description: The ID of the entity to update balance for. type: string required: - balances responses: "200": description: "" content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.customers.updateBalances('customer_id', { balances: [{ balance: 0, feature_id: 'feature_id' }], }); /customers/{customer_id}/entities: post: summary: Create Entity tags: - entities parameters: - in: path name: customer_id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: id: description: The ID of the entity anyOf: - type: string - type: "null" name: description: The name of the entity anyOf: - type: string - type: "null" feature_id: description: The ID of the feature this entity is associated with type: string customer_data: $ref: "#/components/schemas/CustomerData" required: - id - feature_id responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Entity" x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.entities.create('customer_id', { id: 'id', feature_id: 'feature_id' }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) entity = autumn.entities.create( customer_id="customer_id", id="id", feature_id="feature_id", ) print(entity.id) /customers/{customer_id}/entities/{entity_id}: get: summary: Get Entity tags: - entities parameters: - in: path name: customer_id schema: type: string required: true - in: path name: entity_id schema: type: string required: true - in: query name: expand schema: type: array items: type: string enum: - invoices responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Entity" x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.entities.get("entity_id", "customer_id"); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) entity = autumn.entities.get( entity_id="entity_id", customer_id="customer_id", ) print(entity.id) delete: summary: Delete Entity tags: - entities parameters: - in: path name: customer_id schema: type: string required: true - in: path name: entity_id schema: type: string required: true responses: "200": description: "" content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.entities.delete("entity_id", "customer_id"); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) entity = autumn.entities.delete( entity_id="entity_id", customer_id="customer_id", ) print(entity.success) /events/list: post: summary: List Events tags: - events requestBody: content: application/json: schema: type: object properties: offset: description: Number of items to skip default: 0 type: integer limit: description: Number of items to return. Default 100, max 1000. default: 100 type: integer customer_id: description: Filter events by customer ID type: string feature_id: description: Filter by specific feature ID(s) anyOf: - type: string - type: array items: type: string custom_range: description: Filter events by time range type: object properties: start: description: Filter events after this timestamp (epoch milliseconds) type: number end: description: Filter events before this timestamp (epoch milliseconds) type: number required: - customer_id - feature_id responses: "200": description: "" content: application/json: schema: example: list: - id: evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg timestamp: 1765958215459 feature_id: credits customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx value: 30 properties: {} - id: evt_36xmHxxjAkqxufDf9yHAPNfRrLM timestamp: 1765956512057 feature_id: credits customer_id: 0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx value: 49 properties: {} total: 2 has_more: false offset: 0 limit: 100 type: object properties: list: description: Array of items for current page type: array items: type: object properties: id: description: Event ID (KSUID) type: string timestamp: description: Event timestamp (epoch milliseconds) type: number feature_id: description: ID of the feature that the event belongs to type: string customer_id: description: Customer identifier type: string value: description: Event value/count type: number properties: description: Event properties (JSONB) type: object properties: {} additionalProperties: false required: - id - timestamp - feature_id - customer_id - value - properties additionalProperties: false has_more: description: Whether more results exist after this page type: boolean offset: description: Current offset position type: number limit: description: Limit passed in the request type: number total: description: Total number of items returned in the current page type: number required: - list - has_more - offset - limit - total additionalProperties: false x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.events.list({ customer_id: 'customer_id', feature_id: 'x' }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) events = autumn.events.list( customer_id="customer_id", feature_id="x", ) print(events.has_more) /events/aggregate: post: summary: Aggregate Events tags: - events requestBody: content: application/json: schema: type: object properties: customer_id: description: Customer ID to aggregate events for type: string feature_id: description: Feature ID(s) to aggregate events for anyOf: - type: string - type: array items: type: string group_by: description: Property to group events by. If provided, each key in the response will be an object with distinct groups as the keys type: string pattern: ^properties\..* range: description: Time range to aggregate events for. Either range or custom_range must be provided type: string enum: - 24h - 7d - 30d - 90d - last_cycle - 1bc - 3bc bin_size: description: Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day default: day type: string enum: - day - hour custom_range: description: Custom time range to aggregate events for. If provided, range must not be provided type: object properties: start: type: number end: type: number required: - start - end required: - customer_id - feature_id responses: "200": description: "" content: application/json: schema: example: list: - timestamp: 1762905600000 messages: 10 seats: 3 - timestamp: 1762992000000 messages: 3 seats: 12 total: messages: count: 2 sum: 13 seats: count: 2 sum: 15 anyOf: - $ref: "#/components/schemas/EventAggregateResponseFlat" - $ref: "#/components/schemas/EventAggregateResponseGrouped" x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.events.aggregate({ customer_id: 'x', feature_id: 'x' }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) response = autumn.events.aggregate( customer_id="x", feature_id="x", ) print(response) /query: post: summary: Query Analytics Aggregation tags: - analytics requestBody: content: application/json: schema: type: object properties: customer_id: description: Customer ID to aggregate events for type: string feature_id: description: Feature ID(s) to aggregate events for anyOf: - type: string - type: array items: type: string group_by: description: Property to group events by. If provided, each key in the response will be an object with distinct groups as the keys type: string pattern: ^properties\..* range: description: Time range to aggregate events for. Either range or custom_range must be provided type: string enum: - 24h - 7d - 30d - 90d - last_cycle - 1bc - 3bc bin_size: description: Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day default: day type: string enum: - day - hour custom_range: description: Custom time range to aggregate events for. If provided, range must not be provided type: object properties: start: type: number end: type: number required: - start - end required: - customer_id - feature_id responses: "200": description: Analytics aggregation results content: application/json: schema: anyOf: - $ref: "#/components/schemas/EventAggregateResponseFlat" - $ref: "#/components/schemas/EventAggregateResponseGrouped" x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.query({ customer_id: 'x', feature_id: 'x' }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) response = autumn.query( customer_id="x", feature_id="x", ) print(response) /balances/create: post: summary: Create Balance description: Create a new balance for a specific feature for a customer. tags: - balances x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.balances.create({ "customer_id": "cus_123", "feature_id": "api_tokens", "granted_balance": 100, "reset": { "interval": "month" } }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) balance = autumn.balances.create( customer_id="customer_id", feature_id="feature_id", ) print(balance.success) requestBody: content: application/json: schema: type: object properties: feature_id: description: The feature ID to create the balance for type: string customer_id: description: The customer ID to assign the balance to type: string entity_id: description: Entity ID for entity-scoped balances type: string granted_balance: description: The initial balance amount to grant type: number unlimited: description: Whether the balance is unlimited type: boolean reset: description: Reset configuration for the balance type: object properties: interval: type: string enum: - one_off - minute - hour - day - week - month - quarter - semi_annual - year interval_count: type: number required: - interval expires_at: description: Unix timestamp (milliseconds) when the balance expires type: number required: - feature_id - customer_id responses: "200": description: Balance created successfully content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false /referrals/code: post: summary: Create a referral code tags: - referrals requestBody: content: application/json: schema: type: object properties: customer_id: description: The unique identifier of the customer example: cus_123 type: string program_id: description: ID of your referral program example: prog_123 type: string required: - customer_id - program_id responses: "200": description: Referral code generated successfully content: application/json: schema: $ref: "#/components/schemas/ReferralCode" x-codeSamples: - lang: TypeScript source: |- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.referrals.createCode({ customer_id: 'cus_123', program_id: 'prog_123', }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) response = autumn.referrals.create_code( customer_id="cus_123", program_id="prog_123", ) print(response.customer_id) /referrals/redeem: post: summary: Redeem a referral code tags: - referrals requestBody: content: application/json: schema: type: object properties: code: description: The referral code to redeem example: REF123ABC type: string customer_id: description: The unique identifier of the customer redeeming the code example: cus_456 type: string required: - code - customer_id responses: "200": description: Referral code redeemed successfully content: application/json: schema: $ref: "#/components/schemas/RedeemReferralCodeResponse" x-codeSamples: - lang: TypeScript source: >- import { Autumn } from 'autumn-js'; const autumn = new Autumn(); const { data, error } = await autumn.referrals.redeemCode({ code: 'REF123ABC', customer_id: 'cus_456' }); - lang: Python source: >- import asyncio import os from autumn import Autumn client = Autumn( secret_key=os.environ.get("AUTUMN_SECRET_KEY"), # This is the default and can be omitted ) response = autumn.referrals.redeem_code( code="REF123ABC", customer_id="cus_456", ) print(response.id) components: schemas: FreeTrialConfig: title: FreeTrialConfig type: object properties: length: anyOf: - type: string - type: number unique_fingerprint: default: false type: boolean duration: default: day type: string enum: - day - month - year card_required: default: true type: boolean required: - length CustomerData: description: Customer details to set when creating a customer type: object properties: name: description: Customer's name anyOf: - type: string - type: "null" email: description: Customer's email address anyOf: - type: string - type: "null" CustomerProduct: type: object properties: id: description: The unique identifier for the product example: pro_plan type: string name: description: The name of the product example: Pro Plan anyOf: - type: string - type: "null" group: description: The group the product belongs to example: product_set_1 anyOf: - type: string - type: "null" status: description: Current status of the product for this customer example: active type: string enum: - active - expired - scheduled - trialing - past_due canceled_at: description: Timestamp when the product was canceled for the customer example: 1717000000 anyOf: - type: number - type: "null" started_at: description: Timestamp when the customer started this product example: 1700000000000 type: number is_default: description: Whether this product is the default for the customer example: true type: boolean is_add_on: description: Whether the product is an add-on example: false type: boolean version: description: Version of the product example: 1 anyOf: - type: number - type: "null" stripe_subscription_ids: description: List of Stripe subscription IDs associated with this product, if any example: - sub_1Nc0JzBAbcxyz - sub_1Nc0xyBAnopq anyOf: - type: array items: type: string - type: "null" current_period_start: description: Start of the current billing period example: 1717000000 anyOf: - type: number - type: "null" current_period_end: description: End of the current billing period example: 1719600000 anyOf: - type: number - type: "null" entity_id: description: ID of the entity this customer product is attached to, if applicable example: entity_1234abcd anyOf: - type: string - type: "null" items: description: Array of product items defining the features and pricing example: - feature_id: feature_type: single_use included_usage: 123 interval: month usage_model: prepaid price: 123 billing_units: 1000 entity_feature_id: reset_usage_when_enabled: true tiers: - to: 100 amount: 10 anyOf: - type: array items: $ref: "#/components/schemas/ProductItem" - type: "null" quantity: description: The number of units of this product held by the customer, if applicable example: 1 type: number required: - id - name - group - status - started_at - is_default - is_add_on ProductItem: description: Product item defining features and pricing within a product type: object properties: type: description: The type of the product item anyOf: - type: string enum: - feature - priced_feature - price - type: "null" feature_id: description: The feature ID of the product item. If the item is a fixed price, should be `null` anyOf: - type: string - type: "null" feature_type: 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. anyOf: - type: string enum: - single_use - continuous_use - boolean - static - type: "null" included_usage: description: The amount of usage included for this feature. anyOf: - anyOf: - type: number - type: string const: inf - type: "null" interval: 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. anyOf: - type: string enum: - minute - hour - day - week - month - quarter - semi_annual - year - type: "null" interval_count: description: The interval count of the product item. anyOf: - type: number - type: "null" price: description: The price of the product item. Should be `null` if tiered pricing is set. anyOf: - type: number - type: "null" tiers: description: Tiered pricing for the product item. Not applicable for fixed price items. anyOf: - type: array items: type: object properties: to: description: The maximum amount of usage for this tier. example: 100 anyOf: - type: number - type: string const: inf amount: description: The price of the product item for this tier. example: 10 type: number required: - to - amount - type: "null" usage_model: description: Whether the feature should be prepaid upfront or billed for how much they use end of billing period. anyOf: - type: string enum: - prepaid - pay_per_use - type: "null" billing_units: description: The amount per billing unit (eg. $9 / 250 units) anyOf: - type: number - type: "null" reset_usage_when_enabled: description: Whether the usage should be reset when the product is enabled. anyOf: - type: boolean - type: "null" entity_feature_id: description: The entity feature ID of the product item if applicable. anyOf: - type: string - type: "null" display: description: The display of the product item. anyOf: - type: object properties: primary_text: type: string secondary_text: anyOf: - type: string - type: "null" required: - primary_text - type: "null" quantity: description: Used in customer context. Quantity of the feature the customer has prepaid for. anyOf: - type: number - type: "null" next_cycle_quantity: description: Used in customer context. Quantity of the feature the customer will prepay for in the next cycle. anyOf: - type: number - type: "null" config: description: Configuration for rollover and proration behavior of the feature. anyOf: - type: object properties: rollover: anyOf: - type: object properties: max: anyOf: - type: number - type: "null" duration: default: month type: string enum: - month - forever length: type: number required: - max - length - type: "null" on_increase: anyOf: - type: string enum: - bill_immediately - prorate_immediately - prorate_next_cycle - bill_next_cycle - type: "null" on_decrease: anyOf: - type: string enum: - prorate - prorate_immediately - prorate_next_cycle - none - no_prorations - type: "null" - type: "null" EventAggregateResponseFlat: title: No Group description: Response when group_by is not provided. Feature values are numbers. allOf: - type: object properties: list: type: array items: type: object properties: period: type: number required: - period additionalProperties: type: number required: - list additionalProperties: false - type: object properties: total: type: object propertyNames: type: string additionalProperties: type: object properties: count: type: number sum: type: number required: - count - sum additionalProperties: false required: - total additionalProperties: false EventAggregateResponseGrouped: title: With Group description: Response when group_by is provided. Feature values are objects with group values as keys. allOf: - type: object properties: list: type: array items: type: object properties: period: type: number required: - period additionalProperties: type: object propertyNames: type: string additionalProperties: type: number required: - list additionalProperties: false - type: object properties: total: type: object propertyNames: type: string additionalProperties: type: object properties: count: type: number sum: type: number required: - count - sum additionalProperties: false required: - total additionalProperties: false ReferralCode: description: Referral code object returned by the API type: object properties: code: description: The referral code that can be shared with customers example: REF123ABC type: string customer_id: description: Your unique identifier for the customer example: cus_123 type: string created_at: description: The timestamp of when the referral code was created example: 1717000000 type: number required: - code - customer_id - created_at additionalProperties: false RedeemReferralCodeResponse: description: Redemption response object returned by the API type: object properties: id: description: The ID of the redemption event example: red_123 type: string customer_id: description: Your unique identifier for the customer example: cus_456 type: string reward_id: description: The ID of the reward that will be granted example: reward_789 type: string required: - id - customer_id - reward_id additionalProperties: false Customer: example: id: customer_123 created_at: 1762971906762 name: John Doe email: john@doe.com fingerprint: null stripe_id: cus_J8A5c31A8tlpwN env: sandbox metadata: {} products: - id: pro_plan name: Pro Plan group: product_set_1 status: active canceled_at: null started_at: 1762971923843 is_default: false is_add_on: false version: 1 current_period_start: 1762971905000 current_period_end: 1765563905000 items: - type: feature feature_id: dashboard feature_type: static included_usage: 0 interval: null entity_feature_id: null display: primary_text: Dashboard - type: feature feature_id: messages feature_type: single_use included_usage: 30 interval: month reset_usage_when_enabled: true entity_feature_id: null display: primary_text: 10 Messages quantity: 1 features: messages: id: messages type: single_use name: Messages interval: month interval_count: 1 unlimited: false balance: 10 usage: 0 included_usage: 10 next_reset_at: 1765563905000 overage_allowed: false dashboard: id: dashboard type: static name: Dashboard interval: null interval_count: null unlimited: false balance: 0 usage: 0 included_usage: 0 next_reset_at: null overage_allowed: false type: object properties: id: description: Your unique identifier for the customer. anyOf: - type: string - type: "null" created_at: description: Timestamp of customer creation in milliseconds since epoch. type: number name: description: The name of the customer. anyOf: - type: string - type: "null" email: description: The email address of the customer. anyOf: - type: string - type: "null" fingerprint: description: "A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID." anyOf: - type: string - type: "null" stripe_id: description: Stripe customer ID. default: null anyOf: - type: string - type: "null" env: description: The environment this customer was created in. type: string enum: - sandbox - live metadata: description: The metadata for the customer. default: {} type: object propertyNames: {} additionalProperties: {} products: description: The products the customer has access to. type: array items: $ref: "#/components/schemas/CustomerProduct" features: description: The features a customer has access to as a dictionary of feature IDs to customer feature objects. type: object propertyNames: type: string additionalProperties: type: object properties: id: description: The ID of the feature type: string type: description: The type of the feature type: string enum: - static - boolean - single_use - continuous_use - credit_system name: description: The name of the feature anyOf: - type: string - type: "null" interval: description: The billing interval (e.g., 'month', 'year') or 'multiple' if the feature has different intervals across subscriptions anyOf: - anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: string const: multiple - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" unlimited: description: Whether the feature has unlimited usage with no restrictions or limits anyOf: - type: boolean - type: "null" balance: description: The remaining available balance across all subscriptions for this feature (or all time for allocated features) anyOf: - type: number - type: "null" usage: description: The total cumulative usage consumed in the current cycle across all subscriptions (or all time for allocated features) anyOf: - type: number - type: "null" included_usage: description: The total amount of usage included in the customer's plan(s) for this feature anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next cycle anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the included usage. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" breakdown: description: Detailed breakdown by interval for features with multiple intervals anyOf: - type: array items: type: object properties: interval: description: The reset interval for this feature breakdown anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" balance: description: The remaining available balance for this interval. Only present for metered features anyOf: - type: number - type: "null" usage: description: The total amount of usage consumed in the current cycle anyOf: - type: number - type: "null" included_usage: description: The amount of usage included in the customer's plan for this interval anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next billing period anyOf: - type: number - type: "null" usage_limit: description: The maximum usage allowed for this feature. null if unlimited or no limit is set anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the usage limit. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" required: - interval additionalProperties: false - type: "null" usage_limit: description: If this feature has a price, the usage limit indicates the maximum amount of usage the customer can use of this feature. anyOf: - type: number - type: "null" required: - id - type additionalProperties: false invoices: description: The invoices for the customer. Returned only if invoices is provided in the expand parameter. type: array items: type: object properties: product_ids: description: Array of product IDs included in this invoice example: - pro_plan - addon_feature type: array items: type: string stripe_id: description: The Stripe invoice ID example: in_1A2B3C4D5E6F7G8H type: string status: description: The status of the invoice example: paid type: string total: description: The total amount of the invoice example: 2999 type: number currency: description: The currency code for the invoice example: usd type: string created_at: description: Timestamp when the invoice was created example: 1759247877000 type: number hosted_invoice_url: description: URL to the Stripe-hosted invoice page example: https://invoice.stripe.com/i/acct_123/test_456 anyOf: - type: string - type: "null" required: - product_ids - stripe_id - status - total - currency - created_at additionalProperties: false entities: description: The entities for the customer. Returned only if entities is provided in the expand parameter. type: array items: type: object properties: autumn_id: type: string id: description: The unique identifier of the entity anyOf: - type: string - type: "null" name: description: The name of the entity anyOf: - type: string - type: "null" customer_id: description: The customer ID this entity belongs to anyOf: - type: string - type: "null" feature_id: description: The feature ID this entity belongs to anyOf: - type: string - type: "null" created_at: description: Unix timestamp when the entity was created type: number env: description: The environment (sandbox/live) type: string enum: - sandbox - live required: - id - name - created_at - env additionalProperties: false trials_used: description: The trials used for the customer. Returned only if trials_used is provided in the expand parameter. type: array items: type: object properties: product_id: type: string customer_id: type: string fingerprint: anyOf: - type: string - type: "null" required: - product_id - customer_id additionalProperties: false rewards: description: The rewards for the customer. Returned only if rewards is provided in the expand parameter. anyOf: - type: object properties: discounts: description: Array of active discounts applied to the customer example: - id: disc_123456 name: SUMMER20 type: percentage discount_value: 20 type: array items: type: object properties: id: description: The unique identifier for this discount example: disc_123456 type: string name: description: The name of the discount or coupon example: SUMMER20 type: string type: description: The type of reward example: percentage type: string enum: - percentage_discount - fixed_discount - free_product - invoice_credits discount_value: description: The discount value (percentage or fixed amount) example: 20 type: number duration_type: description: How long the discount lasts example: forever type: string enum: - one_off - months - forever duration_value: description: Number of billing periods the discount applies for repeating durations example: 3 anyOf: - type: number - type: "null" currency: description: The currency code for fixed amount discounts example: usd anyOf: - type: string - type: "null" start: description: Timestamp when the discount becomes active example: 1759247877000 anyOf: - type: number - type: "null" end: description: Timestamp when the discount expires example: 1761839877000 anyOf: - type: number - type: "null" subscription_id: description: The Stripe subscription ID this discount is applied to example: sub_1A2B3C4D5E6F7G8H anyOf: - type: string - type: "null" total_discount_amount: description: Total amount saved from this discount example: 599 anyOf: - type: number - type: "null" required: - id - name - type - discount_value - duration_type additionalProperties: false required: - discounts additionalProperties: false - type: "null" referrals: description: The referrals for the customer. Returned only if referrals is provided in the expand parameter. 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 additionalProperties: false reward_applied: type: boolean created_at: type: number required: - program_id - customer - reward_applied - created_at additionalProperties: false upcoming_invoice: description: The upcoming invoice for the customer. Returned only if upcoming_invoice is provided in the expand parameter. anyOf: - type: object properties: lines: type: array items: type: object properties: product_id: anyOf: - type: string - type: "null" description: type: string amount: type: number required: - description - amount additionalProperties: false discounts: type: array items: type: object properties: id: description: The unique identifier for this discount example: disc_123456 type: string name: description: The name of the discount or coupon example: SUMMER20 type: string type: description: The type of reward example: percentage type: string enum: - percentage_discount - fixed_discount - free_product - invoice_credits discount_value: description: The discount value (percentage or fixed amount) example: 20 type: number duration_type: description: How long the discount lasts example: forever type: string enum: - one_off - months - forever duration_value: description: Number of billing periods the discount applies for repeating durations example: 3 anyOf: - type: number - type: "null" currency: description: The currency code for fixed amount discounts example: usd anyOf: - type: string - type: "null" start: description: Timestamp when the discount becomes active example: 1759247877000 anyOf: - type: number - type: "null" end: description: Timestamp when the discount expires example: 1761839877000 anyOf: - type: number - type: "null" subscription_id: description: The Stripe subscription ID this discount is applied to example: sub_1A2B3C4D5E6F7G8H anyOf: - type: string - type: "null" total_discount_amount: description: Total amount saved from this discount example: 599 anyOf: - type: number - type: "null" required: - id - name - type - discount_value - duration_type additionalProperties: false subtotal: type: number total: type: number currency: type: string required: - lines - discounts - subtotal - total - currency additionalProperties: false - type: "null" payment_method: description: The payment method for the customer on Stripe. Returned only if payment_method is provided in the expand parameter. anyOf: - {} - type: "null" required: - id - created_at - name - email - fingerprint - stripe_id - env - metadata - products - features additionalProperties: false Product: examples: - id: Pro Product name: Pro Plan group: null env: sandbox is_add_on: false is_default: false archived: false version: 1 created_at: 1761296829908 items: - type: price feature_id: null interval: month interval_count: 1 price: 20 display: primary_text: $20 secondary_text: per month - type: priced_feature feature_id: words included_usage: 1000 interval: month interval_count: 1 price: 0.5 usage_model: pay_per_use billing_units: 1000 reset_usage_when_enabled: true entity_feature_id: null display: primary_text: 1,000 Words secondary_text: then $0.5 per 1,000 Words - type: feature feature_id: dashboard entity_feature_id: null display: primary_text: Dashboard - type: feature feature_id: messages included_usage: 10 interval: month interval_count: 1 reset_usage_when_enabled: true entity_feature_id: null display: primary_text: 10 Messages free_trial: duration: day length: 7 unique_fingerprint: false card_required: true base_variant_id: null scenario: new type: object properties: id: description: The ID of the product you set when creating the product type: string name: description: The name of the product type: string group: description: Product group which this product belongs to anyOf: - type: string - type: "null" env: description: The environment of the product type: string enum: - sandbox - live is_add_on: description: Whether the product is an add-on and can be purchased alongside other products type: boolean is_default: description: Whether the product is the default product type: boolean archived: description: Whether this product has been archived and is no longer available type: boolean version: description: The current version of the product type: number created_at: description: The timestamp of when the product was created in milliseconds since epoch type: number items: description: Array of product items that define the product's features and pricing type: array items: $ref: "#/components/schemas/ProductItem" free_trial: description: Free trial configuration for this product, if available anyOf: - type: object properties: duration: description: The duration type of the free trial type: string enum: - day - month - year length: description: The length of the duration type specified type: number unique_fingerprint: description: Whether the free trial is limited to one per customer fingerprint type: boolean card_required: 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. type: boolean trial_available: description: Used in customer context. Whether the free trial is available for the customer if they were to attach the product. default: true anyOf: - type: boolean - type: "null" required: - duration - length - unique_fingerprint - card_required - trial_available additionalProperties: false - type: "null" base_variant_id: description: ID of the base variant this product is derived from anyOf: - type: string - type: "null" scenario: description: Scenario for when this product is used in attach flows type: string enum: - scheduled - active - new - renew - upgrade - downgrade - cancel - expired - past_due required: - id - name - group - env - is_add_on - is_default - archived - version - created_at - items - free_trial - base_variant_id additionalProperties: false Feature: examples: - id: tokens name: Tokens type: single_use display: singular: token plural: tokens credit_schema: null archived: false type: object properties: id: description: The ID of the feature, used to refer to it in other API calls like /track or /check. type: string name: description: The name of the feature. anyOf: - type: string - type: "null" type: type: string enum: - boolean - single_use - continuous_use - credit_system display: description: Singular and plural display names for the feature. anyOf: - type: object properties: singular: description: The singular display name for the feature. type: string plural: description: The plural display name for the feature. type: string required: - singular - plural additionalProperties: false - type: "null" credit_schema: description: Credit cost schema for credit system features. anyOf: - type: array items: type: object properties: metered_feature_id: description: The ID of the metered feature (should be a single_use feature). type: string credit_cost: description: The credit cost of the metered feature. type: number required: - metered_feature_id - credit_cost additionalProperties: false - type: "null" archived: description: Whether or not the feature is archived. anyOf: - type: boolean - type: "null" required: - id - type additionalProperties: false Entity: example: id: seat_123 name: John Doe's Seat customer_id: org_123 created_at: 1762971906762 env: sandbox products: - id: pro_plan name: Pro Plan group: null status: active canceled_at: null started_at: 1762971923843 is_default: false is_add_on: false version: 1 current_period_start: 1762971905000 current_period_end: 1765563905000 items: - type: feature feature_id: messages feature_type: single_use included_usage: 30 interval: month reset_usage_when_enabled: true entity_feature_id: null display: primary_text: 10 Messages quantity: 1 features: messages: id: messages type: single_use name: Messages interval: month interval_count: 1 unlimited: false balance: 10 usage: 0 included_usage: 30 next_reset_at: 1765563905000 overage_allowed: false type: object properties: id: description: The unique identifier of the entity. anyOf: - type: string - type: "null" name: description: The name of the entity. anyOf: - type: string - type: "null" customer_id: description: The customer ID this entity belongs to. anyOf: - type: string - type: "null" feature_id: description: The feature ID this entity belongs to. anyOf: - type: string - type: "null" created_at: description: Unix timestamp (in milliseconds) when the entity was created. type: number env: type: string enum: - sandbox - live products: description: The products this entity has access to. type: array items: $ref: "#/components/schemas/CustomerProduct" features: description: The features this entity has access to. type: object propertyNames: type: string additionalProperties: type: object properties: id: description: The ID of the feature type: string type: description: The type of the feature type: string enum: - static - boolean - single_use - continuous_use - credit_system name: description: The name of the feature anyOf: - type: string - type: "null" interval: description: The billing interval (e.g., 'month', 'year') or 'multiple' if the feature has different intervals across subscriptions anyOf: - anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: string const: multiple - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" unlimited: description: Whether the feature has unlimited usage with no restrictions or limits anyOf: - type: boolean - type: "null" balance: description: The remaining available balance across all subscriptions for this feature (or all time for allocated features) anyOf: - type: number - type: "null" usage: description: The total cumulative usage consumed in the current cycle across all subscriptions (or all time for allocated features) anyOf: - type: number - type: "null" included_usage: description: The total amount of usage included in the customer's plan(s) for this feature anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next cycle anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the included usage. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" breakdown: description: Detailed breakdown by interval for features with multiple intervals anyOf: - type: array items: type: object properties: interval: description: The reset interval for this feature breakdown anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" balance: description: The remaining available balance for this interval. Only present for metered features anyOf: - type: number - type: "null" usage: description: The total amount of usage consumed in the current cycle anyOf: - type: number - type: "null" included_usage: description: The amount of usage included in the customer's plan for this interval anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next billing period anyOf: - type: number - type: "null" usage_limit: description: The maximum usage allowed for this feature. null if unlimited or no limit is set anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the usage limit. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" required: - interval additionalProperties: false - type: "null" usage_limit: description: If this feature has a price, the usage limit indicates the maximum amount of usage the customer can use of this feature. anyOf: - type: number - type: "null" required: - id - type additionalProperties: false invoices: description: The invoices for this entity. Returned only if 'invoices' is passed into the expand parameter. type: array items: type: object properties: product_ids: description: Array of product IDs included in this invoice example: - pro_plan - addon_feature type: array items: type: string stripe_id: description: The Stripe invoice ID example: in_1A2B3C4D5E6F7G8H type: string status: description: The status of the invoice example: paid type: string total: description: The total amount of the invoice example: 2999 type: number currency: description: The currency code for the invoice example: usd type: string created_at: description: Timestamp when the invoice was created example: 1759247877000 type: number hosted_invoice_url: description: URL to the Stripe-hosted invoice page example: https://invoice.stripe.com/i/acct_123/test_456 anyOf: - type: string - type: "null" required: - product_ids - stripe_id - status - total - currency - created_at additionalProperties: false required: - id - name - created_at - env additionalProperties: false EntityData: description: Entity data for creating an entity type: object properties: feature_id: description: The feature ID that this entity is associated with type: string name: description: Name of the entity type: string required: - feature_id additionalProperties: false CustomerFeature: description: Customer feature object returned by the API type: object properties: id: description: The ID of the feature type: string type: description: The type of the feature type: string enum: - static - boolean - single_use - continuous_use - credit_system name: description: The name of the feature anyOf: - type: string - type: "null" interval: description: The billing interval (e.g., 'month', 'year') or 'multiple' if the feature has different intervals across subscriptions anyOf: - anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: string const: multiple - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" unlimited: description: Whether the feature has unlimited usage with no restrictions or limits anyOf: - type: boolean - type: "null" balance: description: The remaining available balance across all subscriptions for this feature (or all time for allocated features) anyOf: - type: number - type: "null" usage: description: The total cumulative usage consumed in the current cycle across all subscriptions (or all time for allocated features) anyOf: - type: number - type: "null" included_usage: description: The total amount of usage included in the customer's plan(s) for this feature anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next cycle anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the included usage. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" breakdown: description: Detailed breakdown by interval for features with multiple intervals anyOf: - type: array items: type: object properties: interval: description: The reset interval for this feature breakdown anyOf: - type: string enum: - lifetime - minute - hour - day - week - month - quarter - semi_annual - year - type: "null" interval_count: description: The number of intervals between usage resets anyOf: - type: number - type: "null" balance: description: The remaining available balance for this interval. Only present for metered features anyOf: - type: number - type: "null" usage: description: The total amount of usage consumed in the current cycle anyOf: - type: number - type: "null" included_usage: description: The amount of usage included in the customer's plan for this interval anyOf: - type: number - type: "null" next_reset_at: description: Unix timestamp (in milliseconds) when the usage counter will reset for the next billing period anyOf: - type: number - type: "null" usage_limit: description: The maximum usage allowed for this feature. null if unlimited or no limit is set anyOf: - type: number - type: "null" overage_allowed: description: Whether the customer can continue using the feature beyond the usage limit. If false, access is blocked when limit is reached anyOf: - type: boolean - type: "null" required: - interval additionalProperties: false - type: "null" usage_limit: description: If this feature has a price, the usage limit indicates the maximum amount of usage the customer can use of this feature. anyOf: - type: number - type: "null" required: - id - type additionalProperties: false securitySchemes: secretKey: type: http scheme: bearer bearerFormat: JWT