# Autumn Billing

> Autumn Billing is an Agent Skill for apps & automation published in the useautumn/autumn repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Performing Autumn billing actions — attaching plans, updating or canceling subscriptions, creating schedules, customizing terms, previewing charges, and applying billing changes. Use when the user wants to bill a customer, change a subscription, schedule plan changes, or preview billing impact.

- Skill name: `autumn-billing`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/useautumn/autumn/blob/HEAD/packages/agent-docs/generated/skills/autumn-billing/SKILL.md
- Repository: useautumn/autumn (2,613 GitHub stars when collected)

## SKILL.md

# Billing

Use this resource for billing actions: attaching plans, updating subscriptions, creating schedules, canceling or uncanceling subscriptions, and changing customer billing state.
Read `autumn://docs/concepts` to understand Autumn's model: Customer, Entity, Plan, Subscription, Purchase, Balance, Flag, and Billing Controls.

## Goal

- Map the user's billing request to one or more Autumn billing API calls.
- Build the params for those calls before previewing.
- Gather requirements in natural language; do not force the user to speak in Autumn field names.
- Preview only when the params are complete enough to represent the intended billing action.

## Workflow

- You MUST follow this checklist in order for every billing request.
- Read the org's agent rules with `getAgentRules` to understand how this org attaches plans to customers — its entity defaults, credit defaults, and org notes.
- Resolve targets (see Target resolution).
- Choose the operation (see Action selection).
- Collect action-specific params (see Param checklist).
- Resolve custom terms (see Customizations).
- Resolve timing (see Timing and schedules).
- Resolve invoice, checkout, and proration behavior (see Billing behavior).
- If one ambiguity changes which of the other questions apply, resolve it first on its own before gathering the rest.
- Gather all remaining missing questions from the checklist and ask them together.
- If there are no missing questions, call the preview tool.
- Surface the preview's immediate billing impact in one line, then immediately call the write tool — the write tool call itself IS the approval mechanism (it triggers your client's approval prompt/card before executing). Never ask for confirmation with a question tool or in prose.
- If params change, update them and repeat from the relevant checklist step.
- Once approved, apply the exact previewed billing action.

## Rules

- **A mutating billing action requires approval before it takes effect. The approval mechanism is the write tool call itself: calling `attach`/`updateSubscription`/`createSchedule` pauses for the user's approval before executing. Do NOT pre-confirm with `ask_question` or prose — that double-prompts the user.**
- **Apply the default billing params on every action unless the user explicitly asks otherwise — invoice mode (draft), enable immediately, and no proration. The full rules and field names are in the Billing behavior section below; follow them exactly.**
- Don't propose or promise steps outside what your tools can do. If the goal isn't reachable, say so plainly rather than inventing a workaround.
- Read this full resource before billing work and follow sections in order; later sections can define params that must be resolved before previewing.
- Monetary amounts are major currency units: `$1,150` -> `1150`, not `115000`.
- Slack billing requests usually expect immediate effect; use `plan_schedule: "immediate"` unless the user asks for end-of-cycle or future timing.
- If using `invoice_mode` and the customer has no email, ask for the email and call `updateCustomer` before previewing.
- Ask independent missing questions together in one concise message, using one bullet point per question.
- While gathering params, ask only for values needed to build the billing request; do not explain plan internals unless the user asks.
- If a customization is inferred, surface it for confirmation before previewing or writing. If its intent is ambiguous, ask before building — don't resolve it silently. When surfacing a customization, describe it as a patch (what was added/removed/changed vs the catalog plan), not a full restatement of every feature.
- If the plan prices a feature as prepaid, a bare amount for that feature ("put them on 4.5k credits") means `feature_quantities` — NOT an item customization. Never remove or replace a prepaid item to set how many units a customer gets; customize the item only when the user explicitly changes its pricing or included allowance.
- Before any trial action, re-read the Trials section in `autumn://docs/concepts`.
- Adding a trial for a customer who already has a paid subscription resets the Stripe billing cycle; warn the user and offer the `on_end: "revert"` flow, then let them choose.

## Target resolution

- Resolve IDs from the user's message before choosing params: customer, optional entity, and plan(s).
- If preloaded `listPlans` / `listFeatures` results are present, treat them as already-run tool results. Do not call them again unless the needed record is absent or the user asks to refresh.
- Search remaining unknowns with the relevant lookup tools; run independent lookups in parallel.
- If the user gives explicit IDs, verify they exist with the same lookup tools.
- Do not create plans. If the customer or entity is missing, ask whether to create it.
- If an explicit customer/entity/plan ID is found, move on. For plans, a perfect or very close name match is enough only if it maps to exactly one plan.
- If sibling plans share a base name but differ by variant (e.g. `scale` vs `scale_yearly`), the name alone is not a match; ask which variant before previewing, especially for interval-specific or custom terms.
- If an ID had to be inferred from a name or description, confirm the match with the user before moving on.
- If the found customer has no email, remember that and ask for it before any invoice or checkout step.

## Action selection

### Overview

- Usually choose `attach` or `updateSubscription`.
- Use `createSchedule` for multiple phases or when the request needs explicit control over future billing state.
- Use `attach` for a single plan attach even when it has `starts_at` or `ends_at`.
- Check the customer's existing subscriptions before choosing the action.

### attach

- Use when the customer/entity is not already on the target plan: new subscription, purchase, upgrade, downgrade, add-on, or one-off top-up.
- If they already have the target recurring plan, do not attach it again; use `updateSubscription`.
- One-off plans are always attached because each purchase/top-up is a new purchase.
- `attach` handles transitions: switching main plans expires the replaced plan, while add-ons are additive.
- Autumn determines upgrade vs downgrade from normalized base and prepaid prices.
- By default, `attach` tries to add the new plan to an existing Stripe subscription when possible; mid-cycle changes on that subscription can charge or credit prorations.
- Downgrades default to end-of-cycle scheduling through `plan_schedule`; upgrades usually apply immediately.

### updateSubscription

- Use when changing a plan the customer/entity is currently on.
- Main uses: prepaid feature quantity changes, cancel now/end-of-cycle, uncancel, custom plan edits, version/trial changes, and discounts.
- Use it for modifying the existing subscription state, not for moving to a different plan the customer is not on.

### createSchedule

- Use for explicit dated phases: contracts, future changes, multi-year pricing, or sequences like Pro for 6 months then Starter.
- Treat it like replacing the customer/entity's billing configuration for that scope with the listed phase states.
- The immediate phase previews like a transition from current state to the first phase, so prorations may apply.
- Each phase must still be valid: do not put two non-add-on main plans from the same group in one phase.
- Watch contracts for dates, year-by-year fees, ramps, delayed downgrades, or different packages over time.

### Notes

- Existing subscriptions decide `attach` vs `updateSubscription`; one-off plans are the main exception and are always attached.
- Preview responses describe the immediate billing impact: what is charged or credited now, plus future-cycle details when present.
- Schedules are explicit phase state. Use them when attach/update cannot express the required future configuration or level of control.

## Param checklist

- After target resolution, collect the params specific to the selected action.
- Before previewing, resolve any required `customize` params identified in Customizations.
- `attach`
  - If the plan has prepaid items and quantity is missing, ask for the quantity before previewing. Undefined quantity silently grants 0 units — never proceed on this default without asking.
  - If the prepaid quantity is known, include `feature_quantities`. Undefined `feature_quantities` defaults to 0 for that feature.
  - `feature_quantities.quantity` is inclusive of the plan item's included amount. Example: if 5,000 credits are included and $10/100 credits after, passing 6,000 means only the extra 1,000 credits are charged.
- `updateSubscription`
  - If intent is ambiguous, clarify before previewing; e.g. cancel now vs cancel at end of cycle.
  - Quantity change: include `feature_quantities`.
  - Cancel or uncancel: include `cancel_action`.
  - Custom terms: include `customize`.
  - Version, trial, or discount change: include the matching fields. (less common intent)
- `createSchedule`
  - Build ordered `phases[]`.
  - Each phase needs timing (`starts_at` or `starting_after`) and at least one `plans[]` entry.
- If a missing value changes billing impact, ask before previewing.

## Billing customizations

- For general `customize` patch rules and examples, read the concepts reference `packages/agent-docs/content/skills/concepts/references/customize.md` (generated as `autumn-concepts/references/customize.md`).
- Use `customize` for customer-specific plan terms in `attach`, `updateSubscription`, and `createSchedule`.
- A bare number with an interval but no `$` and no unit (e.g. "1k/yr", "2k/mo") is ambiguous between `customize.price` and a feature quantity; clarify before building.
- A clarifying answer resolves only that question — re-check the checklist before previewing. Example: the user picks "custom price" for "1k/mo"; the plan's prepaid quantity is still unanswered and must be asked.
- A list of what a customer "gets" is ambiguous: restating the plan, adding on top, or the exact set. If it changes what they receive vs the catalog plan, ask which before building.
- "Features" may mean only boolean access or may include credits/metered items; clarify scope before removing anything priced.
- When the same outcome can be expressed multiple ways, prefer the customization that preserves the catalog plan's existing item structure.
- If a plan name/id/context suggests an Enterprise or custom placeholder plan and the plan has no base price, ask whether they want to customize the base price.

### Same-shape pricing example

A plan prices `credits` as a prepaid, volume-tiered item (ladder `10k=$90, 50k=$400, inf=$700`). To give a customer 20k credits at a custom $150/mo, add a `20k=$150` tier into the existing ladder:

```json
{
  "customize": {
    "remove_items": [{ "feature_id": "credits", "billing_method": "prepaid" }],
    "add_items": [
      {
        "feature_id": "credits",
        "price": {
          "billing_method": "prepaid",
          "interval": "month",
          "tier_behavior": "volume",
          "tiers": [
            { "to": 10000, "flat_amount": 90 },
            { "to": 20000, "flat_amount": 150 },
            { "to": 50000, "flat_amount": 400 },
            { "to": "inf", "flat_amount": 700 }
          ]
        }
      }
    ]
  },
  "feature_quantities": [{ "feature_id": "credits", "quantity": 20000 }]
}
```

Carry the whole ladder over; don't replace it with just the custom tier or a flat base price.

### Use cases

- `updateSubscription`: customize the plan configuration the customer is already on.
  ```json
  {
    "customer_id": "cus_123",
    "plan_id": "pro",
    "customize": { "add_items": [{ "feature_id": "sso" }] }
  }
  ```

- `attach`: attach a plan with customer-specific base price or item changes.
  ```json
  {
    "customer_id": "cus_123",
    "plan_id": "pro",
    "customize": {
      "price": { "amount": 50, "interval": "month" },
      "add_items": [{ "feature_id": "credits", "included": 5000 }]
    }
  }
  ```

- `createSchedule`: customize the plan inside the phase that needs custom terms.
  ```json
  {
    "customer_id": "cus_123",
    "phases": [
      { "starts_at": "now", "plans": [{ "plan_id": "pro" }] },
      {
        "starts_at": "2027-06-12T00:00:00Z",
        "plans": [
          {
            "plan_id": "pro",
            "customize": { "price": { "amount": 75, "interval": "month" } }
          }
        ]
      }
    ]
  }
  ```

## Timing and schedules

### Default timing

- Do not set `starts_at` or `ends_at` unless the user gives a date, duration, backdate, future start, or explicit end date.
- If timing is ambiguous and affects billing impact, ask before previewing.

### attach timing

- To attach now, explicitly set `plan_schedule: "immediate"`; omitting it can schedule a lower- or zero-base-price plan for end of cycle.
- A downgrade (incoming base price genuinely lower than the current plan's) should be flagged to the user, asking whether to schedule it for end of cycle. A no-base-price plan (e.g. Enterprise/custom, priced per customer) is not a downgrade.
- Use `starts_at` for single-plan backdates or future starts; do not use `createSchedule` just for this.
- Backdating is only allowed when the customer has no existing Stripe subscription. If the API rejects it, explain that constraint.
- For future billing start with immediate access, set future `starts_at` and `enable_plan_immediately: true`; otherwise the user's plan is created with `scheduled` status in Autumn and access starts on the specified `starts_at`.
- Use `ends_at` only when the user gives an explicit end date or duration.

### updateSubscription timing

- Scheduling is only relevant for canceling at end of cycle.
- Immediate cancel, uncancel, quantity changes, and customizations do not need schedule params.

### createSchedule timing

- If the user describes phases relatively and gives no concrete dates (e.g. "year 1 $10k, year 2 $20k"), use `starts_at: "now"` on phase 1 and `starting_after` on later phases.
- If the user gives concrete phase dates, use explicit `starts_at` values; later `starts_at` values must align exactly with the intended boundary.
- Use a historical first `starts_at` only when the user explicitly asks for a past start.
- Future first-phase `starts_at` is not supported today.
- Resolve every phase's plan and customization before previewing.

### Date handling

- Autumn date params and responses are epoch milliseconds.
- Never interpret epoch milliseconds manually; use `dateToEpochMilliseconds`, `epochMillisecondsToDate`, or the most convenient accurate tool available, such as bash date utilities.
- Prefer ISO dates/timestamps in params when the schema allows them; the tool will convert.
- Present dates as `12 Jun 2026`; include `HH:MM` only when time matters.

## Billing behavior

### Invoice default

- Default operator-led billing actions to invoice mode: `invoice_mode.enabled: true` and `invoice_mode.finalize: false`, and grant access now (see Enable plan immediately for which field).
- Use invoice mode even when the immediate charge is $0, unless the user asks for checkout, self-serve, or direct charging.
- This grants access now while creating a draft Stripe invoice that the operator can review, edit, and send.
- Use explicit net terms from the user or contract in `invoice_mode.net_terms_days`; otherwise do not ask just to set net terms.
- If the customer has no email, ask for it and update the customer before previewing invoice or checkout flows.

### Enable plan immediately

- Top-level `enable_plan_immediately` grants access now whenever payment is deferred or pending (invoice unpaid, checkout incomplete, or future `starts_at`) — a superset of `invoice_mode.enable_plan_immediately`, which only covers the invoice-unpaid case.
- For `createSchedule` and `attach`, set top-level `enable_plan_immediately: true` instead of `invoice_mode.enable_plan_immediately`.
- `updateSubscription` has no top-level field; keep using `invoice_mode.enable_plan_immediately` there.

### Checkout flow

- Use checkout only when the user wants a payment link or checkout session to send to the customer.
- For checkout, omit `invoice_mode`, set `redirect_mode: "always"`, and set `enable_plan_immediately: true`.
- If the user might be asking for checkout but did not say so clearly, clarify before previewing.

### Direct charge flow

- If the user wants self-serve-style billing or immediate card charging, clarify before omitting `invoice_mode`.
- Without `invoice_mode`, eligible plan changes may charge the customer immediately.

### Proration

- Default proration to `none` so the preview starts with no immediate prorated charge or credit.
- If the customer has no existing subscriptions, do not pass `proration_behavior: "none"`; new subscriptions do not allow it.
- Use the endpoint's field name: `proration_behavior` for attach/updateSubscription, `billing_behavior` for createSchedule.
- Use `prorate_immediately` only when the user asks for prorations, immediate true-up, or immediate credits/charges.

## Preview and approval

- Preview only after action, target IDs, quantities, customization, timing, and billing behavior are known or intentionally defaulted.
- If missing information could change immediate charges, access timing, or scheduled state, ask before previewing.
- The main purpose of preview is to determine immediate billing impact: `total`, `currency`, and `line_items`.
- Summarize the preview's impact before the write.
- Lead with immediate impact: amount due now, no immediate charge, or credit.
- Include only preview facts that affect approval; avoid repeating context the user already resolved.
- If `next_cycle` exists, explain the next event: date, amount, and likely reason such as renewal, trial end, cancellation, downgrade, phase change, or nearest multi-interval event.
- Mention material state changes from `incoming` and `outgoing`, but treat them as supporting context if they look stale or incomplete.
- Convert preview timestamps before presenting dates.
- Apply only the exact previewed request. If params change, preview again.

## Completion response

- After the billing action succeeds, respond as concisely as possible: say the action completed successfully.
- Surface any returned customer-facing URL, especially `payment_url` or `invoice.hosted_invoice_url`.
- If an `invoice` is returned, mention its `status`, `stripe_id`, and hosted URL when present.
- If `invoice.hosted_invoice_url` is missing but `invoice.stripe_id` exists, surface the Stripe dashboard invoice URL: sandbox `https://dashboard.stripe.com/test/invoices/{stripe_id}`, live `https://dashboard.stripe.com/invoices/{stripe_id}`.
- If `required_action` is returned, explain the required payment action and include `payment_url` if present.
- If the action fails, state that it failed and quote the server error/status clearly.
- Do not re-summarize the full preview after completion unless the user asks.

---

Source: https://www.openparable.com/skill/apps-automation/autumn-billing (OpenParable). Cite the canonical URL above.
