fix: settle promotional credits

[turip]

Overview

Fix promotional credit grants so they settle immediately through wash instead of leaving open customer receivable.

Previously promotional credit purchases reused the shared issuance flow and stopped after issuing +FBO / -open receivable. Because promotional grants do not have later payment lifecycle events, that left an unsettled balance on the promotional receivable route. This change keeps the shared issuance logic but, for promotional
settlement types, appends the existing receivable funding and settlement templates so the receivable is cleared immediately.

What Changed

• Updated issueCreditPurchase in openmeter/ledger/chargeadapter/creditpurchase.go
• Kept the shared issuance path for:
  • advance receivable attribution
  • accrued cost-basis translation
  • new credit issuance
• Added settlement-type-specific behavior inside that shared function:
  • promotional: append FundCustomerReceivableTemplate and SettleCustomerReceivablePaymentTemplate
  • external/invoice: unchanged deferred behavior
• Added an inline comment documenting why promotional grants must settle through wash
• Updated ledger chargeadapter tests to assert:
  • promotional grants no longer leave open receivable
  • wash carries the offset
  • advance-exposure handling still works
• Updated test/credits/sanity_test.go to reflect the new promotional accounting model

Behavioral Impact

For promotional credit grants:

• before: FBO +X, open receivable -X, wash unchanged
• after: FBO +X, open receivable 0, wash -X

External and invoice-backed credit purchase flows are unchanged.

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Fixed promotional credit purchase settlement to properly distribute amounts across receivable and settlement accounts based on settlement type.
  • Added validation to detect and reject unsupported settlement types with descriptive error messaging.

• Tests

  • Updated test coverage for promotional credit purchase settlement scenarios.
  • Added new test case validating promotional credits with prior advance exposure.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e2053eba-9c57-4d09-83df-656bc8f13e45

📥 Commits

Reviewing files that changed from the base of the PR and between 532db5c and ae94220.

📒 Files selected for processing (3)

• openmeter/ledger/chargeadapter/creditpurchase.go
• openmeter/ledger/chargeadapter/creditpurchase_test.go
• test/credits/sanity_test.go

---

📝 Walkthrough

Walkthrough

This PR refactors promotional credit purchase settlement handling by adding settlement-type-aware branching to the ledger transaction template assembly. For promotional settlements, it now appends receivable funding and wash settlement templates; other settlement types receive error handling or deferred processing. Tests are updated to verify the new wash-based accounting behavior.

Changes

Cohort / File(s)	Summary
Settlement Type Branching Logic openmeter/ledger/chargeadapter/creditpurchase.go	Adds conditional template assembly based on charge.Intent.Settlement.Type(). Promotional settlements now include receivable funding and wash templates using computed costBasis; other types return errors or remain unmodified.
Promotional Credit Purchase Tests openmeter/ledger/chargeadapter/creditpurchase_test.go	Updated TestOnPromotionalCreditPurchase expectations: receivable balance now 0 instead of -100, wash sub-account now -100. Added new test TestOnPromotionalCreditPurchase_BacksAdvanceBeforeTopUp validating behavior when promotional credits back existing advances.
Integration Tests test/credits/sanity_test.go	Adjusted lifecycle assertions in TestUsageBasedCreditThenInvoicePaymentLifecycle: promotional receivables now zero throughout, wash balances shifted to reflect new accounting, open receivable totals reduced accordingly.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix: credit purchase adapter issues #4068: Modifies credit-purchase adapter's settlement type branching and cost-basis computation for ledger templates.
• fix: grants service should not bypass charges service for now #4166: Updates API/service conversion to handle promotional credit purchases specially, complementing settlement type handling changes.

Suggested labels

release-note/bug-fix, area/billing

Suggested reviewers

• GAlexIHU
• tothandras

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: settle promotional credits' directly and clearly summarizes the main change: fixing promotional credit settlement by transitioning from open receivables to immediate wash settlement.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/settle-promotional-credits

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}