> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Invoices

> Lists invoices with cursor pagination and optional filters (customer, entity, status, processor). Pass `start_cursor: ""` (or omit) for the first page; use `next_cursor` from a prior response for subsequent pages.

export const DynamicResponseExample = ({json, statusCode = "200"}) => {
  const toCamelCase = str => {
    return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
  };
  const convertKeysToCamelCase = obj => {
    if (Array.isArray(obj)) {
      return obj.map(item => convertKeysToCamelCase(item));
    }
    if (obj !== null && typeof obj === "object") {
      return Object.keys(obj).reduce((acc, key) => {
        const camelKey = toCamelCase(key);
        acc[camelKey] = convertKeysToCamelCase(obj[key]);
        return acc;
      }, {});
    }
    return obj;
  };
  const [isTypeScript, setIsTypeScript] = useState(() => {
    if (typeof window !== "undefined") {
      try {
        const lang = localStorage.getItem("code");
        return JSON.parse(lang) === "typescript";
      } catch {
        return true;
      }
    }
    return true;
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      if (event.detail?.key === "code") {
        try {
          const value = JSON.parse(event.detail.value);
          setIsTypeScript(value === "typescript");
        } catch {}
      }
    };
    const pollInterval = setInterval(() => {
      try {
        const lang = localStorage.getItem("code");
        const value = JSON.parse(lang);
        setIsTypeScript(value === "typescript");
      } catch {}
    }, 300);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, []);
  const camelCaseJson = useMemo(() => convertKeysToCamelCase(json), [json]);
  const snakeCaseString = JSON.stringify(json, null, 2);
  const camelCaseString = JSON.stringify(camelCaseJson, null, 2);
  return <ResponseExample>
			{isTypeScript ? <CodeBlock language="json" filename={statusCode}>
					{camelCaseString}
				</CodeBlock> : <CodeBlock language="json" filename={statusCode}>
					{snakeCaseString}
				</CodeBlock>}
		</ResponseExample>;
};

export const DynamicResponseField = ({children, name, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedName = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(name) : name;
    } catch {
      return name;
    }
  }, [name, lang]);
  return <ResponseField name={resolvedName} {...props}>
			{children}
		</ResponseField>;
};

export const DynamicParamField = ({children, body, path, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedBody = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(body) : body;
    } catch {
      return body;
    }
  }, [body, lang]);
  const resolvedPath = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(path) : path;
    } catch {
      return path;
    }
  }, [path, lang]);
  return <ParamField body={resolvedBody} path={resolvedPath} {...props}>
			{children}
		</ParamField>;
};

### Body Parameters

<DynamicParamField body="start_cursor" type="string">
  Opaque pagination cursor. Empty string (default) requests the first page; use next\_cursor from a prior response for subsequent pages.
</DynamicParamField>

<DynamicParamField body="limit" type="integer">
  Number of items to return. Default 50, hard ceiling 5000.
</DynamicParamField>

<DynamicParamField body="customer_id" type="string">
  Filter invoices to a single customer by ID.
</DynamicParamField>

<DynamicParamField body="entity_id" type="string">
  Filter invoices to a single entity by ID. Must be provided together with customer\_id, since entity IDs are only unique per customer.
</DynamicParamField>

<DynamicParamField body="status" type="('draft' | 'open' | 'void' | 'paid' | 'uncollectible')[]">
  Filter by invoice status (draft, open, paid, void, uncollectible).
</DynamicParamField>

<DynamicParamField body="processor_types" type="('stripe' | 'revenuecat')[]">
  Filter by billing processor (stripe, revenuecat). Invoices recorded before processor tracking count as stripe.
</DynamicParamField>

### Response

<DynamicResponseField name="list" type="object[]">
  Items for current page.

  <Expandable title="properties">
    <DynamicResponseField name="plan_ids" type="string[]">
      Array of plan IDs included in this invoice
    </DynamicResponseField>

    <DynamicResponseField name="stripe_id" type="string">
      The Stripe invoice ID
    </DynamicResponseField>

    <DynamicResponseField name="processor_type" type="'stripe' | 'revenuecat'">
      The billing processor that owns this invoice.
    </DynamicResponseField>

    <DynamicResponseField name="status" type="string">
      The status of the invoice
    </DynamicResponseField>

    <DynamicResponseField name="total" type="number">
      The total amount of the invoice
    </DynamicResponseField>

    <DynamicResponseField name="currency" type="string">
      The currency code for the invoice
    </DynamicResponseField>

    <DynamicResponseField name="created_at" type="number">
      Timestamp when the invoice was created
    </DynamicResponseField>

    <DynamicResponseField name="hosted_invoice_url" type="string | null">
      URL to the Stripe-hosted invoice page
    </DynamicResponseField>

    <DynamicResponseField name="id" type="string">
      The Autumn invoice ID
    </DynamicResponseField>

    <DynamicResponseField name="customer_id" type="string | null">
      The ID of the customer this invoice belongs to. Null for customers created without an ID.
    </DynamicResponseField>

    <DynamicResponseField name="entity_id" type="string | null">
      The ID of the entity this invoice belongs to, if entity-scoped
    </DynamicResponseField>

    <DynamicResponseField name="amount_paid" type="number | null">
      The amount paid on the invoice. Null on invoices recorded before amounts paid were tracked.
    </DynamicResponseField>

    <DynamicResponseField name="refunded_amount" type="number">
      The total amount refunded on the invoice
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="next_cursor" type="string | null">
  Opaque cursor for the next page. Null when there are no more results.
</DynamicResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "list": [
      {
        "id": "inv_2b3c4d5e6f7g8h",
        "customer_id": "cus_123",
        "entity_id": null,
        "plan_ids": [
          "pro_plan"
        ],
        "stripe_id": "in_1A2B3C4D5E6F7G8H",
        "processor_type": "stripe",
        "status": "paid",
        "total": 29.99,
        "amount_paid": 29.99,
        "refunded_amount": 0,
        "currency": "usd",
        "created_at": 1759247877000,
        "hosted_invoice_url": "https://invoice.stripe.com/i/acct_123/test_456"
      }
    ],
    "next_cursor": null
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi POST /v1/invoices.list
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.3.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths:
  /v1/invoices.list:
    post:
      tags:
        - invoices
      description: >-
        Lists invoices with cursor pagination and optional filters (customer,
        entity, status, processor). Pass `start_cursor: ""` (or omit) for the
        first page; use `next_cursor` from a prior response for subsequent
        pages.
      operationId: listInvoices
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            default: 2.3.0
          x-speakeasy-globals-hidden: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_cursor:
                  type: string
                  default: ''
                  description: >-
                    Opaque pagination cursor. Empty string (default) requests
                    the first page; use next_cursor from a prior response for
                    subsequent pages.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 5000
                  default: 50
                  description: Number of items to return. Default 50, hard ceiling 5000.
                customer_id:
                  type: string
                  description: Filter invoices to a single customer by ID.
                entity_id:
                  type: string
                  description: >-
                    Filter invoices to a single entity by ID. Must be provided
                    together with customer_id, since entity IDs are only unique
                    per customer.
                status:
                  type: array
                  items:
                    enum:
                      - draft
                      - open
                      - void
                      - paid
                      - uncollectible
                    type: string
                  description: >-
                    Filter by invoice status (draft, open, paid, void,
                    uncollectible).
                processor_types:
                  type: array
                  items:
                    enum:
                      - stripe
                      - revenuecat
                    type: string
                  description: >-
                    Filter by billing processor (stripe, revenuecat). Invoices
                    recorded before processor tracking count as stripe.
              title: ListInvoicesParams
              examples:
                - start_cursor: ''
                  limit: 10
                  customer_id: cus_123
                  status:
                    - open
                    - paid
            example:
              start_cursor: ''
              limit: 10
              customer_id: cus_123
              status:
                - open
                - paid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    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
                        processor_type:
                          enum:
                            - stripe
                            - revenuecat
                          type: string
                          default: stripe
                          description: The billing processor that owns this invoice.
                        status:
                          type: string
                          description: The status of the invoice
                        total:
                          type: number
                          description: The total amount of the invoice
                        currency:
                          type: string
                          description: The currency code for the invoice
                        created_at:
                          type: number
                          description: Timestamp when the invoice was created
                        hosted_invoice_url:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: URL to the Stripe-hosted invoice page
                        id:
                          type: string
                          description: The Autumn invoice ID
                        customer_id:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: >-
                            The ID of the customer this invoice belongs to. Null
                            for customers created without an ID.
                        entity_id:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: >-
                            The ID of the entity this invoice belongs to, if
                            entity-scoped
                        amount_paid:
                          anyOf:
                            - type: number
                            - type: 'null'
                          description: >-
                            The amount paid on the invoice. Null on invoices
                            recorded before amounts paid were tracked.
                        refunded_amount:
                          type: number
                          description: The total amount refunded on the invoice
                      required:
                        - plan_ids
                        - stripe_id
                        - status
                        - total
                        - currency
                        - created_at
                        - id
                        - customer_id
                        - entity_id
                        - amount_paid
                        - refunded_amount
                    description: Items for current page.
                  next_cursor:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      Opaque cursor for the next page. Null when there are no
                      more results.
                required:
                  - list
                  - next_cursor
                examples:
                  - list:
                      - id: inv_2b3c4d5e6f7g8h
                        customer_id: cus_123
                        entity_id: null
                        plan_ids:
                          - pro_plan
                        stripe_id: in_1A2B3C4D5E6F7G8H
                        processor_type: stripe
                        status: paid
                        total: 29.99
                        amount_paid: 29.99
                        refunded_amount: 0
                        currency: usd
                        created_at: 1759247877000
                        hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456
                    next_cursor: null
              example:
                list:
                  - id: inv_2b3c4d5e6f7g8h
                    customer_id: cus_123
                    entity_id: null
                    plan_ids:
                      - pro_plan
                    stripe_id: in_1A2B3C4D5E6F7G8H
                    processor_type: stripe
                    status: paid
                    total: 29.99
                    amount_paid: 29.99
                    refunded_amount: 0
                    currency: usd
                    created_at: 1759247877000
                    hosted_invoice_url: https://invoice.stripe.com/i/acct_123/test_456
                next_cursor: null
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.invoices.list({
              limit: 10,
              customerId: "cus_123",
              status: [
                "open",
                "paid",
              ],
            });
        - lang: python
          label: Python (SDK)
          source: |-
            from autumn_sdk import Autumn

            autumn = Autumn(secret_key="am_sk_test...")

            res = autumn.invoices.list(
                start_cursor="",
                limit=10,
                customer_id="cus_123",
                status=[
                    "open",
                    "paid",
                ],
            )
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````