> ## 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.

# Create Balance

> Create a balance for a customer feature.

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="customer_id" type="string" required>
  The ID of the customer.
</DynamicParamField>

<DynamicParamField body="feature_id" type="string" required>
  The ID of the feature.
</DynamicParamField>

<DynamicParamField body="entity_id" type="string">
  The ID of the entity for entity-scoped balances (e.g., per-seat limits).
</DynamicParamField>

<DynamicParamField body="included_grant" type="number">
  The initial balance amount to grant. For metered features, this is the number of units the customer can use.
</DynamicParamField>

<DynamicParamField body="unlimited" type="boolean">
  If true, the balance has unlimited usage. Cannot be combined with 'included\_grant'.
</DynamicParamField>

<DynamicParamField body="reset" type="object">
  Reset configuration for the balance. If not provided, the balance is a one-time grant that never resets.

  <Expandable title="properties">
    <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
      The interval at which the balance resets (e.g., 'month', 'day', 'year').
    </DynamicParamField>

    <DynamicParamField body="interval_count" type="number">
      Number of intervals between resets. Defaults to 1 (e.g., interval\_count: 2 with interval: 'month' resets every 2 months).
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

<DynamicParamField body="rollover" type="object">
  Rollover configuration for the balance.

  <Expandable title="properties">
    <DynamicParamField body="max" type="number | null" />

    <DynamicParamField body="max_percentage" type="number | null" />

    <DynamicParamField body="duration" type="'month' | 'forever'" />

    <DynamicParamField body="length" type="number" required />
  </Expandable>
</DynamicParamField>

<DynamicParamField body="expires_at" type="number">
  Unix timestamp (milliseconds) when the balance expires. Mutually exclusive with reset.
</DynamicParamField>

<DynamicParamField body="next_reset_at" type="number">
  Unix timestamp (milliseconds) for the first reset boundary, allowing a custom (e.g. shorter) first period. Requires 'reset', and must occur before 'expires\_at' if both are provided. Subsequent resets advance by one reset interval from this boundary.
</DynamicParamField>

<DynamicParamField body="balance_id" type="string">
  A unique identifier for this balance. Use this to target the balance in future update / delete calls.
</DynamicParamField>

### Response

<DynamicResponseField name="success" type="boolean" />


## OpenAPI

````yaml openapi POST /v1/balances.create
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/balances.create:
    post:
      tags:
        - balances
      description: Create a balance for a customer feature.
      operationId: createBalance
      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:
                customer_id:
                  type: string
                  description: The ID of the customer.
                feature_id:
                  type: string
                  description: The ID of the feature.
                entity_id:
                  type: string
                  description: >-
                    The ID of the entity for entity-scoped balances (e.g.,
                    per-seat limits).
                included_grant:
                  type: number
                  description: >-
                    The initial balance amount to grant. For metered features,
                    this is the number of units the customer can use.
                unlimited:
                  type: boolean
                  description: >-
                    If true, the balance has unlimited usage. Cannot be combined
                    with 'included_grant'.
                reset:
                  type: object
                  properties:
                    interval:
                      enum:
                        - one_off
                        - minute
                        - hour
                        - day
                        - week
                        - month
                        - quarter
                        - semi_annual
                        - year
                      type: string
                      description: >-
                        The interval at which the balance resets (e.g., 'month',
                        'day', 'year').
                    interval_count:
                      type: number
                      description: >-
                        Number of intervals between resets. Defaults to 1 (e.g.,
                        interval_count: 2 with interval: 'month' resets every 2
                        months).
                  required:
                    - interval
                  description: >-
                    Reset configuration for the balance. If not provided, the
                    balance is a one-time grant that never resets.
                rollover:
                  type: object
                  properties:
                    max:
                      anyOf:
                        - type: number
                        - type: 'null'
                    max_percentage:
                      anyOf:
                        - type: number
                        - type: 'null'
                    duration:
                      enum:
                        - month
                        - forever
                      type: string
                      default: month
                    length:
                      type: number
                  required:
                    - length
                  description: Rollover configuration for the balance.
                expires_at:
                  type: number
                  description: >-
                    Unix timestamp (milliseconds) when the balance expires.
                    Mutually exclusive with reset.
                next_reset_at:
                  type: number
                  description: >-
                    Unix timestamp (milliseconds) for the first reset boundary,
                    allowing a custom (e.g. shorter) first period. Requires
                    'reset', and must occur before 'expires_at' if both are
                    provided. Subsequent resets advance by one reset interval
                    from this boundary.
                balance_id:
                  type: string
                  description: >-
                    A unique identifier for this balance. Use this to target the
                    balance in future update / delete calls.
              required:
                - customer_id
                - feature_id
              title: CreateBalanceParams
              examples:
                - customer_id: cus_123
                  feature_id: api_calls
                  included: 1000
                  reset:
                    interval: month
            example:
              customer_id: cus_123
              feature_id: api_calls
              included: 1000
              reset:
                interval: month
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                required:
                  - success
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.balances.create({
              customerId: "cus_123",
              featureId: "api_calls",
              reset: {
                interval: "month",
              },
            });
        - lang: python
          label: Python (SDK)
          source: |-
            from autumn_sdk import Autumn

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

            res = autumn.balances.create(
                customer_id="cus_123",
                feature_id="api_calls",
                reset={
                    "interval": "month",
                },
            )
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````