livepeer / livepeer/clearinghouse

Support OpenMeter Grant Credits (real-money credit applied to settle invoices)

Open
#68 1 comment 0 reactions 0 assignees View on GitHub
billing feature
Dominant language
Go
Stars
1
Forks
3
Avg merge
1h 47m
Merged PRs (30d)
3

Description

## Summary

Track adding support for OpenMeter **Grant Credits** — real money applied to a customer account that can be used to settle an invoice. This is distinct from the free-trial mechanism currently in the bootstrap and from Entitlements.

## Background: the three OpenMeter "Credit" concepts

1. **Subscription Discounts** — a discount toward a plan, recurs monthly. Used today by the bootstrap (#25) for free trials.
2. **Grant Credits** — real money applied to an account that can be used to settle an invoice. **This issue.**
3. **Entitlements** — advanced Plans feature for dynamic pricing / rate limiting (tracked in #67).

Grant Credits differ from a trial discount: they represent actual monetary balance (e.g. promotional credit, refund/goodwill credit, or prepaid balance) that is drawn down against real invoices, rather than a recurring percentage/amount discount on a plan.

## Use cases

- Promotional or goodwill credit ("here's \$50 on us").
- Refunds issued as credit rather than a payout.
- Prepaid balance that offsets pay-per-use invoices.

## Tasks

- [ ] Confirm the OpenMeter/Konnect API surface for creating and querying account-level credit grants that settle invoices.
- [ ] Add a mechanism (admin API and/or bootstrap/provision path) to grant credits to a customer.
- [ ] Ensure grants are idempotent per customer/reason.
- [ ] Define how granted credit interacts with invoicing and with the identity-webhook balance gate (`483 insufficient_balance`).
- [ ] Document usage in the README / admin API wrapper (#10).

## Acceptance

- Credit can be granted to a customer account and is applied against that customer's invoice, with idempotent grants and documented behavior.

## References

- #67 — Evaluate Entitlements vs Subscription Discounts (related but distinct concept)
- #10 — Administrative API wrapper over KongHQ metering & billing
- #25 — OpenMeter/Konnect bootstrap scripts

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by confirming the OpenMeter/Konnect API surface for account-level credit grants and reviewing related issues #10, #25, and #67. Define the grant, idempotency, invoice interaction, and 483 insufficient_balance behavior before choosing an admin API or bootstrap path. Done means a customer can receive credit, have it applied to an invoice, and find the behavior documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
backend-api-design, payments
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.