docs(concepts): dynamic offerings + monthly commitment references

[kherembourg]

What

Adds public-knowledge reference docs so AI tools (and humans) can reason about dynamic offerings and the 12-month monthly-commitment billing feature when debugging paywalls.

New

• purchasely/references/concepts/dynamic-offerings.md
  • setDynamicOffering(reference, planVendorId, offerVendorId[, billingPlanType]) — cross-platform API (iOS/Android/RN/Flutter/Cordova; billingPlanType is iOS-only).
  • Applied server-side at placement fetch → must register before fetching/displaying; offerings persist until removed.
  • ⚠️ Pitfall: mapping the same plan to multiple offering references with different billing types in one presentation → the billing type becomes ambiguous and resolves to .unspecified. One plan → one billing type per presentation.
• purchasely/references/concepts/monthly-commitment.md
  • Apple advance commitment (12-month billed monthly), PLYBillingPlanType (.unspecified / .upFront / .monthly).
  • Eligibility: iOS 26.4+, SDK v6+, not US / Singapore (auto-fallback to up-front), App Store Connect + Console setup.

Updated

• concepts/README.md — index + "when to load" rows.
• troubleshooting/common-issues.md — symptom→cause row + §12 diagnostic (billingPlanType == .unspecified when .monthly expected).
• purchasely-sdk-expert/SKILL.md — reference list + routing section.

Notes

• Public integration knowledge only — no SDK internals, no tooling specifics.
• API signatures verified against the current SDK sources; billingPlanType confirmed iOS-only.

Verify

• node scripts/guard-known-bad-snippets.mjs → passes.
• New files lint clean; all reference/relative links resolve.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR adds two new public-knowledge reference documents — dynamic-offerings.md (the setDynamicOffering cross-platform API, its server-side-at-fetch behaviour, and the same-plan billing-type pitfall) and monthly-commitment.md (Apple advance-commitment / 12-month billed monthly, PLYBillingPlanType, iOS 26.4+ eligibility, US/SG auto-fallback) — and wires them into the concepts index, troubleshooting guide, and SDK-expert skill.

• New files: dynamic-offerings.md and monthly-commitment.md cover API signatures, platform scope, eligibility, and the key pitfall (one plan → one billing type per presentation).
• Index / troubleshooting updates: concepts/README.md adds routing rows; common-issues.md adds a quick-reference symptom row and a full §12 diagnostic.
• Skill update: purchasely-sdk-expert/SKILL.md adds a "Dynamic offerings & commitment billing" routing section with the correct relative paths.

Confidence Score: 4/5

Documentation-only change; no executable code is modified. Safe to merge after the CHANGELOG omission and the anchor link are addressed.

The content is accurate and well-structured. Two issues need attention: the [Unreleased] section in CHANGELOG.md was not updated despite the repository convention requiring it for every user-visible addition, and the cross-file anchor #️-pitfall-… in monthly-commitment.md is likely missing the ⚠ codepoint, which would cause it to silently land at the top of the page rather than the intended pitfall section.

CHANGELOG.md (not in the diff — missing entries for the new concept files and updated references); purchasely/references/concepts/monthly-commitment.md (anchor link to the pitfall section in dynamic-offerings.md may be malformed).

Important Files Changed

Filename	Overview
purchasely/references/concepts/dynamic-offerings.md	New reference doc for setDynamicOffering API — covers all platforms, server-side-at-fetch rule, and the same-plan billing-type pitfall; CHANGELOG entry is missing.
purchasely/references/concepts/monthly-commitment.md	New reference doc for Apple advance-commitment billing (PLYBillingPlanType); cross-file anchor to the pitfall section in dynamic-offerings.md may be broken due to emoji stripping.
purchasely/references/concepts/README.md	Index and 'when to load' table updated with two new entries pointing to the new concept files; links look correct.
purchasely/references/troubleshooting/common-issues.md	Added symptom row to the quick-reference table and a new §12 diagnostic section for billingPlanType resolving to .unspecified; content is consistent with the new concept docs.
purchasely/skills/purchasely-sdk-expert/SKILL.md	Reference list and routing section extended for dynamic offerings and monthly commitment; paths and summaries are accurate.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant App
    participant SDK as Purchasely SDK
    participant Backend as Purchasely Backend

    App->>SDK: setDynamicOffering(reference, planVendorId, billingPlanType?)
    SDK-->>App: success callback
    Note over SDK: Offering persisted locally

    App->>SDK: fetchPresentation / display placement
    SDK->>Backend: Fetch paywall JSON (with registered offerings)
    Backend-->>SDK: Paywall JSON (plan/offer substituted server-side)
    SDK-->>App: Paywall rendered with overridden plan

    Note over App,SDK: If offering registered AFTER fetch → no effect until next fetch
    Note over App,SDK: Same plan + conflicting billing types → .unspecified

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant App
    participant SDK as Purchasely SDK
    participant Backend as Purchasely Backend

    App->>SDK: setDynamicOffering(reference, planVendorId, billingPlanType?)
    SDK-->>App: success callback
    Note over SDK: Offering persisted locally

    App->>SDK: fetchPresentation / display placement
    SDK->>Backend: Fetch paywall JSON (with registered offerings)
    Backend-->>SDK: Paywall JSON (plan/offer substituted server-side)
    SDK-->>App: Paywall rendered with overridden plan

    Note over App,SDK: If offering registered AFTER fetch → no effect until next fetch
    Note over App,SDK: Same plan + conflicting billing types → .unspecified

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
purchasely/references/concepts/monthly-commitment.md:43
**Possibly broken cross-file anchor**

The anchor `#️-pitfall-one-plan--one-billing-type-per-presentation` is missing the `⚠` character (U+26A0) — only the variation-selector-16 codepoint (`️`, U+FE0F) is present. GitHub's slug generator (`github-slugger`) keeps the full emoji glyph in the anchor, so the resolved anchor for the heading `## ⚠️ Pitfall: one plan → one billing type per presentation` would include `⚠`. The missing `⚠` means this link may silently land at the top of the page instead of the pitfall section.

### Issue 2 of 2
purchasely/references/concepts/dynamic-offerings.md:1-5
**CHANGELOG.md not updated**

`CLAUDE.md` requires that every PR adding, changing, removing, or deprecating anything user-visible updates `CHANGELOG.md` under `[Unreleased]`. This PR adds two new reference files (`dynamic-offerings.md`, `monthly-commitment.md`) and updates `common-issues.md`, `README.md`, and `SKILL.md` — all user-visible — but the `[Unreleased]` section in `CHANGELOG.md` is still empty. Entries under `Added` (two new concept files) and `Changed` (updated index, troubleshooting, skill) are needed.

_{Reviews (1): Last reviewed commit: "docs(concepts): add dynamic offerings + ..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Adds new public reference documentation covering dynamic offerings (runtime plan/offer overrides) and iOS monthly commitment billing (Apple advance commitment), and updates existing indexes/troubleshooting/skill routing so tools and humans can load the right docs when debugging paywalls.

Changes:

• Added two new concept references: dynamic-offerings.md and monthly-commitment.md.
• Expanded troubleshooting guidance with a new diagnostic section for billingPlanType resolving to .unspecified.
• Updated concept index and purchasely-sdk-expert skill routing to include the new references.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
purchasely/skills/purchasely-sdk-expert/SKILL.md	Adds routing/notes so the skill loads the new dynamic offerings + commitment billing references.
purchasely/references/troubleshooting/common-issues.md	Adds a new symptom row and a dedicated diagnostic section for .unspecified billing plan type.
purchasely/references/concepts/README.md	Updates the concepts index and “when to load” table to include the new docs.
purchasely/references/concepts/monthly-commitment.md	New reference explaining iOS monthly commitment billing and runtime behavior/diagnostics.
purchasely/references/concepts/dynamic-offerings.md	New cross-platform reference describing dynamic offerings, timing, APIs, and the billing-type pitfall.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.