使用方法
- 复制安装命令，在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物，并对照来源检查输出。
npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill stripe-refund-dispute-lifecycle开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况，不等于独立质量或安全测试。
按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。
Quick Reference
| Event | Action | Key rule | |--|--|--| | charge.refunded | Revoke credits proportional to refund delta | G2 — previous_attributes.amount_refunded | | charge.dispute.created | Set user past_due + store checkpoint | G1 + G9 | | charge.dispute.closed | won / warning_closed / prevented -> restore; lost -> no-op (charge.refunded handles); else -> no-op | G5 + G7 |
| Refund source priority | When to use | |--|--| | event.data.previous_attributes.amount_refunded (G2) | Primary — always prefer | | charge.refunds.data (sorted by created desc) | Fallback when previous_attributes absent | | stripe.refunds.list({charge, limit:1}) | Last resort when embedded missing | | charge.amount_refunded alone | NEVER (cumulative, not per-event) |
When to Use This Skill
Use when implementing any handler that revokes credits or mutates a paid-status column in response to Stripe refund or dispute events.
Related skills:
- For
getRefundDelta(the G2 delta helper):stripe-billing-master:stripe-list-pagination-previous-attributes - For the canonical refund helper and audit-row invariant:
stripe-billing-master:stripe-credit-audit-trail - For the G1 checkpoint pattern every dispute handler wraps:
stripe-billing-master:stripe-webhook-idempotency
Core Rules
G2: refund delta
Use getRefundDelta() from stripe-billing-master:stripe-list-pagination-previous-attributes — that skill owns the delta-computation helper. Key guarantee: the helper returns null when no source is available, and the handler MUST skip revocation rather than guess.
G7: exhaustive shouldRestoreStatus
const shouldRestoreMap = {
won: true,
warning_closed: true,
prevented: true,
lost: false,
needs_response: false,
under_review: false,
warning_needs_response: false,
warning_under_review: false,
charge_refunded: false,
} satisfies Record<Stripe.Dispute.Status, boolean>;
export const shouldRestoreStatus = (s: Stripe.Dispute.Status): boolean => shouldRestoreMap[s];When Stripe adds a new status in a future SDK version, this object is a compile error until you add the key — forcing a conscious G5 allowlist decision.
Credit-pack vs subscription refund
async function resolveCreditsToRevoke(charge: Stripe.Charge, refundAmount: number) {
const sessions = await stripe.checkout.sessions.list({
payment_intent: charge.payment_intent as string,
limit: 1,
expand: ["data.line_items"],
});
const session = sessions.data[0];
if (session?.mode !== "subscription") {
const pack = CREDIT_PACKS.find(p => session?.line_items?.data?.[0]?.price?.id === p.priceId);
if (pack && session.amount_total && session.amount_total > 0) {
// Proportional revocation: if they refunded 50% of the pack, revoke 50% of the credits
return Math.round(pack.credits * (refundAmount / session.amount_total));
}
}
// Subscription: 1 credit = 1 cent at cash-equivalent
return refundAmount;
}Notes on the credit-pack math: proportional revocation matters because packs are bulk-priced (e.g., 1000 credits for $9 instead of $10) — a flat refundAmount -> credits conversion over-revokes. Always look up the originating Checkout Session to distinguish mode: "subscription" (cash-equivalent) from mode: "payment" with a known pack price ID (proportional).
