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
security:
  - bearerAuth: [Authorization]
paths:
  /customers:
    get:
      security:
        - secretKeyAuth: []
      summary: List customers
      description: Retrieve a paginated list of customers
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 10
            maximum: 100
            default: 10
          description: Maximum number of customers to return
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of customers to skip before returning results
      x-code-samples:
        - lang: typescript
          source: |
            import { Autumn as autumn } from 'autumn-js';

            const { data } = await autumn.customers.list({ limit: 10, offset: 0 });

        - lang: curl
          source: |
            curl 'https://api.useautumn.com/v1/customers?limit=10&offset=0' \
            -H 'Authorization: Bearer am_sk_1234567890'

      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      $ref: "#/components/schemas/Customer"
                  total:
                    type: integer
                    description: Total number of customers available
                  limit:
                    type: integer
                    description: Maximum number of customers returned
                  offset:
                    type: integer
                    description: Number of customers skipped before returning results
    post:
      description: Create a new Autumn customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  description: Your unique identifier for the customer
                email:
                  type: string
                  description: Customer's email address
                name:
                  type: string
                  description: Customer's name
                fingerprint:
                  type: string
                  description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
      x-code-samples:
        - lang: typescript
          source: |
            import { Autumn as autumn } from 'autumn-js';

            const { data } = await autumn.customers.create({
              id: 'user_123',
              name: 'John Yeo',
              email: 'john@example.com'
            });

        - lang: curl
          source: |
            curl -X POST 'https://api.useautumn.com/v1/customers' \
            -H 'Authorization: Bearer am_sk_1234567890' \
            -H 'Content-Type: application/json' \
            -d '{
              "id": "user_123",
              "name": "John Yeo",
              "email": "john@example.com"
            }'
        - lang: python
          source: |
            import asyncio
            from autumn import Autumn

            autumn = Autumn('am_sk_1234567890')

            async def main():
                customer = await autumn.customers.create(
                    id='user_123',
                    name='John Yeo',
                    email='john@example.com'
                )

            asyncio.run(main())
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
              example:
                $ref: "#/components/examples/CustomerResponse/value"

  /customers/{customer_id}:
    get:
      security:
        - secretKeyAuth: []
      summary: Get customer details
      description: Retrieve detailed information about a specific customer including their subscriptions, add-ons, and entitlements
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
          description: Your unique identifier for the customer
        - name: expand
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum: ["invoices", "rewards", "trials_used", "entities", "referrals", "payment_method"]
          style: form
          explode: false
          description: Array of additional data to include in the customer response. Options include invoices, rewards, trials_used, entities, referrals, payment_method
      x-code-samples:
        - lang: typescript
          source: |
            import { Autumn as autumn } from 'autumn-js';

            const { data } = await autumn.customers.get('user_123');

        - lang: curl
          source: |
            curl 'https://api.useautumn.com/v1/customers/user_123' \
            -H 'Authorization: Bearer am_sk_1234567890'

        - lang: python
          source: |
            import asyncio
            from autumn import Autumn

            autumn = Autumn('am_sk_1234567890')

            async def main():
                customer = await autumn.customers.get('user_123')

            asyncio.run(main())
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
              example:
                $ref: "#/components/examples/CustomerResponse/value"
    post:
      security:
        - secretKeyAuth: []
      summary: Update customer details
      description: Update information for an existing customer
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
          description: Your unique identifier for the customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: New ID to update the customer to (eg if switching from user to org)
                name:
                  type: string
                  description: The customer's full name
                email:
                  type: string
                  format: email
                  description: The customer's email address
                fingerprint:
                  type: string
                  description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
      x-code-samples:
        - lang: typescript
          source: |
            import { Autumn as autumn } from 'autumn-js';

            const { data } = await autumn.customers.update('user_123', {
              name: 'John Yeo',
              email: 'john@example.com'
            });

        - lang: curl
          source: |
            curl -X POST 'https://api.useautumn.com/v1/customers/user_123' \
            -H 'Authorization: Bearer am_sk_1234567890' \
            -H 'Content-Type: application/json' \
            -d '{
              "name": "John Yeo",
              "email": "john@example.com"
            }'

        - lang: python
          source: |
            import asyncio
            from autumn import Autumn

            autumn = Autumn('am_sk_1234567890')

            async def main():
                customer = await autumn.customers.update(
                    customer_id='user_123',
                    name='John Yeo',
                    email='john@example.com'
                )

            asyncio.run(main())
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
              example:
                $ref: "#/components/examples/CustomerResponse/value"
    delete:
      security:
        - secretKeyAuth: []
      summary: Delete a customer
      description: Delete a customer
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
          description: Your unique identifier for the customer
        - name: delete_in_stripe
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Also delete the linked Stripe customer
      x-code-samples:
        - lang: typescript
          source: |
            import { Autumn as autumn } from 'autumn-js';

            const { data } = await autumn.customers.delete('user_123', {
              delete_in_stripe: true
            });

        - lang: curl
          source: |
            curl -X DELETE 'https://api.useautumn.com/v1/customers/user_123?delete_in_stripe=true' \
            -H 'Authorization: Bearer am_sk_1234567890'


      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Customer"
              example:
                $ref: "#/components/examples/CustomerResponse/value"
components:
  examples:
    CustomerResponse:
      value:
        autumn_id: "cus_2w5dzidzFD1cESxOGnn9frVuVcm"
        created_at: 1677649423000
        env: "production"
        id: "user_123"
        name: "John Yeo"
        email: "john@example.com"
        fingerprint: ""
        stripe_id: "cus_abc123"
        products:
          [
            {
              id: "pro",
              name: "Pro Plan",
              group: "",
              status: "active",
              started_at: 1677649423000,
              canceled_at: null,
              current_period_start: 1677649423000,
              current_period_end: 1680327823000,
            },
          ]
        features:
          [
            {
              feature_id: "messages",
              unlimited: false,
              interval: "month",
              balance: 80,
              usage: 20,
              included_usage: 100,
              next_reset_at: 1680327823000,
            },
          ]
  schemas:
    CustomerProduct:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          nullable: true
        group:
          type: string
          nullable: true
        status:
          type: string
          enum: [active, past_due, trialing]
        started_at:
          type: integer
          format: int64
        canceled_at:
          type: integer
          format: int64
          nullable: true
        current_period_start:
          type: integer
          format: int64
          nullable: true
        current_period_end:
          type: integer
          format: int64
          nullable: true
    CustomerFeature:
      type: object
      properties:
        feature_id:
          type: string
        unlimited:
          type: boolean
        interval:
          type: string
          enum: [month, year]
          nullable: true
        balance:
          type: integer
          nullable: true
        usage:
          type: integer
          nullable: true
        included_usage:
          type: integer
          nullable: true
        next_reset_at:
          type: integer
          format: int64
          nullable: true
    Customer:
      type: object
      properties:
        autumn_id:
          type: string
          description: Autumn's internal identifier for the customer
        created_at:
          type: integer
          format: int64
          description: Timestamp of customer creation in milliseconds since epoch
        env:
          type: string
          description: Environment the customer is in
          enum: [production, sandbox]
        id:
          type: string
          description: Your unique identifier for the customer
        name:
          type: string
          description: Customer's name
        email:
          type: string
          description: Customer's email address
        fingerprint:
          type: string
          description: Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
        stripe_id:
          type: string
          description: Stripe customer ID
        products:
          type: array
          description: List of products the customer has access to
          items:
            $ref: "#/components/schemas/CustomerProduct"
        features:
          type: array
          description: List of features the customer has access to
          items:
            $ref: "#/components/schemas/CustomerFeature"
        invoices:
          type: array
          description: Invoices for this customer (only included when expand=invoices)
          items:
            $ref: "#/components/schemas/Invoice"
    Product:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the product
        name:
          type: string
          description: Display name of the product
        group:
          type: string
          description: Product grouping category
        status:
          type: string
          enum: [active, past_due, trialing]
          description: Current status of the product subscription.
        created_at:
          type: integer
          format: int64
          description: Timestamp of product creation in milliseconds since epoch
        canceled_at:
          type: integer
          format: int64
          nullable: true
          description: Timestamp of cancellation, if applicable
        processor:
          type: object
          properties:
            type:
              type: string
              description: Payment processor type
            subscription_id:
              type: string
              nullable: true
              description: Payment processor's subscription ID
        prices:
          type: array
          items:
            type: object
            properties:
              amount:
                type: number
                description: Price amount in the default currency
              interval:
                type: string
                enum: [month, year]
                description: Billing interval for the price
    Entitlement:
      type: object
      properties:
        feature_id:
          type: string
          description: Unique identifier for the feature
        interval:
          type: string
          description: Time interval for the entitlement
        balance:
          type: integer
          nullable: true
          description: Remaining balance of the entitlement
        unlimited:
          type: boolean
          description: Whether the entitlement has unlimited usage
        used:
          type: integer
          description: Amount of the entitlement that has been used
    Invoice:
      type: object
      properties:
        product_ids:
          type: array
          items:
            type: string
          description: List of product IDs included in this invoice
        stripe_id:
          type: string
          description: Stripe invoice ID
        status:
          type: string
          enum: [paid, unpaid, void]
          description: Payment status of the invoice
        total:
          type: number
          description: Total amount of the invoice
        currency:
          type: string
          description: Currency code for the invoice
        created_at:
          type: integer
          format: int64
          description: Timestamp of invoice creation in milliseconds since epoch
        hosted_invoice_url:
          type: string
          format: uri
          description: URL to view the hosted invoice page
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    publishableKeyAuthAttach:
      type: http
      scheme: bearer
      description: You can use your Secret or Publishable key for this endpoint. Using your Publishable Key will always return a `checkout_url`. Using your Secret Key allows you to handle payments automatically (eg, for plan upgrades).
    secretKeyAuth:
      type: http
      scheme: bearer
      description: Your secret key must be used as the Bearer token for this endpoint.
    publishableKeyAuthEntitled:
      type: http
      scheme: bearer
      description: You can use your Secret or Publishable key for this endpoint. To include usage event tracking however, you must use your Secret key.