autumn-add-payments

name	autumn-add-payments
description	Skill for adding Stripe checkout and payment flows using Autumn.

Autumn Payments

Always consult docs.useautumn.com for code examples and latest API.

Autumn handles Stripe checkout, upgrades, downgrades, and cancellations automatically.

---

Quick Reference

Payment Flow

1. checkout - Returns Stripe URL (new) or preview data (returning customer)
2. attach - Confirms purchase when card already on file

Checkout Result

Field	Description
url	Stripe checkout URL (null if card on file)
product	Target product with scenario
current_product	Customer's current product
lines	Invoice line items
total	Amount in major currency units
currency	Currency code

---

Product Scenarios

Scenario	Meaning	Action
new	Not subscribed	Subscribe
active	Current plan	Current Plan
scheduled	Scheduled	Already Scheduled
upgrade	Higher tier	Upgrade
downgrade	Lower tier	Downgrade
renew	Cancelled	Renew

---

React Implementation

import { useCustomer, usePricingTable } from "autumn-js/react";

const { checkout, attach } = useCustomer();
const { products } = usePricingTable();

// Checkout flow
const data = await checkout({ productId: "pro" });
if (data.url) {
  window.location.href = data.url;  // New customer
} else {
  // Show confirmation dialog, then:
  await attach({ productId: "pro" });
}

// Cancel
const { cancel } = useCustomer();
await cancel({ productId: "pro" });
// Or downgrade to free:
await attach({ productId: "free" });

---

Backend Implementation

import { Autumn } from "autumn-js";

const autumn = new Autumn({ secretKey: process.env.AUTUMN_SECRET_KEY });

// Checkout
const { data } = await autumn.checkout({ customer_id, product_id: "pro" });
if (data.url) return redirect(data.url);

// Attach (after user confirms)
await autumn.attach({ customer_id, product_id: "pro" });

// Get products with scenarios
const { data: productsData } = await autumn.products.list({ customer_id });

---

Prepaid Pricing

For seat-based or prepaid products, pass quantities:

await autumn.checkout({
  customer_id,
  product_id: "credits_pack",
  options: [{ feature_id: "credits", quantity: 500 }],
});

---

Button Text Pattern

function getButtonText(product: Product): string {
  const { scenario, properties } = product;
  if (properties?.has_trial) return "Start Trial";
  if (scenario === "active") return "Current Plan";
  
  const text = { upgrade: "Upgrade", downgrade: "Downgrade", new: "Subscribe" };
  return text[scenario] ?? "Enable";
}

---

Common Gotchas

1. URL field - It's data.url, not data.checkout_url
2. Don't build custom logic - Use products.list for scenarios
3. Proration automatic - Autumn handles upgrade/downgrade proration
4. Cancel via free - Prefer attaching free plan over hard cancel
5. Success URL - Pass success_url to redirect after Stripe checkout

---

Resources

• Checkout Docs
• Attach Docs
• LLMs.txt