docs: add subscription charge webhook guide#17
Conversation
Two improvements to help external developers self-serve on common integration questions: 1. webhooks/index.mdx — new "Event Trigger Sources" section listing the models whose post_save fires each *.updated event (so subscribers can pick the leanest event for their use case), plus an "Identifying Rebill Orders" section covering the order subscriptions block and the transaction.subscription.billing_cycle counter. 2. admin-api/guides/metadata-and-correlation.mdx — new guide enumerating the 9 metadata-supported object types, with a callout that subscriptions/carts aren't directly metadata-managed. Walks through the canonical attribution.metadata pattern for cross-rebill external ID correlation (set once on subscription attribution, flows through subscription/order/transaction webhooks via FK inheritance with no follow-up API call). Includes a worked plan_id example and a "When to Use Which Surface" decision table. Surfaced via support inquiry from a merchant building integration to an external plan-management service. The fan-out + correlation patterns were institutional knowledge that took multiple rounds to produce authoritatively; this PR puts both into the public docs so future developers get the answer on first read. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Code Review SummaryStatus: No Issues Found | Recommendation: Merge Files Reviewed (3 files)
Previous Review Summary (commit 5f245b0)Current summary above is authoritative. Previous snapshots are kept for context only. Previous review (commit 5f245b0)Status: No Issues Found | Recommendation: Merge Overview
Other Observations (not in diff)One item noted for awareness:
Files Reviewed (3 files)
Reviewer Notes: The PR adds two valuable documentation improvements: (1) an "Event Trigger Sources" table clarifying the fan-out behavior of The changes are accurate, well-structured, and follow existing documentation patterns. The internal links ( Reviewed by minimax-m3 · Input: 37K · Output: 1.7K · Cached: 133.1K |
|
@alexphelps is this worth adding? Or just noise? |
Replace brittle implementation details with a task-oriented, retry-safe flow for detecting and correlating successful subscription charges. Co-authored-by: Cursor <cursoragent@cursor.com>
next-devin
changed the title
|
@next-devin The section that highlights the "subscription" object on transactions to link the related subscription and the biling cycle is good but the rest that discusses metadata, external plans, etc I think is noise. Also don't believe this should have it's own dedicated page, should be additional sections on the existing Subscription Management guide here. |
2 participants
Summary
Adds a task-oriented guide for integrations that need to react to subscription charges and correlate them with external systems.
The guide explains how to:
transaction.created,type: "debit", andstatus: "succeeded"subscription.billing_cycleattribution.metadataevent_idor transaction IDThe webhook overview now links to the focused guide instead of exposing an exhaustive internal model-to-event fan-out table that would be difficult to keep accurate.
Why
This flow surfaced through a merchant integration inquiry and previously required several rounds of support to explain. The public docs did not connect successful-payment filtering, renewal detection, external-ID correlation, and retry safety in one place.
Test plan
npm run build)