Documentation
¶
Index ¶
- func AddAccountMember(c *gin.Context)
- func AddInvoiceLineItem(c *gin.Context)
- func AdjustCustomerBalance(c *gin.Context)
- func ApplyInvoiceDiscount(c *gin.Context)
- 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 *gin.Context)
- func CancelBillingSubscription(c *gin.Context)
- func CancelPaymentIntent(c *gin.Context)
- func CancelPayout(c *gin.Context)
- func CancelSetupIntent(c *gin.Context)
- func CancelSubscriptionSchedule(c *gin.Context)
- func CapturePaymentIntent(c *gin.Context)
- func ChargeGPU(c *gin.Context)
- func CloseDispute(c *gin.Context)
- func ConfirmPaymentIntent(c *gin.Context)
- func ConfirmSetupIntent(c *gin.Context)
- func CreateBankTransferInstruction(c *gin.Context)
- func CreateBillingAccount(c *gin.Context)
- func CreateBillingSubscription(c *gin.Context)
- func CreateCreditGrant(c *gin.Context)
- func CreateCreditNote(c *gin.Context)
- func CreateInvoice(c *gin.Context)
- func CreateMeter(c *gin.Context)
- func CreatePaymentIntent(c *gin.Context)
- func CreatePaymentMethod(c *gin.Context)
- func CreatePayout(c *gin.Context)
- func CreatePricingRule(c *gin.Context)
- func CreateRefund(c *gin.Context)
- func CreateSetupIntent(c *gin.Context)
- func CreateSpendAlert(c *gin.Context)
- func CreateSubscriptionItem(c *gin.Context)
- func CreateSubscriptionSchedule(c *gin.Context)
- func CreateWebhookEndpoint(c *gin.Context)
- func DeletePricingRule(c *gin.Context)
- func DeleteSpendAlert(c *gin.Context)
- func DeleteSubscriptionItem(c *gin.Context)
- func DeleteWebhookEndpoint(c *gin.Context)
- func Deposit(c *gin.Context)
- func DetachPaymentMethod(c *gin.Context)
- func DownloadInvoicePDF(c *gin.Context)
- func FinalizeInvoice(c *gin.Context)
- func GPUChargeEligibility(c *gin.Context)
- func GetAutoRecharge(c *gin.Context)
- func GetBalance(c *gin.Context)
- func GetBalanceAll(c *gin.Context)
- func GetBankTransferInstruction(c *gin.Context)
- func GetBillingEvent(c *gin.Context)
- func GetBillingStatus(c *gin.Context)
- func GetBillingSubscription(c *gin.Context)
- func GetCapabilities(c *gin.Context)
- func GetCreditBalance(c *gin.Context)
- func GetCreditBalanceBreakdown(c *gin.Context)
- func GetCreditNote(c *gin.Context)
- func GetCustomerBalance(c *gin.Context)
- func GetDNSUsageSummary(c *gin.Context)
- func GetDispute(c *gin.Context)
- func GetInvoice(c *gin.Context)
- func GetMeter(c *gin.Context)
- func GetMeterEventsSummary(c *gin.Context)
- func GetMyBalance(c *gin.Context)
- func GetOSSPayoutSummary(c *gin.Context)
- func GetPaymentConfig(c *gin.Context)
- func GetPaymentIntent(c *gin.Context)
- func GetPaymentMethod(c *gin.Context)
- func GetPayout(c *gin.Context)
- func GetPlan(c *gin.Context)
- func GetRefund(c *gin.Context)
- func GetSetupIntent(c *gin.Context)
- func GetSubscriptionItem(c *gin.Context)
- func GetSubscriptionSchedule(c *gin.Context)
- func GetTier(c *gin.Context)
- func GetUsage(c *gin.Context)
- func GetUsageRollup(c *gin.Context)
- func GetWebhookEndpoint(c *gin.Context)
- func GrantAllotment(c *gin.Context)
- func GrantStarter(c *gin.Context)
- func GrantStarterCredit(c *gin.Context)
- func HandleProviderWebhook(c *gin.Context)
- func IncludedMonthlyCents(slug string) int64
- func IngestSBOM(c *gin.Context)
- func InvoicePreview(c *gin.Context)
- func ListAccountMembers(c *gin.Context)
- func ListBalanceTransactions(c *gin.Context)
- func ListBankTransferInstructions(c *gin.Context)
- func ListBillingAccounts(c *gin.Context)
- func ListBillingEvents(c *gin.Context)
- func ListBillingSubscriptions(c *gin.Context)
- func ListCreditGrants(c *gin.Context)
- func ListCreditNotes(c *gin.Context)
- func ListDNSPlans(c *gin.Context)
- func ListDisputes(c *gin.Context)
- func ListInvoices(c *gin.Context)
- func ListMeters(c *gin.Context)
- func ListOSSAccruals(c *gin.Context)
- func ListPaymentIntents(c *gin.Context)
- func ListPaymentMethods(c *gin.Context)
- func ListPayouts(c *gin.Context)
- func ListPlans(c *gin.Context)
- func ListPricingRules(c *gin.Context)
- func ListRefunds(c *gin.Context)
- func ListSBOMs(c *gin.Context)
- func ListSpendAlerts(c *gin.Context)
- func ListSubscriptionItems(c *gin.Context)
- func ListSubscriptionSchedules(c *gin.Context)
- func ListTransactions(c *gin.Context)
- func ListWebhookEndpoints(c *gin.Context)
- func PayInvoice(c *gin.Context)
- func PortalInvoices(c *gin.Context)
- func PortalOverview(c *gin.Context)
- func PortalPaymentMethods(c *gin.Context)
- func PortalSubscriptions(c *gin.Context)
- func PostMyWelcome(c *gin.Context)
- func ReactivateBillingSubscription(c *gin.Context)
- func ReconcileInboundTransfer(c *gin.Context)
- func RecordDNSUsage(c *gin.Context)
- func RecordMeterEvents(c *gin.Context)
- func RecordUsage(c *gin.Context)
- func Refund(c *gin.Context)
- func ReleaseSubscriptionSchedule(c *gin.Context)
- func RemoveAccountMember(c *gin.Context)
- func RemoveInvoiceLineItem(c *gin.Context)
- func RenewBillingSubscription(c *gin.Context)
- func Route(r router.Router, args ...gin.HandlerFunc)
- func RunAllotments(c *gin.Context)
- func RunAutoRechargeAllOrgs(c *gin.Context)
- func RunBillingCycle(c *gin.Context)
- func RunBillingCycleAllOrgs(c *gin.Context)
- func RunBillingCycleUser(c *gin.Context)
- func SetAutoRecharge(c *gin.Context)
- func SetDefaultPaymentMethod(c *gin.Context)
- func SetOrgTestMode(c *gin.Context)
- func SubmitDisputeEvidence(c *gin.Context)
- func TierCheck(c *gin.Context)
- func TokenizeCard(c *gin.Context)
- func Topup(c *gin.Context)
- func TopupWithToken(c *gin.Context)
- func UpcomingInvoice(c *gin.Context)
- func UpdateBillingSubscription(c *gin.Context)
- func UpdateMemberRole(c *gin.Context)
- func UpdatePaymentMethod(c *gin.Context)
- func UpdateSpendAlert(c *gin.Context)
- func UpdateSubscriptionItem(c *gin.Context)
- func UpdateSubscriptionSchedule(c *gin.Context)
- func UpdateWebhookEndpoint(c *gin.Context)
- func VoidCreditGrant(c *gin.Context)
- func VoidCreditNote(c *gin.Context)
- func VoidInvoice(c *gin.Context)
- func Withdraw(c *gin.Context)
- func ZapDispatch(c *gin.Context)
- 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 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 new spend alert for a user.
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 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))). 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 GrantStarter ¶ added in v1.42.38
GrantStarter ensures an explicit subject has received the one-time $100 starter credit, idempotently. It is the on-signup welcome grant invoked by trusted services (chat, cloud-api) with the commerce service token — the service-to-service twin of POST /billing/credit (GrantStarterCredit, the admin/UI path). Neither requires a payment method, so a brand-new user "just works" on first chat without a card (a card gates top-up BEYOND the credit).
The subject is explicit and caller-supplied: "owner/name" for per-user (personal-org) billing, or the org slug for org-pooled billing — it MUST match the subject the cloud gateway debits and reads (object.BillingSubject in hanzoai/ai). The grant is scoped to the X-Org-Id namespace.
Idempotent + race-safe: credit.GrantIfEligibleNow dedupes on the starter-credit tag inside a datastore transaction, so duplicate/concurrent calls (e.g. the same user opening several chats at once) never double-grant — no bleed.
POST /v1/billing/grant-starter {"user":"hanzo/alice","trigger":"chat_first_use"}
func GrantStarterCredit ¶
GrantStarterCredit creates a $100 USD starter credit for a new org. The credit expires after 365 days if unused. Tagged "starter-credit" so it can be identified in transaction history.
No payment method is required — the starter credit is the on-signup grant that lets a new org evaluate the platform before adding a card. A verified payment method is required only to top up BEYOND the starter credit. Idempotent: deduped by the starter-credit tag.
POST /v1/billing/credit
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 all spend alerts for the given user.
GET /v1/billing/spend-alerts?user=:userId
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 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 PostMyWelcome ¶ added in v1.42.0
PostMyWelcome grants the welcome credit (idempotent, tag-deduped) to the calling user. Unlike POST /billing/credit — which requires an admin token and an explicit user — this endpoint is callable with just an IAM bearer token (user inferred from headers), designed to be invoked by the playground SPA on first successful login.
Idempotent: if the credit was already granted (or zapped), returns 200 with `granted: false` instead of failing.
POST /v1/billing/me/welcome
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 ¶
func Route(r router.Router, args ...gin.HandlerFunc)
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 SubmitDisputeEvidence ¶ added in v1.34.0
SubmitDisputeEvidence submits evidence for a dispute.
PATCH /v1/billing/disputes/:id
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 updates title or threshold on an existing spend alert.
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_grants.go
- credit_notes.go
- customer_balance.go
- cycle.go
- deposit.go
- disputes.go
- dns_usage.go
- events.go
- gpu_charge.go
- grant_starter.go
- handlers.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
- setup_intents.go
- spend_alerts.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