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

# Insert Invoices

> Inserts or updates up to 500 historical invoices without reading or mutating the billing processor.

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="invoices" type="object[]" required>
  Invoices to insert or update, in response order.

  <Expandable title="properties">
    <DynamicParamField body="customer_id" type="string" required>
      The customer this invoice belongs to.
    </DynamicParamField>

    <DynamicParamField body="plan_ids" type="string[]">
      Plan IDs represented by this invoice.
    </DynamicParamField>

    <DynamicParamField body="stripe_id" type="string" required>
      The processor's stable invoice ID.
    </DynamicParamField>

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

    <DynamicParamField body="status" type="'draft' | 'open' | 'void' | 'paid' | 'uncollectible'" required>
      The invoice status.
    </DynamicParamField>

    <DynamicParamField body="total" type="number" required>
      The invoice total in major currency units.
    </DynamicParamField>

    <DynamicParamField body="amount_paid" type="number | null">
      The amount paid in major currency units.
    </DynamicParamField>

    <DynamicParamField body="refunded_amount" type="number">
      The refunded amount in major currency units.
    </DynamicParamField>

    <DynamicParamField body="currency" type="string">
      The currency code. Defaults to the organization's default currency.
    </DynamicParamField>

    <DynamicParamField body="created_at" type="number" required>
      The invoice creation timestamp in milliseconds.
    </DynamicParamField>

    <DynamicParamField body="hosted_invoice_url" type="string | null">
      The hosted invoice URL, when available.
    </DynamicParamField>
  </Expandable>
</DynamicParamField>

### Response

<DynamicResponseField name="invoices" type="object[]">
  Inserted or updated invoices in request order.

  <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">
      The customer this invoice belongs to.
    </DynamicResponseField>

    <DynamicResponseField name="amount_paid" type="number | null">
      The amount paid in major currency units.
    </DynamicResponseField>

    <DynamicResponseField name="refunded_amount" type="number">
      The refunded amount in major currency units.
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "invoices": [
      {
        "id": "inv_2b3c4d5e6f7g8h",
        "customer_id": "cus_123",
        "plan_ids": [
          "pro"
        ],
        "stripe_id": "in_legacy_123",
        "processor_type": "stripe",
        "status": "paid",
        "total": 29.99,
        "amount_paid": 29.99,
        "refunded_amount": 0,
        "currency": "usd",
        "created_at": 1451606400000,
        "hosted_invoice_url": "https://billing.example.com/invoices/legacy-123"
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi POST /v1/invoices.insert
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.insert:
    post:
      tags:
        - invoices
      description: >-
        Inserts or updates up to 500 historical invoices without reading or
        mutating the billing processor.
      operationId: insertInvoices
      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:
                invoices:
                  type: array
                  maxItems: 500
                  items:
                    type: object
                    properties:
                      customer_id:
                        type: string
                        description: The customer this invoice belongs to.
                      plan_ids:
                        type: array
                        items:
                          type: string
                        default: []
                        description: Plan IDs represented by this invoice.
                      stripe_id:
                        type: string
                        description: The processor's stable invoice ID.
                      processor_type:
                        enum:
                          - stripe
                          - revenuecat
                        type: string
                        default: stripe
                        description: The billing processor that owns this invoice.
                      status:
                        enum:
                          - draft
                          - open
                          - void
                          - paid
                          - uncollectible
                        type: string
                        description: The invoice status.
                      total:
                        type: number
                        description: The invoice total in major currency units.
                      amount_paid:
                        anyOf:
                          - type: number
                          - type: 'null'
                        default: null
                        description: The amount paid in major currency units.
                      refunded_amount:
                        type: number
                        default: 0
                        description: The refunded amount in major currency units.
                      currency:
                        type: string
                        description: >-
                          The currency code. Defaults to the organization's
                          default currency.
                      created_at:
                        type: number
                        description: The invoice creation timestamp in milliseconds.
                      hosted_invoice_url:
                        anyOf:
                          - type: string
                          - type: 'null'
                        default: null
                        description: The hosted invoice URL, when available.
                    required:
                      - customer_id
                      - stripe_id
                      - status
                      - total
                      - created_at
                  description: Invoices to insert or update, in response order.
              required:
                - invoices
              title: InsertInvoicesParams
              examples:
                - invoices:
                    - customer_id: cus_123
                      plan_ids:
                        - pro
                      stripe_id: in_legacy_123
                      processor_type: stripe
                      status: paid
                      total: 29.99
                      amount_paid: 29.99
                      refunded_amount: 0
                      currency: usd
                      created_at: 1451606400000
                      hosted_invoice_url: https://billing.example.com/invoices/legacy-123
            example:
              invoices:
                - customer_id: cus_123
                  plan_ids:
                    - pro
                  stripe_id: in_legacy_123
                  processor_type: stripe
                  status: paid
                  total: 29.99
                  amount_paid: 29.99
                  refunded_amount: 0
                  currency: usd
                  created_at: 1451606400000
                  hosted_invoice_url: https://billing.example.com/invoices/legacy-123
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  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
                        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:
                          type: string
                          description: The customer this invoice belongs to.
                        amount_paid:
                          anyOf:
                            - type: number
                            - type: 'null'
                          description: The amount paid in major currency units.
                        refunded_amount:
                          type: number
                          description: The refunded amount in major currency units.
                      required:
                        - plan_ids
                        - stripe_id
                        - status
                        - total
                        - currency
                        - created_at
                        - id
                        - customer_id
                        - amount_paid
                        - refunded_amount
                    description: Inserted or updated invoices in request order.
                required:
                  - invoices
                examples:
                  - invoices:
                      - id: inv_2b3c4d5e6f7g8h
                        customer_id: cus_123
                        plan_ids:
                          - pro
                        stripe_id: in_legacy_123
                        processor_type: stripe
                        status: paid
                        total: 29.99
                        amount_paid: 29.99
                        refunded_amount: 0
                        currency: usd
                        created_at: 1451606400000
                        hosted_invoice_url: https://billing.example.com/invoices/legacy-123
              example:
                invoices:
                  - id: inv_2b3c4d5e6f7g8h
                    customer_id: cus_123
                    plan_ids:
                      - pro
                    stripe_id: in_legacy_123
                    processor_type: stripe
                    status: paid
                    total: 29.99
                    amount_paid: 29.99
                    refunded_amount: 0
                    currency: usd
                    created_at: 1451606400000
                    hosted_invoice_url: https://billing.example.com/invoices/legacy-123
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.invoices.insert({
              invoices: [
                {
                  customerId: "cus_123",
                  planIds: [
                    "pro",
                  ],
                  stripeId: "in_legacy_123",
                  status: "paid",
                  total: 29.99,
                  amountPaid: 29.99,
                  currency: "usd",
                  createdAt: 1451606400000,
                  hostedInvoiceUrl: "https://billing.example.com/invoices/legacy-123",
                },
              ],
            });
        - lang: python
          label: Python (SDK)
          source: |-
            from autumn_sdk import Autumn

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

            res = autumn.invoices.insert(
                invoices=[
                    {
                        "customer_id": "cus_123",
                        "plan_ids": [
                            "pro",
                        ],
                        "stripe_id": "in_legacy_123",
                        "status": "paid",
                        "total": 29.99,
                        "amount_paid": 29.99,
                        "currency": "usd",
                        "created_at": 1451606400000,
                        "hosted_invoice_url": "https://billing.example.com/invoices/legacy-123",
                    },
                ],
            )
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````