Documentation
¶
Index ¶
- func AddAccountMember(c *zip.Ctx) error
- func AddInvoiceLineItem(c *zip.Ctx) error
- func AdjustCustomerBalance(c *zip.Ctx) error
- func ApplyInvoiceDiscount(c *zip.Ctx) error
- func AuthorizeSpendCap(c *zip.Ctx) error
- func BurnCredits(db *datastore.Datastore, userId string, amount int64, meterId string) (int64, error)
- func BurnCreditsPreview(db *datastore.Datastore, userId string, amount int64) (int64, error)
- func CalculateInvoiceTax(c *zip.Ctx) error
- func CancelBillingSubscription(c *zip.Ctx) error
- func CancelPaymentIntent(c *zip.Ctx) error
- func CancelPayout(c *zip.Ctx) error
- func CancelSetupIntent(c *zip.Ctx) error
- func CancelSubscriptionSchedule(c *zip.Ctx) error
- func CapturePaymentIntent(c *zip.Ctx) error
- func ChargeGPU(c *zip.Ctx) error
- func CloseDispute(c *zip.Ctx) error
- func ConfirmPaymentIntent(c *zip.Ctx) error
- func ConfirmSetupIntent(c *zip.Ctx) error
- func CreateBankTransferInstruction(c *zip.Ctx) error
- func CreateBillingAccount(c *zip.Ctx) error
- func CreateBillingSubscription(c *zip.Ctx) error
- func CreateCreditGrant(c *zip.Ctx) error
- func CreateCreditNote(c *zip.Ctx) error
- func CreateInvoice(c *zip.Ctx) error
- func CreateMeter(c *zip.Ctx) error
- func CreatePaymentIntent(c *zip.Ctx) error
- func CreatePaymentMethod(c *zip.Ctx) error
- func CreatePayout(c *zip.Ctx) error
- func CreatePricingRule(c *zip.Ctx) error
- func CreateRefund(c *zip.Ctx) error
- func CreateSetupIntent(c *zip.Ctx) error
- func CreateSpendAlert(c *zip.Ctx) error
- func CreateSubscriptionItem(c *zip.Ctx) error
- func CreateSubscriptionSchedule(c *zip.Ctx) error
- func CreateWebhookEndpoint(c *zip.Ctx) error
- func Credit(c *zip.Ctx) error
- func DeletePricingRule(c *zip.Ctx) error
- func DeleteSpendAlert(c *zip.Ctx) error
- func DeleteSubscriptionItem(c *zip.Ctx) error
- func DeleteWebhookEndpoint(c *zip.Ctx) error
- func Deposit(c *zip.Ctx) error
- func DetachPaymentMethod(c *zip.Ctx) error
- func DownloadInvoicePDF(c *zip.Ctx) error
- func FinalizeInvoice(c *zip.Ctx) error
- func GPUChargeEligibility(c *zip.Ctx) error
- func GetAutoRecharge(c *zip.Ctx) error
- func GetBalance(c *zip.Ctx) error
- func GetBalanceAll(c *zip.Ctx) error
- func GetBankTransferInstruction(c *zip.Ctx) error
- func GetBillingEvent(c *zip.Ctx) error
- func GetBillingStatus(c *zip.Ctx) error
- func GetBillingSubscription(c *zip.Ctx) error
- func GetCapabilities(c *zip.Ctx) error
- func GetCreditBalance(c *zip.Ctx) error
- func GetCreditBalanceBreakdown(c *zip.Ctx) error
- func GetCreditNote(c *zip.Ctx) error
- func GetCustomerBalance(c *zip.Ctx) error
- func GetDNSUsageSummary(c *zip.Ctx) error
- func GetDispute(c *zip.Ctx) error
- func GetInvoice(c *zip.Ctx) error
- func GetMeter(c *zip.Ctx) error
- func GetMeterEventsSummary(c *zip.Ctx) error
- func GetMyBalance(c *zip.Ctx) error
- func GetOSSPayoutSummary(c *zip.Ctx) error
- func GetPaymentConfig(c *zip.Ctx) error
- func GetPaymentIntent(c *zip.Ctx) error
- func GetPaymentMethod(c *zip.Ctx) error
- func GetPayout(c *zip.Ctx) error
- func GetPlan(c *zip.Ctx) error
- func GetRefund(c *zip.Ctx) error
- func GetSetupIntent(c *zip.Ctx) error
- func GetSubscriptionItem(c *zip.Ctx) error
- func GetSubscriptionSchedule(c *zip.Ctx) error
- func GetTier(c *zip.Ctx) error
- func GetUsage(c *zip.Ctx) error
- func GetUsageRollup(c *zip.Ctx) error
- func GetWebhookEndpoint(c *zip.Ctx) error
- func GrantAllotment(c *zip.Ctx) error
- func HandleProviderWebhook(c *zip.Ctx) error
- func IncludedMonthlyCents(slug string) int64
- func IngestSBOM(c *zip.Ctx) error
- func InvoicePreview(c *zip.Ctx) error
- func ListAccountMembers(c *zip.Ctx) error
- func ListBalanceTransactions(c *zip.Ctx) error
- func ListBankTransferInstructions(c *zip.Ctx) error
- func ListBillingAccounts(c *zip.Ctx) error
- func ListBillingEvents(c *zip.Ctx) error
- func ListBillingSubscriptions(c *zip.Ctx) error
- func ListCreditGrants(c *zip.Ctx) error
- func ListCreditNotes(c *zip.Ctx) error
- func ListDNSPlans(c *zip.Ctx) error
- func ListDisputes(c *zip.Ctx) error
- func ListInvoices(c *zip.Ctx) error
- func ListMeters(c *zip.Ctx) error
- func ListOSSAccruals(c *zip.Ctx) error
- func ListPaymentIntents(c *zip.Ctx) error
- func ListPaymentMethods(c *zip.Ctx) error
- func ListPayouts(c *zip.Ctx) error
- func ListPlans(c *zip.Ctx) error
- func ListPricingRules(c *zip.Ctx) error
- func ListRefunds(c *zip.Ctx) error
- func ListSBOMs(c *zip.Ctx) error
- func ListSpendAlerts(c *zip.Ctx) error
- func ListSubscriptionItems(c *zip.Ctx) error
- func ListSubscriptionSchedules(c *zip.Ctx) error
- func ListTransactions(c *zip.Ctx) error
- func ListWebhookEndpoints(c *zip.Ctx) error
- func MigrateHUSD(c *zip.Ctx) error
- func PayInvoice(c *zip.Ctx) error
- func PortalInvoices(c *zip.Ctx) error
- func PortalOverview(c *zip.Ctx) error
- func PortalPaymentMethods(c *zip.Ctx) error
- func PortalSubscriptions(c *zip.Ctx) error
- func ReactivateBillingSubscription(c *zip.Ctx) error
- func ReconcileInboundTransfer(c *zip.Ctx) error
- func RecordDNSUsage(c *zip.Ctx) error
- func RecordMeterEvents(c *zip.Ctx) error
- func RecordUsage(c *zip.Ctx) error
- func Refund(c *zip.Ctx) error
- func ReleaseSubscriptionSchedule(c *zip.Ctx) error
- func RemoveAccountMember(c *zip.Ctx) error
- func RemoveInvoiceLineItem(c *zip.Ctx) error
- func RenewBillingSubscription(c *zip.Ctx) error
- func Route(r zip.Router, args ...zip.Handler)
- func RunAllotments(c *zip.Ctx) error
- func RunAutoRechargeAllOrgs(c *zip.Ctx) error
- func RunBillingCycle(c *zip.Ctx) error
- func RunBillingCycleAllOrgs(c *zip.Ctx) error
- func RunBillingCycleUser(c *zip.Ctx) error
- func SetAutoRecharge(c *zip.Ctx) error
- func SetDefaultPaymentMethod(c *zip.Ctx) error
- func SetOrgTestMode(c *zip.Ctx) error
- func SettleHUSD(c *zip.Ctx) error
- func StatusHUSD(c *zip.Ctx) error
- func SubmitDisputeEvidence(c *zip.Ctx) error
- func SyncHUSD(c *zip.Ctx) error
- func TierCheck(c *zip.Ctx) error
- func TokenizeCard(c *zip.Ctx) error
- func Topup(c *zip.Ctx) error
- func TopupWithToken(c *zip.Ctx) error
- func UpcomingInvoice(c *zip.Ctx) error
- func UpdateBillingSubscription(c *zip.Ctx) error
- func UpdateMemberRole(c *zip.Ctx) error
- func UpdatePaymentMethod(c *zip.Ctx) error
- func UpdateSpendAlert(c *zip.Ctx) error
- func UpdateSubscriptionItem(c *zip.Ctx) error
- func UpdateSubscriptionSchedule(c *zip.Ctx) error
- func UpdateWebhookEndpoint(c *zip.Ctx) error
- func VoidCreditGrant(c *zip.Ctx) error
- func VoidCreditNote(c *zip.Ctx) error
- func VoidInvoice(c *zip.Ctx) error
- func Withdraw(c *zip.Ctx) error
- func ZapDispatch(c *zip.Ctx) error
- type Plan
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddAccountMember ¶ added in v1.36.3
AddAccountMember is a stub. Member management is done via IAM.
POST /v1/billing/accounts/:id/members
func AddInvoiceLineItem ¶ added in v1.34.0
AddInvoiceLineItem appends a line item to a draft invoice and recalculates the subtotal.
POST /v1/billing/invoices/:id/line-items
func AdjustCustomerBalance ¶ added in v1.34.0
AdjustCustomerBalance manually adjusts a customer's balance.
POST /v1/billing/customer-balance/adjustments
func ApplyInvoiceDiscount ¶ added in v1.34.0
ApplyInvoiceDiscount applies a discount to a draft invoice and recalculates the amount due.
POST /v1/billing/invoices/:id/apply-discount
func AuthorizeSpendCap ¶ added in v1.46.38
AuthorizeSpendCap is the per-request cap verdict for a (project,service) scope and a proposed amount, over the org's spend-alert rows. It evaluates EVERY covering row (most-restrictive-wins) and DENIES when any HARD-enforceable ENFORCE=true row is exceeded, reporting the tightest one. Soft rows — and a project-scoped enforce row whose project axis is NOT validated (pv=0) — never block; they only raise the warn utilization.
FAIL CLOSED, not open: if a HARD-enforceable enforce row's spend sum cannot be computed, the verdict DENIES (spend_cap) — an attacker must not disable a cap by inducing a compute error. Per-scope sums are memoized so covering rows sharing a scope cost one query. The row scan is bounded (loadOrgScopes).
GET /v1/billing/spend-alerts/authorize?user=&project=&service=&amount=&pv=
func BurnCredits ¶
func BurnCredits(db *datastore.Datastore, userId string, amount int64, meterId string) (int64, error)
BurnCredits applies the credit burn-down algorithm: deducts amount from active grants in priority order. Returns the remaining amount (overage) and the grants that were modified.
func BurnCreditsPreview ¶ added in v1.34.0
BurnCreditsPreview calculates credit burn without actually deducting. Returns the remaining amount after credits would be applied.
func CalculateInvoiceTax ¶ added in v1.34.0
CalculateInvoiceTax computes tax for an invoice based on a customer address and updates the invoice with the resulting tax lines.
POST /v1/billing/invoices/:id/calculate-tax?country=...&state=...
func CancelBillingSubscription ¶ added in v1.34.0
CancelBillingSubscription cancels a subscription.
POST /v1/billing/subscriptions/:id/cancel
func CancelPaymentIntent ¶ added in v1.34.0
CancelPaymentIntent cancels a payment intent.
POST /v1/billing/payment-intents/:id/cancel
func CancelPayout ¶ added in v1.34.0
CancelPayout cancels a pending payout.
POST /v1/billing/payouts/:id/cancel
func CancelSetupIntent ¶ added in v1.34.0
CancelSetupIntent cancels a setup intent.
POST /v1/billing/setup-intents/:id/cancel
func CancelSubscriptionSchedule ¶ added in v1.34.0
CancelSubscriptionSchedule cancels a subscription schedule.
POST /v1/billing/subscription-schedules/:id/cancel
func CapturePaymentIntent ¶ added in v1.34.0
CapturePaymentIntent captures a previously authorized payment intent.
POST /v1/billing/payment-intents/:id/capture
func ChargeGPU ¶ added in v1.46.25
ChargeGPU debits a GPU charge from PREPAID real money only. It is the ONLY commerce write that records a "gpu"-tagged withdrawal, and it is fail-closed:
POST /v1/billing/gpu-charge { user, amountCents, currency?, requestId?, tag? }
- 402 {code: card_required} — no chargeable card on file.
- 402 {code: insufficient_prepaid} — prepaid real money can't cover it
(credits are NEVER consulted or consumed).
- 201 {transactionId, prepaidBalance, ...} on success.
Admin/service token (mounted on the admin group) — called by the cloud GPU launch/meter path, never the browser.
func CloseDispute ¶ added in v1.34.0
CloseDispute closes a dispute.
POST /v1/billing/disputes/:id/close
func ConfirmPaymentIntent ¶ added in v1.34.0
ConfirmPaymentIntent confirms a payment intent.
POST /v1/billing/payment-intents/:id/confirm
func ConfirmSetupIntent ¶ added in v1.34.0
ConfirmSetupIntent confirms a setup intent, saving the payment method.
POST /v1/billing/setup-intents/:id/confirm
func CreateBankTransferInstruction ¶ added in v1.34.0
CreateBankTransferInstruction creates bank transfer details for a customer.
POST /v1/billing/bank-transfer-instructions
func CreateBillingAccount ¶ added in v1.36.3
CreateBillingAccount is a no-op stub. Billing accounts are provisioned via IAM/console org creation; Commerce does not manage org lifecycle. Returns 501 to signal the caller to redirect to the org provisioning flow.
POST /v1/billing/accounts
func CreateBillingSubscription ¶ added in v1.34.0
CreateBillingSubscription creates a new subscription and starts the billing lifecycle.
POST /v1/billing/subscriptions
func CreateCreditGrant ¶
CreateCreditGrant creates a new credit grant for a user.
POST /v1/billing/credit-grants
func CreateCreditNote ¶ added in v1.34.0
CreateCreditNote creates a credit note against an invoice.
POST /v1/billing/credit-notes
func CreateInvoice ¶ added in v1.34.0
CreateInvoice creates a new draft billing invoice.
POST /v1/billing/invoices
func CreatePaymentIntent ¶ added in v1.34.0
CreatePaymentIntent creates a new payment intent.
POST /v1/billing/payment-intents
func CreatePaymentMethod ¶ added in v1.34.0
CreatePaymentMethod creates and attaches a payment method to a customer.
POST /v1/billing/payment-methods
func CreatePayout ¶ added in v1.34.0
CreatePayout creates a new outbound payout.
POST /v1/billing/payouts
func CreatePricingRule ¶
CreatePricingRule creates a new pricing rule for a meter.
POST /v1/billing/pricing-rules
func CreateRefund ¶ added in v1.34.0
CreateRefund creates a full or partial refund.
POST /v1/billing/refunds
func CreateSetupIntent ¶ added in v1.34.0
CreateSetupIntent creates a new setup intent for saving a payment method.
POST /v1/billing/setup-intents
func CreateSpendAlert ¶ added in v1.36.3
CreateSpendAlert creates a spend alert / cap. UserId is optional (an org-wide or project/service scope cap has none). At least one limit must be meaningful: a Threshold>0 (spend cap) or a RateLimitRpm>0 (rate limit).
POST /v1/billing/spend-alerts
func CreateSubscriptionItem ¶ added in v1.34.0
CreateSubscriptionItem adds an item to a subscription.
POST /v1/billing/subscription-items
func CreateSubscriptionSchedule ¶ added in v1.34.0
CreateSubscriptionSchedule creates a new subscription schedule.
POST /v1/billing/subscription-schedules
func CreateWebhookEndpoint ¶ added in v1.34.0
CreateWebhookEndpoint registers a new webhook endpoint.
POST /v1/billing/webhook-endpoints
func Credit ¶ added in v1.48.3
Credit is THE ONE way credit enters an org ledger. It appends a single org-keyed, non-cash credit grant to the org's balance — the same ledger GET /v1/billing/balance and the cloud AI spend-gate read, so a granted credit is immediately spendable.
POST /v1/billing/credit
{"org":"acme","amountCents":500,"reason":"welcome","tag":"starter-credit",
"currency":"usd","expiresAt":"2027-01-01T00:00:00Z","idempotencyKey":"signup:acme"}
MINT-GATED. The route is registered through middleware.Mint, which puts it behind middleware.PlatformOnly and records it in middleware.MintRoutes(), so ONLY the internal service token (cloud-api → commerce, COMMERCE_SERVICE_TOKEN) or a platform global admin (auth.IAMClaims.IsSuperAdmin, owner=="admin") reaches it; every self-service / org-owner / no-auth caller is refused (403/401) BEFORE the handler. A client-supplied mint amount is exactly what must never be self-service — that is why this is mint-gated and a user cannot credit itself.
Backing: when the host injects a double-entry ledger (creditledger, set by commerce.EmbedConfig.Ledger — the cloud-embedded path), the credit is a balanced posting to the org account the AI gate reads (one ledger, no split). Standalone (no ledger injected), it appends a tagged Deposit to commerce's own datastore.
"Starter credit" is not a special case — it is a parameterized call with tag=credit.StarterCreditTag, amountCents=credit.StarterCreditCents, and expiresAt=now+credit.StarterCreditDays; the billing/credit constants are the data a caller passes, not a second code path.
Idempotent on idempotencyKey: the same key credits AT MOST ONCE.
func DeletePricingRule ¶
DeletePricingRule removes a pricing rule by ID.
DELETE /v1/billing/pricing-rules/:id
func DeleteSpendAlert ¶ added in v1.36.3
DeleteSpendAlert deletes a spend alert by ID.
DELETE /v1/billing/spend-alerts/:id
func DeleteSubscriptionItem ¶ added in v1.34.0
DeleteSubscriptionItem removes an item from a subscription.
DELETE /v1/billing/subscription-items/:id
func DeleteWebhookEndpoint ¶ added in v1.34.0
DeleteWebhookEndpoint removes a webhook endpoint.
DELETE /v1/billing/webhook-endpoints/:id
func Deposit ¶
Deposit creates a deposit (credit) transaction for an IAM user.
POST /v1/billing/deposit
Used by internal services to add funds to a user's account (payment processor settlement, manual credit, promotional grants, etc.).
func DetachPaymentMethod ¶ added in v1.34.0
DetachPaymentMethod detaches (soft-deletes) a payment method.
DELETE /v1/billing/payment-methods/:id
func DownloadInvoicePDF ¶ added in v1.46.33
DownloadInvoicePDF renders and serves an invoice as a PDF.
GET /v1/billing/invoices/:id/pdf
Tenant isolation: the invoice is loaded from the caller's OWN org namespace (datastore.New(org.Namespaced(c.Context()))). GetById scopes the lookup to that namespace at the storage layer, so an org can only ever fetch its own invoice — a foreign id resolves to nothing and returns 404. It is mounted on the user group so a normal authenticated org member can download their own invoice.
func FinalizeInvoice ¶ added in v1.34.0
FinalizeInvoice transitions an invoice from draft to open.
POST /v1/billing/invoices/:id/finalize
func GPUChargeEligibility ¶ added in v1.46.25
GPUChargeEligibility is the read-only launch gate: may a GPU of this size be launched/charged from prepaid right now?
GET /v1/billing/gpu-eligibility?user=<subj>&amountCents=<n>&minPrepaidCents=<m>
Returns 200 with {eligible,reason,...} in ALL cases (the caller decides how to render) — it never 402s, so the launch UI can show the exact remedy (add a card / add prepaid). amountCents is the immediate charge; minPrepaidCents is the 24h-minimum prepaid the GPU policy requires before launch (the gate needs prepaidAvailable >= max(amountCents, minPrepaidCents)).
func GetAutoRecharge ¶ added in v1.42.38
GetAutoRecharge returns the org's auto-recharge config (or disabled defaults).
GET /v1/billing/auto-recharge
func GetBalance ¶
GetBalance returns the current balance for an IAM user.
GET /v1/billing/balance?user=hanzo/alice¤cy=usd
All amounts in cents. available = balance - holds.
func GetBalanceAll ¶
GetBalanceAll returns balances across all currencies for an IAM user.
GET /v1/billing/balance/all?user=hanzo/alice
func GetBankTransferInstruction ¶ added in v1.34.0
GetBankTransferInstruction returns a single bank transfer instruction by ID.
GET /v1/billing/bank-transfer-instructions/:id
func GetBillingEvent ¶ added in v1.34.0
GetBillingEvent retrieves a single billing event.
GET /v1/billing/events/:id
func GetBillingStatus ¶ added in v1.37.0
GetBillingStatus returns a unified billing status for a user. Used by the bot gateway billing-gate to decide whether to allow LLM requests.
GET /v1/billing/status?user=<userId>
Response:
{
"user": "alice",
"hasPaymentMethod": true,
"creditBalance": 500, // cents
"tier": "developer"
}
func GetBillingSubscription ¶ added in v1.34.0
GetBillingSubscription returns a single subscription.
GET /v1/billing/subscriptions/:id
func GetCapabilities ¶ added in v1.34.0
GetCapabilities returns the billing platform's supported features, payment methods, and currencies.
GET /v1/billing/capabilities
func GetCreditBalance ¶
GetCreditBalance returns the total available credit balance for a user.
GET /v1/billing/credit-balance?userId=...
func GetCreditBalanceBreakdown ¶ added in v1.36.4
GetCreditBalanceBreakdown returns the credit balance grouped by tag. Used by Chat to distinguish trial vs paid credits.
GET /v1/billing/credit-balance/breakdown?userId=...
func GetCreditNote ¶ added in v1.34.0
GetCreditNote retrieves a credit note by ID.
GET /v1/billing/credit-notes/:id
func GetCustomerBalance ¶ added in v1.34.0
GetCustomerBalance retrieves the customer balance for a customer+currency.
GET /v1/billing/customer-balance?customerId=...¤cy=...
func GetDNSUsageSummary ¶ added in v1.36.4
GetDNSUsageSummary returns a usage summary for DNS queries, zones, and records.
GET /v1/dns/usage/summary?user={owner/name}&period=day|month
func GetDispute ¶ added in v1.34.0
GetDispute retrieves a dispute by ID.
GET /v1/billing/disputes/:id
func GetInvoice ¶ added in v1.34.0
GetInvoice returns a single billing invoice by ID.
GET /v1/billing/invoices/:id
func GetMeterEventsSummary ¶
GetMeterEventsSummary returns aggregated usage for a meter+user+period.
GET /v1/billing/meter-events/summary?meterId=...&userId=...&periodStart=...&periodEnd=...
func GetMyBalance ¶ added in v1.42.0
GetMyBalance returns the calling user's balance for a given currency. Identity comes from the gateway-injected X-Org-Id / X-User-Id headers; no admin token required.
GET /v1/billing/me/balance?currency=usd
func GetOSSPayoutSummary ¶ added in v1.42.45
GetOSSPayoutSummary rolls up accruals per package: the running total Hanzo owes each OSS package and where it would be paid. This is the payout-ready view — the disbursement job consumes it.
GET /v1/billing/oss-payout/summary?org=
func GetPaymentConfig ¶ added in v1.42.38
GetPaymentConfig returns the PUBLIC Square config (application id, location id, environment) the browser's Web Payments SDK must use to tokenize a card for THIS org. It resolves sandbox-vs-production through the SAME single authority as the charge path (org.TestMode / SQUARE_ENVIRONMENT) and the same KMS-then-env fallback, so the app id the browser tokenizes with always matches the env + access token commerce will vault/charge with. All values are public (safe to expose to the client).
GET /v1/billing/payment-config
func GetPaymentIntent ¶ added in v1.34.0
GetPaymentIntent retrieves a payment intent by ID.
GET /v1/billing/payment-intents/:id
func GetPaymentMethod ¶ added in v1.34.0
GetPaymentMethod retrieves a payment method by ID.
GET /v1/billing/payment-methods/:id
func GetSetupIntent ¶ added in v1.34.0
GetSetupIntent retrieves a setup intent by ID.
GET /v1/billing/setup-intents/:id
func GetSubscriptionItem ¶ added in v1.34.0
GetSubscriptionItem retrieves a subscription item by ID.
GET /v1/billing/subscription-items/:id
func GetSubscriptionSchedule ¶ added in v1.34.0
GetSubscriptionSchedule retrieves a subscription schedule by ID.
GET /v1/billing/subscription-schedules/:id
func GetTier ¶ added in v1.36.4
GetTier returns the billing tier, limits, and effective balance for a user.
For IAM-authenticated requests the tier is read from the JWT claim. For service-to-service calls the tier may be passed as a query parameter.
GET /v1/billing/tier?user=hanzo/alice
Response includes the tier config plus the effective available balance. There is no free tier: a zero-balance account has effectiveAvailable == 0 and is gated. The daily-credit term is 0 for every tier (see billing/tier); onboarding funds an account once via the starter-credit grant, and once that is spent the account is gated until it is topped up.
func GetUsage ¶
GetUsage returns usage transactions for an IAM user, filtered by tag "api-usage".
GET /v1/billing/usage?user=hanzo/alice¤cy=usd
func GetUsageRollup ¶ added in v1.42.32
GetUsageRollup returns the unified plan + included-usage + consumed + overage + balance view for a user, for the current UTC month. This is the single read surface the console billing UI renders. All figures are derived from the same transactions the gateway's balance gate reads — no separate store.
GET /v1/billing/usage-rollup?user=hanzo/alice&plan=pro
`plan` is optional; when omitted it is resolved from the user's subscription.
func GetWebhookEndpoint ¶ added in v1.34.0
GetWebhookEndpoint retrieves a webhook endpoint.
GET /v1/billing/webhook-endpoints/:id
func GrantAllotment ¶ added in v1.42.32
GrantAllotment grants the calling/target user's plan-included monthly usage credit for the current UTC month, idempotently.
POST /v1/billing/allotment/grant { "user": "hanzo/alice", "plan": "pro" }
The credit lands as an expiring balance deposit, so the gateway prepaid balance gate (available > 0) passes while the tenant is within allotment and fails closed once both the included credit and any purchased balance are exhausted. Admin token required.
func HandleProviderWebhook ¶ added in v1.37.0
HandleProviderWebhook is the single ingress for payment-provider webhooks. It dispatches to the matching processor in payment/router, validates the signature, records the event in billing_events, and — for subscription lifecycle events — updates the local subscription row keyed by ProviderId.
POST /v1/billing/webhooks/:provider
The :provider path segment is informational; signature verification picks the right processor regardless. We pass the path segment as a lightweight filter so webhook endpoints are URL-scoped per-provider (easier in Stripe dashboard configuration).
func IncludedMonthlyCents ¶ added in v1.42.32
IncludedMonthlyCents returns the recurring monthly included-usage allotment for a plan slug, in cents. Returns 0 when the plan is unknown or declares no included allotment. This is the single catalog-derived input to the monthly allotment grant — the dollar value is the plan's declared cloud credit (@hanzo/plans limits.includedCloudCredits / includedCloudCreditsPerUser, i.e. the cloud.included_credits_usd entitlement).
func IngestSBOM ¶ added in v1.42.45
IngestSBOM stores the normalized SBOM for a built image.
POST /v1/billing/sbom
Called by the arcd build pipeline after `docker push`: it runs `syft <image> -o cyclonedx-json`, normalizes the component graph to {purl, name, ecosystem, version, scope}, and POSTs it here keyed by the immutable image digest. Idempotent on ImageDigest — re-ingesting the same image updates the record in place.
func InvoicePreview ¶
InvoicePreview calculates an invoice preview: usage x pricing - credits.
POST /v1/billing/invoice-preview
func ListAccountMembers ¶ added in v1.36.3
ListAccountMembers returns the members of a billing account (org). Currently returns the requesting IAM user as the sole member, since Commerce does not store a full membership roster (that lives in IAM).
GET /v1/billing/accounts/:id/members
func ListBalanceTransactions ¶ added in v1.34.0
ListBalanceTransactions lists balance transactions for a customer.
GET /v1/billing/balance-transactions?customerId=...
func ListBankTransferInstructions ¶ added in v1.34.0
ListBankTransferInstructions lists bank transfer instructions, optionally filtered by customerId.
GET /v1/billing/bank-transfer-instructions?customerId=...
func ListBillingAccounts ¶ added in v1.36.3
ListBillingAccounts returns billing accounts visible to the caller. In Commerce each organization is one billing account. The authenticated org is returned as the single account for the current token.
GET /v1/billing/accounts
func ListBillingEvents ¶ added in v1.34.0
ListBillingEvents lists billing events, optionally filtered by type or objectId.
GET /v1/billing/events?type=...&objectId=...
func ListBillingSubscriptions ¶ added in v1.34.0
ListBillingSubscriptions lists subscriptions for a user.
GET /v1/billing/subscriptions?userId=...
func ListCreditGrants ¶
ListCreditGrants lists credit grants for a user.
GET /v1/billing/credit-grants?userId=...
func ListCreditNotes ¶ added in v1.34.0
ListCreditNotes lists credit notes, optionally filtered by invoiceId or customerId.
GET /v1/billing/credit-notes?invoiceId=...&customerId=...
func ListDNSPlans ¶ added in v1.36.4
ListDNSPlans returns the available DNS plans.
GET /v1/dns/plans
func ListDisputes ¶ added in v1.34.0
ListDisputes lists disputes.
GET /v1/billing/disputes?paymentIntentId=...
func ListInvoices ¶ added in v1.34.0
ListInvoices lists billing invoices, optionally filtered by userId and status.
GET /v1/billing/invoices?userId=...&status=...
func ListOSSAccruals ¶ added in v1.42.45
ListOSSAccruals returns accrual ledger lines, optionally filtered by package PURL or spending org.
GET /v1/billing/oss-accruals?purl=&org=
func ListPaymentIntents ¶ added in v1.34.0
ListPaymentIntents lists payment intents, optionally filtered by customerId.
GET /v1/billing/payment-intents?customerId=...
func ListPaymentMethods ¶ added in v1.34.0
ListPaymentMethods lists payment methods for a customer.
GET /v1/billing/payment-methods?customerId=...&type=...
func ListPlans ¶ added in v1.36.3
ListPlans returns the list of available plans, optionally filtered by category. Data is loaded at startup from embedded JSON plan definitions.
GET /v1/billing/plans GET /v1/billing/plans?category=dns
func ListPricingRules ¶
ListPricingRules lists pricing rules, optionally filtered by meter or plan.
GET /v1/billing/pricing-rules?meterId=...&planId=...
func ListRefunds ¶ added in v1.34.0
ListRefunds lists refunds, optionally filtered by paymentIntentId or invoiceId.
GET /v1/billing/refunds?paymentIntentId=...&invoiceId=...
func ListSBOMs ¶ added in v1.42.45
ListSBOMs returns the stored SBOM records (metadata only, not components).
GET /v1/billing/sbom
func ListSpendAlerts ¶ added in v1.36.3
ListSpendAlerts returns the ORG's spend alerts (budgets/caps) plus derived period spend. It is the console Budgets read AND the source ScopeRules uses for the rate-limit config, so it MUST key on the same org the writer stored under.
GET /v1/billing/spend-alerts
func ListSubscriptionItems ¶ added in v1.34.0
ListSubscriptionItems lists items for a subscription.
GET /v1/billing/subscription-items?subscriptionId=...
func ListSubscriptionSchedules ¶ added in v1.34.0
ListSubscriptionSchedules lists subscription schedules.
GET /v1/billing/subscription-schedules?customerId=...&status=...
func ListTransactions ¶ added in v1.37.0
ListTransactions returns transactions for an IAM user, newest first.
GET /v1/billing/transactions?user=hanzo/alice&limit=100&offset=0¤cy=usd
Response: { "transactions": [...], "count": N, "user": "hanzo/alice" }
func ListWebhookEndpoints ¶ added in v1.34.0
ListWebhookEndpoints lists all webhook endpoints.
GET /v1/billing/webhook-endpoints
func MigrateHUSD ¶ added in v1.46.38
MigrateHUSD moves every org's existing DB-ledger balance onto chain with zero drift (one-time). Dry-run by default (reports the snapshot + reconcile without minting); pass ?execute=true to mint. Platform-only.
POST /v1/billing/husd/migrate?execute=true
func PayInvoice ¶ added in v1.34.0
PayInvoice attempts to collect payment on an open invoice.
POST /v1/billing/invoices/:id/pay
func PortalInvoices ¶ added in v1.34.0
PortalInvoices returns the customer's invoice list.
GET /v1/billing/portal/invoices?customerId=...
func PortalOverview ¶ added in v1.34.0
PortalOverview returns a billing summary for the authenticated customer.
GET /v1/billing/portal/overview?customerId=...
func PortalPaymentMethods ¶ added in v1.34.0
PortalPaymentMethods returns the customer's payment methods.
GET /v1/billing/portal/payment-methods?customerId=...
func PortalSubscriptions ¶ added in v1.34.0
PortalSubscriptions returns the customer's subscriptions.
GET /v1/billing/portal/subscriptions?customerId=...
func ReactivateBillingSubscription ¶ added in v1.34.0
ReactivateBillingSubscription reactivates a canceled subscription.
POST /v1/billing/subscriptions/:id/reactivate
func ReconcileInboundTransfer ¶ added in v1.34.0
ReconcileInboundTransfer matches an incoming bank transfer by reference and creates a balance transaction for the customer.
POST /v1/billing/bank-transfer-instructions/reconciliation/match
func RecordDNSUsage ¶ added in v1.36.4
RecordDNSUsage records a batch of DNS query usage for a zone owner. The zone's owner is looked up via the user field. Usage is checked against the plan's daily query limit.
POST /v1/dns/usage
func RecordMeterEvents ¶
RecordMeterEvents records one or more meter events (batch up to 100).
POST /v1/billing/meter-events
func RecordUsage ¶
RecordUsage records an API usage event as a Withdraw transaction.
POST /v1/billing/usage
Creates a withdraw transaction deducting the cost from the user's balance.
func Refund ¶
Refund creates a deposit tagged "refund" to REVERSE a prior charge, correcting an overcharge. The metadata links back to the original transaction.
H1 (money-correctness). Previously this minted an arbitrary, uncapped credit against an UNVALIDATED originalTransactionId — a refund could exceed the original, name a non-existent or foreign transaction, refund a credit (doubling a deposit), or be replayed to double-refund. It is now fully validated and idempotent: the original MUST exist in THIS org's ledger, be a charge (Withdraw) for the SAME subject, and bound the amount (refund ≤ original); and there is AT MOST ONE refund per original transaction (keyed idempotency), so a retry replays and any second refund of the same charge is refused. Fail-closed throughout.
POST /v1/billing/refund
func ReleaseSubscriptionSchedule ¶ added in v1.34.0
ReleaseSubscriptionSchedule releases a subscription schedule.
POST /v1/billing/subscription-schedules/:id/release
func RemoveAccountMember ¶ added in v1.36.3
RemoveAccountMember is a stub. Member removal is done via IAM.
DELETE /v1/billing/accounts/:id/members/:memberId
func RemoveInvoiceLineItem ¶ added in v1.34.0
RemoveInvoiceLineItem removes a line item from a draft invoice by index or line item ID.
DELETE /v1/billing/invoices/:id/line-items/:itemId
func RenewBillingSubscription ¶ added in v1.34.0
RenewBillingSubscription manually triggers a billing cycle renewal. Normally this would be automated by Temporal, but this endpoint allows manual triggering for testing and for deployments without Temporal.
POST /v1/billing/subscriptions/:id/renew
func Route ¶
Route registers billing endpoints for service-to-service calls. These are internal endpoints used by Cloud-API; require admin token.
func RunAllotments ¶ added in v1.42.32
RunAllotments grants the monthly included allotment to every user with an active/trialing subscription in the request's organization, for the current UTC month. Idempotent per (user, period). Intended for the platform scheduler to invoke at period start (alongside the billing cycle).
POST /v1/billing/allotment/run
func RunAutoRechargeAllOrgs ¶ added in v1.42.38
RunAutoRechargeAllOrgs iterates every organization and, for those with auto-recharge enabled whose available balance is below the threshold, charges the default payment method and credits the balance. Intended to be invoked on a recurring schedule (CronJob) by the platform.
POST /v1/billing/auto-recharge/run-all
func RunBillingCycle ¶ added in v1.36.4
RunBillingCycle processes all subscriptions whose current period has ended for the request's organization. It generates invoices and attempts collection for each due subscription.
POST /v1/billing/cycle/run
func RunBillingCycleAllOrgs ¶ added in v1.36.4
RunBillingCycleAllOrgs iterates every organization and processes due subscriptions across all of them. This is intended for the platform scheduler to invoke on a recurring basis.
POST /v1/billing/cycle/run-all
func RunBillingCycleUser ¶ added in v1.36.4
RunBillingCycleUser processes due subscriptions for a single user within the request's organization.
POST /v1/billing/cycle/run-user
func SetAutoRecharge ¶ added in v1.42.38
SetAutoRecharge upserts the org's auto-recharge config.
PUT /v1/billing/auto-recharge
Enabling requires a default payment method on file (the card that will be charged off-session when the balance runs low).
func SetDefaultPaymentMethod ¶ added in v1.34.0
SetDefaultPaymentMethod sets the default payment method for a customer.
POST /v1/billing/customers/:id/default-payment-method
func SetOrgTestMode ¶ added in v1.42.38
SetOrgTestMode toggles the org's live flag (org.Live) and its test-mode view. org.Live marks transactions Test=true and is the FALLBACK Square-environment signal: when the deployment does NOT set SQUARE_ENVIRONMENT, a test org uses Square sandbox and a live org uses production (via org.TestMode). When the deployment DOES set SQUARE_ENVIRONMENT (the per-env authority: mainnet=production, testnet/devnet=sandbox), that env governs which Square environment is charged regardless of this flag — on mainnet there is no sandbox charge. Admin-only — a user must not be able to move their own org to sandbox to dodge real charges.
POST /v1/billing/test-mode { testMode: bool }
func SettleHUSD ¶ added in v1.46.38
SettleHUSD sweeps every org's on-chain drift back to the treasury (metered usage settled org→treasury). Platform-only, CronJob-driven. Idempotent (self-correcting drift). Returns the per-org settlement outcomes.
POST /v1/billing/husd/settle
func StatusHUSD ¶ added in v1.46.38
StatusHUSD reports the chain-ledger configuration + whether it is enabled — a read-only observability surface (no secrets: the treasury key is never exposed).
GET /v1/billing/husd/status
func SubmitDisputeEvidence ¶ added in v1.34.0
SubmitDisputeEvidence submits evidence for a dispute.
PATCH /v1/billing/disputes/:id
func SyncHUSD ¶ added in v1.46.38
SyncHUSD runs one indexer pass — the backfill + reconcile safety net behind the synchronous mint-time projection. Driven by an external CronJob (mirrors the contributor-payout execute endpoint). Platform-only (touches the money ledger).
POST /v1/billing/husd/sync
func TierCheck ¶ added in v1.36.4
TierCheck is a lightweight endpoint for model-access gating. It returns the tier config and whether a specific model is allowed, without computing the full balance. Used by Chat and white-label services.
GET /v1/billing/tier-check?user=hanzo/alice&model=zen4-max
func TokenizeCard ¶ added in v1.36.3
TokenizeCard accepts raw card data server-side and returns a provider token. Raw PAN is never stored; it is forwarded directly to the configured payment provider and discarded.
Card tokenization should be done client-side using the Square Web Payments SDK. This endpoint returns 503 as server-side tokenization requires PCI DSS Level 1 compliance. Use the Square Web Payments SDK (SqPaymentForm) instead.
POST /v1/billing/card/tokenize
func Topup ¶ added in v1.36.4
Topup charges a saved payment method and credits the user's balance.
POST /v1/billing/topup
Body: { userId, paymentMethodId, amountCents, currency? } Returns: { transactionId, balanceCents, status }
func TopupWithToken ¶ added in v1.37.0
TopupWithToken charges a Square Web Payments SDK nonce and credits the org's canonical balance. Use this for one-time card top-ups without saving a payment method first — the cold-customer "add credits" path.
POST /v1/billing/topup/token
Body: { sourceId, amountCents, currency? } Header (optional): X-Idempotency-Key — a retry/double-submit with the same key (or, absent a key, the same single-use nonce) never double-charges or double-credits; it replays the first result. Returns: { transactionId, balanceCents, status }
func UpcomingInvoice ¶ added in v1.34.0
UpcomingInvoice generates a preview of the next invoice for a subscription.
GET /v1/billing/invoices/upcoming?userId=...&subscriptionId=...
func UpdateBillingSubscription ¶ added in v1.34.0
UpdateBillingSubscription updates a subscription (plan change, quantity).
PATCH /v1/billing/subscriptions/:id
func UpdateMemberRole ¶ added in v1.36.3
UpdateMemberRole is a stub. Role updates are done via IAM.
PATCH /v1/billing/accounts/:id/members/:memberId
func UpdatePaymentMethod ¶ added in v1.34.0
UpdatePaymentMethod updates a payment method.
PATCH /v1/billing/payment-methods/:id
func UpdateSpendAlert ¶ added in v1.36.3
UpdateSpendAlert patches an existing spend alert / cap. Only the fields present in the body change; the rest are preserved.
PATCH /v1/billing/spend-alerts/:id
func UpdateSubscriptionItem ¶ added in v1.34.0
UpdateSubscriptionItem updates a subscription item (e.g. seat count).
PATCH /v1/billing/subscription-items/:id
func UpdateSubscriptionSchedule ¶ added in v1.34.0
UpdateSubscriptionSchedule updates phases or end behavior.
PATCH /v1/billing/subscription-schedules/:id
func UpdateWebhookEndpoint ¶ added in v1.34.0
UpdateWebhookEndpoint updates a webhook endpoint configuration.
PATCH /v1/billing/webhook-endpoints/:id
func VoidCreditGrant ¶
VoidCreditGrant voids a specific credit grant, making it unusable.
POST /v1/billing/credit-grants/:id/void
func VoidCreditNote ¶ added in v1.34.0
VoidCreditNote voids a credit note.
POST /v1/billing/credit-notes/:id/void
func VoidInvoice ¶ added in v1.34.0
VoidInvoice voids a draft or open invoice.
POST /v1/billing/invoices/:id/void
func Withdraw ¶ added in v1.37.0
Withdraw creates a withdrawal transaction for an IAM user.
POST /v1/billing/withdraw
Used when a user explicitly moves funds out of their Commerce balance (e.g. funding a bot wallet, manual withdrawal). Non-admin callers may only withdraw from their own account; admin callers may withdraw on behalf of any user.
Fails with 402 if the user has insufficient available balance.
func ZapDispatch ¶
ZapDispatch is the single ZAP-over-HTTP endpoint for billing.
Types ¶
type Plan ¶ added in v1.42.20
type Plan struct {
Slug string
Name string
Description string
Category string
PriceMonth int64
PriceYear int64
Currency string
}
Plan is the exported snapshot used by external seeders (e.g. the Stripe parity seed in commerce.go). It mirrors the subset of fields the seed populates onto seed.Plan, with field names that match the caller's expectations (PriceMonth / PriceYear are cent-denominated monthly + annual prices). Internal callers stick with staticPlan; this type exists so the public surface doesn't leak the unexported shape and so we can evolve them independently.
func LookupStaticPlan ¶ added in v1.37.0
LookupStaticPlan resolves a single plan by slug from the embedded catalog and returns it in the exported Plan shape. Returns nil when the slug is unknown. It is the single-plan analogue of StaticPlans and shares the same staticPlan -> Plan projection, so external seeders (e.g. cmd/grant) never touch the unexported wire type.
func StaticPlans ¶ added in v1.37.0
func StaticPlans() []Plan
StaticPlans returns a snapshot of the embedded plan catalog as the exported Plan shape. The slice is freshly allocated so callers may mutate freely without bleeding into the canonical hanzoPlans var.
Source Files
¶
- accounts.go
- allotment.go
- authz.go
- autorecharge.go
- balance.go
- bank_transfers.go
- bucketed.go
- capabilities.go
- card_tokenize.go
- credit.go
- credit_grants.go
- credit_notes.go
- customer_balance.go
- cycle.go
- deposit.go
- disputes.go
- dns_usage.go
- events.go
- gpu_charge.go
- handlers.go
- husd_mint.go
- invoice_enhancements.go
- invoice_pdf.go
- invoice_preview.go
- invoices.go
- me.go
- meter_events.go
- meters.go
- osspayout.go
- payment_config.go
- payment_intents.go
- payment_methods.go
- payouts.go
- plans.go
- portal.go
- pricing_rules.go
- refund.go
- refunds.go
- resolve.go
- setup_intents.go
- spend_alerts.go
- spend_cap.go
- square_cardonfile.go
- status.go
- subscription_items.go
- subscription_schedules.go
- subscriptions.go
- tier.go
- topup.go
- topup_token.go
- transactions.go
- trial.go
- usage.go
- webhooks.go
- withdraw.go
- zap.go