openapi: 3.0.1
info:
  title: Autumn API
  description: API to interact with Autumn
  license:
    name: MIT
  version: 1.0.0

servers:
  - url: https://api.useautumn.com/v1/batch

security:
  - secretKeyAuth: []

paths:
  /customers:
    post:
      summary: Batch retrieve customers
      description: Retrieve a paginated list of customers with their associated products and entitlements
      operationId: batchGetCustomers
      tags:
        - Batch Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - limit
              properties:
                limit:
                  type: integer
                  description: Number of customers to retrieve (Must be between 10 and 100)
                  example: 100
                offset:
                  type: integer
                  default: 0
                  description: Number of customers to skip for pagination
                  example: 100
                statuses:
                  type: array
                  default: ["active"]
                  items:
                    type: string
                    enum:
                      - scheduled
                      - active
                      - past_due
                      - expired
                      - unknown
                      - trialing
                  description: Filter customers by product status
                  example: ["expired", "past_due"]
            examples:
              basic:
                summary: Basic request
                value:
                  limit: 50
              with-filters:
                summary: With status filters
                value:
                  limit: 100
                  offset: 100
                  statuses: ["expired", "past_due"]
      responses:
        "200":
          description: Successful response with paginated customer list
          content:
            application/json:
              schema:
                type: object
                required:
                  - list
                  - total
                properties:
                  list:
                    type: array
                    items:
                      $ref: "#/components/schemas/Customer"
                    description: Array of customer objects
                  total:
                    type: integer
                    description: Total number of customers in the result set
                    example: 25
              examples:
                success:
                  summary: Successful response
                  value:
                    list:
                      - id: "John Doe"
                        created_at: 1756301935674
                        name: "John Doe"
                        email: "john@example.com"
                        fingerprint: null
                        stripe_id: null
                        env: "sandbox"
                        products:
                          - id: "free"
                            name: "free"
                            group: null
                            status: "active"
                            canceled_at: null
                            started_at: 1756310054931
                            is_default: true
                            is_add_on: false
                            version: 2
                            items:
                              - type: "feature"
                                feature_id: "message"
                                feature_type: "single_use"
                                feature:
                                  id: "message"
                                  name: "Send Message"
                                  type: "single_use"
                                  display:
                                    singular: "message"
                                    plural: "messages"
                                included_usage: 1000
                                interval: "month"
                                interval_count: 1
                                reset_usage_when_enabled: true
                                entity_feature_id: null
                        features:
                          message:
                            id: "message"
                            name: "Send Message"
                            type: "single_use"
                            unlimited: false
                            balance: 1000
                            usage: 0
                            included_usage: 1000
                            next_reset_at: 1758980335931
                            interval: "month"
                            interval_count: 1
                            overage_allowed: false
                        metadata: {}
                      - id: "John Doe"
                        created_at: 1756301935674
                        name: "John Doe"
                        email: "john@example.com"
                        fingerprint: null
                        stripe_id: null
                        env: "sandbox"
                        products:
                          - id: "free"
                            name: "free"
                            group: null
                            status: "active"
                            canceled_at: null
                            started_at: 1756310054931
                            is_default: true
                            is_add_on: false
                            version: 2
                            items:
                              - type: "feature"
                                feature_id: "message"
                                feature_type: "single_use"
                                feature:
                                  id: "message"
                                  name: "Send Message"
                                  type: "single_use"
                                  display:
                                    singular: "message"
                                    plural: "messages"
                                included_usage: 1000
                                interval: "month"
                                interval_count: 1
                                reset_usage_when_enabled: true
                                entity_feature_id: null
                        features:
                          message:
                            id: "message"
                            name: "Send Message"
                            type: "single_use"
                            unlimited: false
                            balance: 1000
                            usage: 0
                            included_usage: 1000
                            next_reset_at: 1758980335931
                            interval: "month"
                            interval_count: 1
                            overage_allowed: false
                        metadata: {}
                    total: 1

components:
  securitySchemes:
    secretKeyAuth:
      type: http
      scheme: bearer
      description: Use your Autumn Secret Key as the Bearer token.

  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
          description: Customer ID provided by user
          example: "cus_123"
        name:
          type: string
          description: Customer name
          example: "John Doe"
        email:
          type: string
          description: Customer email address
          example: "john@example.com"
        fingerprint:
          type: string
          description: Customer fingerprint for identification
          example: "fp_abc123"
        internal_id:
          type: string
          description: Internal Autumn customer ID
          example: "int_123"
        created_at:
          type: integer
          description: Customer creation timestamp (Unix timestamp in milliseconds)
          example: 1640995200000
        metadata:
          type: object
          description: Additional customer metadata
          additionalProperties: true
          example: {}
        customer_products:
          type: array
          items:
            $ref: "#/components/schemas/CustomerProduct"
          description: Associated customer products
        entitlements:
          type: array
          items:
            $ref: "#/components/schemas/CustomerEntitlement"
          description: Customer entitlements and balances

    CustomerProduct:
      type: object
      properties:
        id:
          type: string
          description: Customer product ID
        product_id:
          type: string
          description: Associated product ID
        status:
          type: string
          enum:
            - scheduled
            - active
            - past_due
            - expired
            - unknown
            - trialing
          description: Product status
        created_at:
          type: integer
          description: Product creation timestamp
        starts_at:
          type: integer
          description: Product start timestamp
        canceled_at:
          type: integer
          nullable: true
          description: Product cancellation timestamp
        ended_at:
          type: integer
          nullable: true
          description: Product end timestamp
        trial_ends_at:
          type: integer
          nullable: true
          description: Trial end timestamp
        quantity:
          type: integer
          description: Product quantity
          default: 1
        collection_method:
          type: string
          enum:
            - charge_automatically
            - send_invoice
          description: Payment collection method

    CustomerEntitlement:
      type: object
      properties:
        id:
          type: string
          description: Entitlement ID
        feature_id:
          type: string
          description: Associated feature ID
        balance:
          type: number
          description: Current balance
        adjustment:
          type: number
          description: Balance adjustment
        next_reset_at:
          type: integer
          nullable: true
          description: Next balance reset timestamp
        created_at:
          type: integer
          description: Entitlement creation timestamp

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Error code
              enum:
                - invalid_inputs
                - invalid_request
                - no_secret_key
                - invalid_secret_key
                - customers_not_found
                - internal_error
            message:
              type: string
              description: Human-readable error message