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
    CustomerExpand:
      enum:
        - invoices
        - trials_used
        - rewards
        - entities
        - referrals
        - payment_method
        - subscriptions.plan
        - purchases.plan
        - balances.feature
      title: CustomerExpand
    Customer:
      type: object
      properties:
        name:
          anyOf:
            - type: string
            - type: "null"
        email:
          anyOf:
            - type: string
            - type: "null"
        fingerprint:
          anyOf:
            - type: string
            - type: "null"
        stripe_id:
          anyOf:
            - type: string
            - type: "null"
        env:
          enum:
            - sandbox
            - live
        metadata:
          type: object
          propertyNames: {}
          additionalProperties: {}
        send_email_receipts:
          type: boolean
        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
              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:
                    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
              hosted_invoice_url:
                anyOf:
                  - type: string
                  - type: "null"
                description: URL to the Stripe-hosted invoice page
            required:
              - plan_ids
              - stripe_id
              - status
              - total
              - currency
        entities:
          type: array
          items:
            type: object
            properties:
              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
              env:
                enum:
                  - sandbox
                  - live
                description: The environment (sandbox/live)
            required:
              - name
              - 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:
                      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:
                      - 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:
                  name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                      - type: "null"
                required: []
              reward_applied:
                type: boolean
            required:
              - program_id
              - customer
              - reward_applied
        payment_method:
          anyOf:
            - {}
            - type: "null"
      required:
        - name
        - email
        - fingerprint
        - stripe_id
        - env
        - metadata
        - send_email_receipts
        - subscriptions
        - purchases
        - balances
    Plan:
      type: object
      properties:
        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
              required:
                - amount
                - interval
            - type: "null"
        items:
          type: array
          items:
            type: object
            properties:
              feature_id:
                type: string
              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"
              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
        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:
        - name
        - description
        - group
        - version
        - add_on
        - auto_enable
        - price
        - items
        - env
        - archived
        - base_variant_id
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /v1/customers.getOrCreate:
    post:
      operationId: getOrCreate
      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
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
      parameters:
        - &a1
          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",
            });
  /v1/products:
    get:
      operationId: list
      summary: List Plans
      tags:
        - plans
      parameters:
        - *a1
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: "#/components/schemas/Plan"
                required:
                  - list
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.plans.list();
  /v1/attach:
    post:
      operationId: attach
      tags:
        - billing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                options:
                  anyOf:
                    - type: array
                      items:
                        type: object
                        properties:
                          feature_id:
                            type: string
                          quantity:
                            type: number
                          reset_after_trial_end:
                            type: boolean
                            default: false
                        required:
                          - feature_id
                    - type: "null"
                version:
                  type: number
                free_trial:
                  anyOf:
                    - type: object
                      properties:
                        length:
                          type: number
                        duration:
                          enum:
                            - day
                            - month
                            - year
                        card_required:
                          type: boolean
                          default: true
                      required:
                        - length
                        - duration
                    - type: "null"
                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. Should be null for fixed price
                          items.
                      included_usage:
                        anyOf:
                          - anyOf:
                              - type: number
                              - const: inf
                          - type: "null"
                        description: The amount of usage included for this feature (per interval).
                      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: Interval count of the feature.
                      entity_feature_id:
                        anyOf:
                          - type: string
                          - type: "null"
                        description: The feature ID of the entity (like seats) to track sub-balances
                          for.
                      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.
                      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.
                      billing_units:
                        anyOf:
                          - type: number
                          - type: "null"
                        description: The billing units of the product item (eg $1 for 30 credits).
                      reset_usage_when_enabled:
                        anyOf:
                          - type: boolean
                          - type: "null"
                        description: Whether the usage should be reset when the product is enabled.
                product_id:
                  type: string
                invoice:
                  type: boolean
                enable_product_immediately:
                  type: boolean
                finalize_invoice:
                  type: boolean
                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
                adjustable_quantity:
                  type: boolean
              required:
                - product_id
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_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
      parameters:
        - *a1
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.billing.attach({
              productId: "<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