Skip to content

docs: document subscription charge billing cycles#17

Merged
next-devin merged 5 commits into
mainfrom
docs-webhooks-fanout-and-correlation-guide
Jul 22, 2026
Merged

docs: document subscription charge billing cycles#17
next-devin merged 5 commits into
mainfrom
docs-webhooks-fanout-and-correlation-guide

Conversation

@next-devin

@next-devin next-devin commented Apr 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Adds concise subscription charge webhook guidance to the existing Subscription Management guide.

The update explains how to:

  • link a transaction to its subscription with data.subscription.id
  • distinguish the initial charge from renewals with data.subscription.billing_cycle

The webhook overview links directly to the new section. The standalone guide and external metadata guidance were removed following review.

Test plan

  • Run the full production documentation build (npm run build)
  • Verify the guide anchor and webhook overview link compile
  • Review the rendered section and webhook callout in the deploy preview

@next-devin @claude
docs: add webhook fan-out reference + metadata correlation guide
5f245b0 
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>
@kilo-code-bot

kilo-code-bot Bot commented Apr 27, 2026 •
edited
Loading

Copy link
Copy Markdown

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Incremental review against commit e082aa49 (incremental since 6ecbce23). PATCH 4/4 narrows the new Identifying Subscription Charges section by removing type: "debit" and status: "succeeded" from the example payload, and updates the webhooks index callout link to point at the in-page anchor. The remaining wording is consistent and accurate.

Files Reviewed (2 files)
  • content/docs/admin-api/guides/subscription-management.mdx - 23 lines added (new ### Identifying Subscription Charges section)
  • content/docs/webhooks/index.mdx - 4 lines added (new Callout linking to the section)
Previous Review Summaries (2 snapshots, latest commit 6ecbce2)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 6ecbce2)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (3 files)
  • content/docs/admin-api/guides/meta.json
  • content/docs/admin-api/guides/subscription-charge-webhooks.mdx
  • content/docs/webhooks/index.mdx

Previous review (commit 5f245b0)

Status: No Issues Found | Recommendation: Merge

Overview

Severity Count
CRITICAL 0
WARNING 0
SUGGESTION 0
Other Observations (not in diff)

One item noted for awareness:

File Line Issue
content/docs/webhooks/index.mdx 97 product.updated row uses "AttributeOption*" with an asterisk. This is an informal notation; verify it accurately represents the actual model naming used by the codebase.
Files Reviewed (3 files)
  • content/docs/admin-api/guides/meta.json - Addition of new page entry
  • content/docs/admin-api/guides/metadata-and-correlation.mdx - New guide (132 lines)
  • content/docs/webhooks/index.mdx - New sections: Event Trigger Sources table (lines 74-104), Identifying Rebill Orders (lines 106-125)

Reviewer Notes:

The PR adds two valuable documentation improvements: (1) an "Event Trigger Sources" table clarifying the fan-out behavior of *.updated events, which is currently institutional knowledge, and (2) a new Metadata & External Correlation guide covering the canonical pattern for cross-rebill correlation via attribution.metadata. Both additions address real support pain points identified in the PR description.

The changes are accurate, well-structured, and follow existing documentation patterns. The internal links (#cross-rebill-correlation-via-attribution, /docs/admin-api/reference/metadata/metadataCreate) and sidebar placement appear correct.

Reviewed by minimax-m3 · Input: 45.2K · Output: 3.3K · Cached: 415.2K

@next-devin

next-devin commented May 5, 2026

Copy link
Copy Markdown
Contributor Author

@alexphelps is this worth adding? Or just noise?

@next-devin @cursoragent
docs: focus subscription charge webhook guidance
6ecbce2 
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 next-devin changed the title docs: webhook fan-out reference + metadata correlation guide docs: add subscription charge webhook guide Jul 15, 2026
@alexphelps

alexphelps commented Jul 16, 2026

Copy link
Copy Markdown
Member

@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.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Jul 22, 2026 •
edited
Loading

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs		 developer-docs e082aa4 Commit Preview URL

Branch Preview URL		 Jul 22 2026, 02:27 AM

@next-devin next-devin changed the title docs: add subscription charge webhook guide docs: document subscription charge billing cycles Jul 22, 2026
@next-devin
next-devin merged commit 1447e22 into main Jul 22, 2026
2 checks passed
@next-devin
next-devin deleted the docs-webhooks-fanout-and-correlation-guide branch July 22, 2026 02:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@next-devin @alexphelps