> ## 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 Invoice
> Creates a standalone send-invoice Stripe invoice from catalog pricing and custom charges. Quantities are billable units, exclusive of any included usage; Autumn applies billing units and tiers. Nothing about the customer's plans, balances or subscriptions changes. Pass preview: true to get the calculated lines and totals without creating an invoice.
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
{isTypeScript ?
{camelCaseString}
:
{snakeCaseString}
}
;
};
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
{children}
;
};
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
{children}
;
};
### Body Parameters
The customer to invoice.
The catalog plan (or variant) whose pricing to use.
Plan version. Defaults to the active version.
Pricing overrides applied to this invoice only. The catalog and the customer's plan are not changed.
Override the plan's base price for this invoice. Pass null or an amount of 0 to omit the base price line.
Base price amount for the plan, in major currency units (e.g. dollars).
Billing interval (e.g. 'month', 'year').
Number of intervals per billing cycle. Defaults to 1.
Bill this line under an existing Stripe price instead of an inline one.
Stripe price ID. For prepaid with included > 0 this is the V2 price.
Override feature pricing for this invoice. Only pricing fields are accepted; grants, resets and rollovers are not part of an invoice.
The feature whose pricing is overridden on this invoice.
Pricing to use for this feature on this invoice.
Price per billing\_units after included usage. Either 'amount' or 'tiers' is required.
Tiered pricing. Either 'amount' or 'tiers' is required.
Per-currency amounts for this tier. Tier boundaries ('to') are shared across all currencies.
Three-letter Stripe-supported currency code (e.g. 'eur', 'gbp').
Per-unit amount for this tier in this currency.
Flat amount for this tier in this currency, if the tier uses one.
Billing interval. For consumable features, should match reset.interval.
Number of intervals per billing cycle. Defaults to 1.
Units per price increment. Usage is rounded UP when billed (e.g. billing\_units=100 means 101 rounds to 200).
'prepaid' for upfront payment (seats), 'usage\_based' for pay-as-you-go.
Bill this line under an existing Stripe price instead of an inline one.
Stripe price ID. For prepaid with included > 0 this is the V2 price.
For credit-system features: a credit rate card to use when converting `usage` on this invoice.
For credit system features: replaces the feature's credit\_schema entirely for customers on this plan.
ID of the metered feature that draws from this credit system.
Number of metered-feature units priced together. Defaults to one when omitted.
Named rates chosen by event properties. The most specific match sets the rate; with no match the item's own rate applies.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Breaks ties between dimensions that match the same number of keys. Higher wins.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Named adjustments chosen by event properties. Every match applies: factors multiply, then adds are summed.
Event properties this entry applies to. Every key must equal the tracked property, compared as strings.
Multiplies the matched rate. All matching multipliers stack.
Added to the rate after every factor is applied, in credits per billing-unit group.
Inclusive upper usage boundary for this graduated tier. The final tier must be 'inf'.
Credits consumed per billing-unit group within this tier.
Credits consumed per billing-unit group.
The feature to bill.
Which of the feature's prices to use: 'prepaid' or 'usage\_based'.
Billable feature units in total, exclusive of any included usage. Not per seat or per entity. For a credit-system feature this is the number of credits.
For credit-system features: billable units of the source features, converted through the credit rate card. Mutually exclusive with quantity.
The metered feature whose units are being converted.
Billable units of the metered feature. Converted to the credit-system feature through its rate card.
Event properties used to pick the rate card dimension and multipliers.
Whether to prorate this line against period\_start / period\_end. Defaults to true for prepaid and false for usage-based.
The license plan linked to the parent plan.
Billable seats, exclusive of any included seats.
Override the license's per-seat price on this invoice.
Base price amount for the plan, in major currency units (e.g. dollars).
Billing interval (e.g. 'month', 'year').
Number of intervals per billing cycle. Defaults to 1.
Bill this line under an existing Stripe price instead of an inline one.
Stripe price ID. For prepaid with included > 0 this is the V2 price.
Feature charges priced through the license plan.
The feature to bill.
Which of the feature's prices to use: 'prepaid' or 'usage\_based'.
Billable feature units in total, exclusive of any included usage. Not per seat or per entity. For a credit-system feature this is the number of credits.
For credit-system features: billable units of the source features, converted through the credit rate card. Mutually exclusive with quantity.
The metered feature whose units are being converted.
Billable units of the metered feature. Converted to the credit-system feature through its rate card.
Event properties used to pick the rate card dimension and multipliers.
Whether to prorate this line against period\_start / period\_end. Defaults to true for prepaid and false for usage-based.
Whether to prorate seat charges against period\_start / period\_end. Defaults to true.
Discounts applied only to this plan's lines.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
Whether to prorate the base price against period\_start / period\_end. Defaults to true.
Charges that are not tied to any plan or feature.
Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
Description for the line item.
Discounts applied to the whole invoice.
The ID of the reward to apply as a discount.
The promotion code to apply as a discount.
ID of an invoice template whose footer, memo and default payment terms are applied.
Days until the invoice is due. Defaults to the template's terms, then the org default.
Date of issue printed on the invoice, in milliseconds. Defaults to now; cannot be in the future.
When payment is due, in milliseconds. Must be in the future; takes precedence over net\_terms\_days.
Stripe tax rate ID (txr\_...) applied to every line.
Start of the period being invoiced, in milliseconds. Prorated lines are charged for period\_start → period\_end against one price interval starting at period\_start.
End of the period being invoiced, in milliseconds.
If true, returns the calculated lines and totals without creating an invoice.
### Response
The created invoice. Null when preview is true.
Array of plan IDs included in this invoice
The Stripe invoice ID
The billing processor that owns this invoice.
The status of the invoice
The total amount of the invoice
The currency code for the invoice
Timestamp when the invoice was created
URL to the Stripe-hosted invoice page
The Autumn invoice ID
The ID of the customer this invoice belongs to. Null for customers created without an ID.
The ID of the entity this invoice belongs to, if entity-scoped
The amount paid on the invoice. Null on invoices recorded before amounts paid were tracked.
The total amount refunded on the invoice
Line items on the invoice, one per line as shown in Stripe. Capped at 100. Empty for invoices recorded before line item storage.
The Autumn invoice line item ID. Stable across reads, and can be used to reference this line in later calls.
Description of the invoice line item
Timestamp when the billing period starts
Timestamp when the billing period ends
The plan this line item came from. Null for lines with no Autumn plan behind them.
The ID of the feature associated with this line item
The name of the feature associated with this line item
Quantity actually charged on this line. Null on fixed-price lines.
Amount charged on this line, pre-discount and pre-tax. Negative for credits.
How this line splits by entity. Empty for customer-level lines. Only populated for invoices finalized after entity attribution shipped.
The entity this share of the line item is attributed to
Quantity charged to this entity. Null on fixed-price lines.
Amount attributed to this entity, pre-discount and pre-tax
The customer's Stripe credit balance and how much of it this invoice consumes.
Stripe customer credit balance available, expressed as a positive number in major currency units.
How much of that balance this invoice consumes, capped at its total. The rest stays on the customer.
Three-letter currency code.
What the customer pays: the total less any credit applied.
```json 200 theme={null}
{
"invoice": {
"id": "inv_2b3c4d5e6f7g8h",
"customer_id": "cus_123",
"entity_id": null,
"plan_ids": [
"pro_plan"
],
"stripe_id": "in_1A2B3C4D5E6F7G8H",
"processor_type": "stripe",
"status": "open",
"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",
"items": [
{
"id": "invoice_li_2b3c4d5e6f7g8h",
"description": "Pro plan",
"plan_id": "pro_plan",
"feature_id": null,
"feature_name": null,
"quantity": null,
"amount": 20,
"period_start": 1759247877000,
"period_end": 1761839877000,
"entities": []
},
{
"id": "invoice_li_3c4d5e6f7g8h9i",
"description": "AI credits",
"plan_id": "pro_plan",
"feature_id": "ai_credits",
"feature_name": "AI Credits",
"quantity": 4995,
"amount": 9.99,
"period_start": 1759247877000,
"period_end": 1761839877000,
"entities": [
{
"entity_id": "acme-docs-prod",
"quantity": 4995,
"amount": 9.99
}
]
}
]
},
"preview": {
"currency": "usd",
"lines": [],
"subtotal": 29.99,
"discount_total": 0,
"tax": null,
"total": 29.99,
"invoice_credits": {
"balance": 10,
"applied": 10,
"currency": "usd"
},
"amount_due": 19.99,
"due_date": 1761839877000
}
}
```
## OpenAPI
````yaml openapi POST /v1/invoices.create
openapi: 3.1.0
info:
title: Autumn API
version: 2.4.0
servers:
- url: https://api.useautumn.com
description: Production server
security:
- secretKey: []
paths:
/v1/invoices.create:
post:
tags:
- invoices
description: >-
Creates a standalone send-invoice Stripe invoice from catalog pricing
and custom charges. Quantities are billable units, exclusive of any
included usage; Autumn applies billing units and tiers. Nothing about
the customer's plans, balances or subscriptions changes. Pass preview:
true to get the calculated lines and totals without creating an invoice.
operationId: createInvoice
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
default: 2.4.0
x-speakeasy-globals-hidden: true
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customer_id:
type: string
description: The customer to invoice.
plans:
type: array
items:
type: object
properties:
plan_id:
type: string
description: The catalog plan (or variant) whose pricing to use.
version:
type: number
description: Plan version. Defaults to the active version.
customize:
type: object
properties:
price:
anyOf:
- type: object
properties:
amount:
type: number
description: >-
Base price amount for the plan, in major
currency units (e.g. dollars).
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: Billing interval (e.g. 'month', 'year').
interval_count:
type: number
description: >-
Number of intervals per billing cycle.
Defaults to 1.
default: 1
processors:
type: object
properties:
stripe:
anyOf:
- type: object
properties:
price_id:
type: string
description: >-
Stripe price ID. For prepaid with
included > 0 this is the V2 price.
required:
- price_id
- type: 'null'
x-atmn-mapping: true
description: >-
Bill this line under an existing Stripe
price instead of an inline one.
required:
- amount
- interval
additionalProperties: false
- type: 'null'
description: >-
Override the plan's base price for this invoice.
Pass null or an amount of 0 to omit the base price
line.
items:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The feature whose pricing is overridden on
this invoice.
price:
type: object
properties:
amount:
type: number
description: >-
Price per billing_units after included
usage. Either 'amount' or 'tiers' is
required.
tiers:
type: array
items:
type: object
properties:
to:
anyOf:
- type: number
- const: inf
amount:
type: number
flat_amount:
type: number
additional_currencies:
type: array
items:
type: object
properties:
currency:
type: string
description: >-
Three-letter Stripe-supported currency
code (e.g. 'eur', 'gbp').
amount:
type: number
description: >-
Per-unit amount for this tier in this
currency.
flat_amount:
type: number
description: >-
Flat amount for this tier in this
currency, if the tier uses one.
required:
- currency
description: >-
Per-currency amounts for this tier. Tier
boundaries ('to') are shared across all
currencies.
required:
- to
description: >-
Tiered pricing. Either 'amount' or
'tiers' is required.
tier_behavior:
enum:
- graduated
- volume
type: string
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: >-
Billing interval. For consumable
features, should match reset.interval.
interval_count:
type: number
description: >-
Number of intervals per billing cycle.
Defaults to 1.
default: 1
billing_units:
type: number
default: 1
description: >-
Units per price increment. Usage is
rounded UP when billed (e.g.
billing_units=100 means 101 rounds to
200).
billing_method:
enum:
- prepaid
- usage_based
type: string
description: >-
'prepaid' for upfront payment (seats),
'usage_based' for pay-as-you-go.
processors:
type: object
properties:
stripe:
anyOf:
- type: object
properties:
price_id:
type: string
description: >-
Stripe price ID. For prepaid with
included > 0 this is the V2 price.
required:
- price_id
- type: 'null'
x-atmn-mapping: true
description: >-
Bill this line under an existing Stripe
price instead of an inline one.
required:
- interval
- billing_method
additionalProperties: false
description: >-
Pricing to use for this feature on this
invoice.
feature_override:
type: object
properties:
credit_schema:
type: array
items:
anyOf:
- type: object
properties:
metered_feature_id:
type: string
minLength: 1
description: >-
ID of the metered feature that draws
from this credit system.
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced
together. Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- {}
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
when this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties.
The most specific match sets the rate;
with no match the item's own rate
applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All
matching multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is
applied, in credits per billing-unit
group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event
properties. Every match applies: factors
multiply, then adds are summed.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- inf
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- metered_feature_id
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
metered_feature_id:
type: string
minLength: 1
description: >-
ID of the metered feature that draws
from this credit system.
billing_units:
type: number
exclusiveMinimum: 0
description: >-
Number of metered-feature units priced
together. Defaults to one when omitted.
dimensions:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
anyOf:
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
tier_behavior:
const: graduated
tiers:
type: array
minItems: 1
items:
type: object
properties:
to:
anyOf:
- type: number
exclusiveMinimum: 0
- enum:
- {}
type: string
description: >-
Inclusive upper usage boundary for this
graduated tier. The final tier must be
'inf'.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
within this tier.
required:
- to
- credit_cost
required:
- match
- tier_behavior
- tiers
additionalProperties: false
- type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: >-
Breaks ties between dimensions that
match the same number of keys. Higher
wins.
credit_cost:
type: number
minimum: 0
description: >-
Credits consumed per billing-unit group
when this dimension matches.
required:
- match
- credit_cost
additionalProperties: false
description: >-
Named rates chosen by event properties.
The most specific match sets the rate;
with no match the item's own rate
applies.
multipliers:
type: object
propertyNames:
type: string
minLength: 1
maxLength: 64
additionalProperties:
type: object
properties:
match:
type: object
propertyNames:
type: string
additionalProperties:
anyOf:
- type: string
- type: number
- type: boolean
description: >-
Event properties this entry applies to.
Every key must equal the tracked
property, compared as strings.
factor:
type: number
exclusiveMinimum: 0
description: >-
Multiplies the matched rate. All
matching multipliers stack.
add:
type: number
description: >-
Added to the rate after every factor is
applied, in credits per billing-unit
group.
required:
- match
additionalProperties: false
description: >-
Named adjustments chosen by event
properties. Every match applies: factors
multiply, then adds are summed.
credit_cost:
type: number
minimum: 0
description: Credits consumed per billing-unit group.
required:
- metered_feature_id
- credit_cost
additionalProperties: false
description: >-
For credit system features: replaces the
feature's credit_schema entirely for
customers on this plan.
additionalProperties: false
description: >-
For credit-system features: a credit rate
card to use when converting `usage` on this
invoice.
required:
- feature_id
additionalProperties: false
description: >-
Override feature pricing for this invoice. Only
pricing fields are accepted; grants, resets and
rollovers are not part of an invoice.
additionalProperties: false
title: InvoiceCustomize
description: >-
Pricing overrides applied to this invoice only. The
catalog and the customer's plan are not changed.
feature_quantities:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature to bill.
billing_behavior:
enum:
- prepaid
- usage_based
type: string
description: >-
Which of the feature's prices to use: 'prepaid'
or 'usage_based'.
quantity:
type: number
minimum: 0
description: >-
Billable feature units in total, exclusive of
any included usage. Not per seat or per entity.
For a credit-system feature this is the number
of credits.
usage:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The metered feature whose units are being
converted.
quantity:
type: number
minimum: 0
description: >-
Billable units of the metered feature.
Converted to the credit-system feature
through its rate card.
properties:
type: object
propertyNames:
type: string
additionalProperties: {}
description: >-
Event properties used to pick the rate
card dimension and multipliers.
required:
- feature_id
- quantity
additionalProperties: false
description: >-
For credit-system features: billable units of
the source features, converted through the
credit rate card. Mutually exclusive with
quantity.
prorate:
type: boolean
description: >-
Whether to prorate this line against
period_start / period_end. Defaults to true for
prepaid and false for usage-based.
required:
- feature_id
- billing_behavior
additionalProperties: false
license_quantities:
type: array
items:
type: object
properties:
license_plan_id:
type: string
description: The license plan linked to the parent plan.
quantity:
type: integer
minimum: 0
maximum: 9007199254740991
description: Billable seats, exclusive of any included seats.
customize:
type: object
properties:
price:
anyOf:
- type: object
properties:
amount:
type: number
description: >-
Base price amount for the plan, in major
currency units (e.g. dollars).
interval:
enum:
- one_off
- week
- month
- quarter
- semi_annual
- year
type: string
description: Billing interval (e.g. 'month', 'year').
interval_count:
type: number
description: >-
Number of intervals per billing cycle.
Defaults to 1.
default: 1
processors:
type: object
properties:
stripe:
anyOf:
- type: object
properties:
price_id:
type: string
description: >-
Stripe price ID. For prepaid with
included > 0 this is the V2 price.
required:
- price_id
- type: 'null'
x-atmn-mapping: true
description: >-
Bill this line under an existing Stripe
price instead of an inline one.
required:
- amount
- interval
additionalProperties: false
- type: 'null'
additionalProperties: false
description: >-
Override the license's per-seat price on this
invoice.
feature_quantities:
type: array
items:
type: object
properties:
feature_id:
type: string
description: The feature to bill.
billing_behavior:
enum:
- prepaid
- usage_based
type: string
description: >-
Which of the feature's prices to use:
'prepaid' or 'usage_based'.
quantity:
type: number
minimum: 0
description: >-
Billable feature units in total, exclusive
of any included usage. Not per seat or per
entity. For a credit-system feature this
is the number of credits.
usage:
type: array
items:
type: object
properties:
feature_id:
type: string
description: >-
The metered feature whose units are
being converted.
quantity:
type: number
minimum: 0
description: >-
Billable units of the metered feature.
Converted to the credit-system feature
through its rate card.
properties:
type: object
propertyNames:
type: string
additionalProperties: {}
description: >-
Event properties used to pick the rate
card dimension and multipliers.
required:
- feature_id
- quantity
additionalProperties: false
description: >-
For credit-system features: billable units
of the source features, converted through
the credit rate card. Mutually exclusive
with quantity.
prorate:
type: boolean
description: >-
Whether to prorate this line against
period_start / period_end. Defaults to
true for prepaid and false for
usage-based.
required:
- feature_id
- billing_behavior
additionalProperties: false
description: Feature charges priced through the license plan.
prorate:
type: boolean
description: >-
Whether to prorate seat charges against
period_start / period_end. Defaults to true.
required:
- license_plan_id
- quantity
additionalProperties: false
discounts:
type: array
items:
type: object
properties:
reward_id:
type: string
description: The ID of the reward to apply as a discount.
promotion_code:
type: string
description: The promotion code to apply as a discount.
title: AttachDiscount
description: >-
A discount to apply. Can be either a reward ID or a
promotion code.
description: Discounts applied only to this plan's lines.
prorate:
type: boolean
description: >-
Whether to prorate the base price against period_start
/ period_end. Defaults to true.
required:
- plan_id
additionalProperties: false
custom_line_items:
type: array
items:
type: object
properties:
amount:
type: number
description: >-
Amount in dollars for this line item (e.g. 10.50). Can
be negative for credits.
description:
type: string
description: Description for the line item.
required:
- amount
- description
description: Charges that are not tied to any plan or feature.
discounts:
type: array
items:
type: object
properties:
reward_id:
type: string
description: The ID of the reward to apply as a discount.
promotion_code:
type: string
description: The promotion code to apply as a discount.
title: AttachDiscount
description: >-
A discount to apply. Can be either a reward ID or a
promotion code.
description: Discounts applied to the whole invoice.
invoice_template_id:
type: string
description: >-
ID of an invoice template whose footer, memo and default
payment terms are applied.
net_terms_days:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
exclusiveMinimum: 0
description: >-
Days until the invoice is due. Defaults to the template's
terms, then the org default.
issue_date:
type: integer
minimum: 0
maximum: 9007199254740991
description: >-
Date of issue printed on the invoice, in milliseconds.
Defaults to now; cannot be in the future.
due_date:
type: integer
minimum: 0
maximum: 9007199254740991
description: >-
When payment is due, in milliseconds. Must be in the future;
takes precedence over net_terms_days.
tax_rate_id:
type: string
description: Stripe tax rate ID (txr_...) applied to every line.
period_start:
type: integer
minimum: 0
maximum: 9007199254740991
description: >-
Start of the period being invoiced, in milliseconds.
Prorated lines are charged for period_start → period_end
against one price interval starting at period_start.
period_end:
type: integer
minimum: 0
maximum: 9007199254740991
description: End of the period being invoiced, in milliseconds.
preview:
type: boolean
description: >-
If true, returns the calculated lines and totals without
creating an invoice.
required:
- customer_id
additionalProperties: false
title: CreateInvoiceParams
examples:
- customer_id: cus_123
net_terms_days: 30
plans:
- plan_id: pro
feature_quantities:
- feature_id: seats
billing_behavior: prepaid
quantity: 5
- feature_id: credits
billing_behavior: usage_based
quantity: 2500
custom_line_items:
- description: Implementation services
amount: 500
example:
customer_id: cus_123
net_terms_days: 30
plans:
- plan_id: pro
feature_quantities:
- feature_id: seats
billing_behavior: prepaid
quantity: 5
- feature_id: credits
billing_behavior: usage_based
quantity: 2500
custom_line_items:
- description: Implementation services
amount: 500
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
invoice:
anyOf:
- 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
items:
type: array
items:
type: object
properties:
id:
type: string
description: >-
The Autumn invoice line item ID. Stable
across reads, and can be used to reference
this line in later calls.
description:
type: string
description: Description of the invoice line item
period_start:
anyOf:
- type: number
- type: 'null'
description: Timestamp when the billing period starts
period_end:
anyOf:
- type: number
- type: 'null'
description: Timestamp when the billing period ends
plan_id:
anyOf:
- type: string
- type: 'null'
description: >-
The plan this line item came from. Null for
lines with no Autumn plan behind them.
feature_id:
anyOf:
- type: string
- type: 'null'
description: >-
The ID of the feature associated with this
line item
feature_name:
anyOf:
- type: string
- type: 'null'
description: >-
The name of the feature associated with this
line item
quantity:
anyOf:
- type: number
- type: 'null'
description: >-
Quantity actually charged on this line. Null
on fixed-price lines.
amount:
type: number
description: >-
Amount charged on this line, pre-discount
and pre-tax. Negative for credits.
entities:
type: array
items:
type: object
properties:
entity_id:
type: string
description: >-
The entity this share of the line item
is attributed to
quantity:
anyOf:
- type: number
- type: 'null'
description: >-
Quantity charged to this entity. Null on
fixed-price lines.
amount:
type: number
description: >-
Amount attributed to this entity,
pre-discount and pre-tax
required:
- entity_id
- quantity
- amount
description: >-
How this line splits by entity. Empty for
customer-level lines. Only populated for
invoices finalized after entity attribution
shipped.
required:
- id
- description
- period_start
- period_end
- plan_id
- feature_id
- feature_name
- quantity
- amount
- entities
description: >-
Line items on the invoice, one per line as shown
in Stripe. Capped at 100. Empty for invoices
recorded before line item storage.
required:
- plan_ids
- stripe_id
- status
- total
- currency
- created_at
- id
- customer_id
- entity_id
- amount_paid
- refunded_amount
- type: 'null'
description: The created invoice. Null when preview is true.
preview:
type: object
properties:
currency:
type: string
lines:
type: array
items:
type: object
properties:
plan_id:
anyOf:
- type: string
- type: 'null'
feature_id:
anyOf:
- type: string
- type: 'null'
description:
type: string
amount:
type: number
amount_after_discounts:
type: number
quantity:
anyOf:
- type: number
- type: 'null'
prorated:
type: boolean
period_start:
anyOf:
- type: number
- type: 'null'
period_end:
anyOf:
- type: number
- type: 'null'
required:
- plan_id
- feature_id
- description
- amount
- amount_after_discounts
- quantity
- prorated
- period_start
- period_end
subtotal:
type: number
discount_total:
type: number
tax:
anyOf:
- type: object
properties:
total:
type: number
amount_inclusive:
type: number
amount_exclusive:
type: number
status:
enum:
- complete
- incomplete
type: string
required:
- total
- amount_inclusive
- amount_exclusive
- status
- type: 'null'
total:
type: number
invoice_credits:
type: object
properties:
balance:
type: number
description: >-
Stripe customer credit balance available,
expressed as a positive number in major currency
units.
applied:
type: number
description: >-
How much of that balance this invoice consumes,
capped at its total. The rest stays on the
customer.
currency:
type: string
description: Three-letter currency code.
required:
- balance
- currency
description: >-
The customer's Stripe credit balance and how much of
it this invoice consumes.
amount_due:
type: number
description: >-
What the customer pays: the total less any credit
applied.
issue_date:
type: number
due_date:
anyOf:
- type: number
- type: 'null'
required:
- currency
- lines
- subtotal
- discount_total
- tax
- total
- amount_due
- issue_date
- due_date
required:
- invoice
- preview
examples:
- invoice:
id: inv_2b3c4d5e6f7g8h
customer_id: cus_123
entity_id: null
plan_ids:
- pro_plan
stripe_id: in_1A2B3C4D5E6F7G8H
processor_type: stripe
status: open
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
items:
- id: invoice_li_2b3c4d5e6f7g8h
description: Pro plan
plan_id: pro_plan
feature_id: null
feature_name: null
quantity: null
amount: 20
period_start: 1759247877000
period_end: 1761839877000
entities: []
- id: invoice_li_3c4d5e6f7g8h9i
description: AI credits
plan_id: pro_plan
feature_id: ai_credits
feature_name: AI Credits
quantity: 4995
amount: 9.99
period_start: 1759247877000
period_end: 1761839877000
entities:
- entity_id: acme-docs-prod
quantity: 4995
amount: 9.99
preview:
currency: usd
lines: []
subtotal: 29.99
discount_total: 0
tax: null
total: 29.99
invoice_credits:
balance: 10
applied: 10
currency: usd
amount_due: 19.99
due_date: 1761839877000
example:
invoice:
id: inv_2b3c4d5e6f7g8h
customer_id: cus_123
entity_id: null
plan_ids:
- pro_plan
stripe_id: in_1A2B3C4D5E6F7G8H
processor_type: stripe
status: open
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
items:
- id: invoice_li_2b3c4d5e6f7g8h
description: Pro plan
plan_id: pro_plan
feature_id: null
feature_name: null
quantity: null
amount: 20
period_start: 1759247877000
period_end: 1761839877000
entities: []
- id: invoice_li_3c4d5e6f7g8h9i
description: AI credits
plan_id: pro_plan
feature_id: ai_credits
feature_name: AI Credits
quantity: 4995
amount: 9.99
period_start: 1759247877000
period_end: 1761839877000
entities:
- entity_id: acme-docs-prod
quantity: 4995
amount: 9.99
preview:
currency: usd
lines: []
subtotal: 29.99
discount_total: 0
tax: null
total: 29.99
invoice_credits:
balance: 10
applied: 10
currency: usd
amount_due: 19.99
due_date: 1761839877000
x-codeSamples:
- lang: typescript
label: Typescript (SDK)
source: |-
import { Autumn } from 'autumn-js'
const autumn = new Autumn()
const result = await autumn.invoices.create({
customerId: "cus_123",
plans: [
{
planId: "pro",
featureQuantities: [
{
featureId: "seats",
billingBehavior: "prepaid",
quantity: 5,
},
{
featureId: "credits",
billingBehavior: "usage_based",
quantity: 2500,
},
],
},
],
customLineItems: [
{
amount: 500,
description: "Implementation services",
},
],
netTermsDays: 30,
});
- lang: python
label: Python (SDK)
source: |-
from autumn_sdk import Autumn
autumn = Autumn(secret_key="am_sk_test...")
res = autumn.invoices.create(
customer_id="cus_123",
plans=[
{
"plan_id": "pro",
"feature_quantities": [
{
"feature_id": "seats",
"billing_behavior": "prepaid",
"quantity": 5,
},
{
"feature_id": "credits",
"billing_behavior": "usage_based",
"quantity": 2500,
},
],
},
],
custom_line_items=[
{
"amount": 500,
"description": "Implementation services",
},
],
net_terms_days=30,
)
components:
securitySchemes:
secretKey:
type: http
scheme: bearer
bearerFormat: JWT
````