billing

package
v1.42.23 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 7, 2026 License: MIT Imports: 53 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddAccountMember added in v1.36.3 

func AddAccountMember(c *gin.Context)

AddAccountMember is a stub. Member management is done via IAM. 

POST /v1/billing/accounts/:id/members

func AddInvoiceLineItem added in v1.34.0 

func AddInvoiceLineItem(c *gin.Context)

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 

func AdjustCustomerBalance(c *gin.Context)

AdjustCustomerBalance manually adjusts a customer's balance. 

POST /v1/billing/customer-balance/adjustments

func ApplyInvoiceDiscount added in v1.34.0 

func ApplyInvoiceDiscount(c *gin.Context)

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 

func BurnCreditsPreview(db *datastore.Datastore, userId string, amount int64) (int64, error)

BurnCreditsPreview calculates credit burn without actually deducting. Returns the remaining amount after credits would be applied.

func CalculateInvoiceTax added in v1.34.0 

func CalculateInvoiceTax(c *gin.Context)

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 

func CancelBillingSubscription(c *gin.Context)

CancelBillingSubscription cancels a subscription. 

POST /v1/billing/subscriptions/:id/cancel

func CancelPaymentIntent added in v1.34.0 

func CancelPaymentIntent(c *gin.Context)

CancelPaymentIntent cancels a payment intent. 

POST /v1/billing/payment-intents/:id/cancel

func CancelPayout added in v1.34.0 

func CancelPayout(c *gin.Context)

CancelPayout cancels a pending payout. 

POST /v1/billing/payouts/:id/cancel

func CancelSetupIntent added in v1.34.0 

func CancelSetupIntent(c *gin.Context)

CancelSetupIntent cancels a setup intent. 

POST /v1/billing/setup-intents/:id/cancel

func CancelSubscriptionSchedule added in v1.34.0 

func CancelSubscriptionSchedule(c *gin.Context)

CancelSubscriptionSchedule cancels a subscription schedule. 

POST /v1/billing/subscription-schedules/:id/cancel

func CapturePaymentIntent added in v1.34.0 

func CapturePaymentIntent(c *gin.Context)

CapturePaymentIntent captures a previously authorized payment intent. 

POST /v1/billing/payment-intents/:id/capture

func CloseDispute added in v1.34.0 

func CloseDispute(c *gin.Context)

CloseDispute closes a dispute. 

POST /v1/billing/disputes/:id/close

func ConfirmPaymentIntent added in v1.34.0 

func ConfirmPaymentIntent(c *gin.Context)

ConfirmPaymentIntent confirms a payment intent. 

POST /v1/billing/payment-intents/:id/confirm

func ConfirmSetupIntent added in v1.34.0 

func ConfirmSetupIntent(c *gin.Context)

ConfirmSetupIntent confirms a setup intent, saving the payment method. 

POST /v1/billing/setup-intents/:id/confirm

func CreateBankTransferInstruction added in v1.34.0 

func CreateBankTransferInstruction(c *gin.Context)

CreateBankTransferInstruction creates bank transfer details for a customer. 

POST /v1/billing/bank-transfer-instructions

func CreateBillingAccount added in v1.36.3 

func CreateBillingAccount(c *gin.Context)

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 

func CreateBillingSubscription(c *gin.Context)

CreateBillingSubscription creates a new subscription and starts the billing lifecycle. 

POST /v1/billing/subscriptions

func CreateCreditGrant 

func CreateCreditGrant(c *gin.Context)

CreateCreditGrant creates a new credit grant for a user. 

POST /v1/billing/credit-grants

func CreateCreditNote added in v1.34.0 

func CreateCreditNote(c *gin.Context)

CreateCreditNote creates a credit note against an invoice. 

POST /v1/billing/credit-notes

func CreateInvoice added in v1.34.0 

func CreateInvoice(c *gin.Context)

CreateInvoice creates a new draft billing invoice. 

POST /v1/billing/invoices

func CreateMeter 

func CreateMeter(c *gin.Context)

CreateMeter creates a new usage meter definition. 

POST /v1/billing/meters

func CreatePaymentIntent added in v1.34.0 

func CreatePaymentIntent(c *gin.Context)

CreatePaymentIntent creates a new payment intent. 

POST /v1/billing/payment-intents

func CreatePaymentMethod added in v1.34.0 

func CreatePaymentMethod(c *gin.Context)

CreatePaymentMethod creates and attaches a payment method to a customer. 

POST /v1/billing/payment-methods

func CreatePayout added in v1.34.0 

func CreatePayout(c *gin.Context)

CreatePayout creates a new outbound payout. 

POST /v1/billing/payouts

func CreatePricingRule 

func CreatePricingRule(c *gin.Context)

CreatePricingRule creates a new pricing rule for a meter. 

POST /v1/billing/pricing-rules

func CreateRefund added in v1.34.0 

func CreateRefund(c *gin.Context)

CreateRefund creates a full or partial refund. 

POST /v1/billing/refunds

func CreateSetupIntent added in v1.34.0 

func CreateSetupIntent(c *gin.Context)

CreateSetupIntent creates a new setup intent for saving a payment method. 

POST /v1/billing/setup-intents

func CreateSpendAlert added in v1.36.3 

func CreateSpendAlert(c *gin.Context)

CreateSpendAlert creates a new spend alert for a user. 

POST /v1/billing/spend-alerts

func CreateSubscriptionItem added in v1.34.0 

func CreateSubscriptionItem(c *gin.Context)

CreateSubscriptionItem adds an item to a subscription. 

POST /v1/billing/subscription-items

func CreateSubscriptionSchedule added in v1.34.0 

func CreateSubscriptionSchedule(c *gin.Context)

CreateSubscriptionSchedule creates a new subscription schedule. 

POST /v1/billing/subscription-schedules

func CreateWebhookEndpoint added in v1.34.0 

func CreateWebhookEndpoint(c *gin.Context)

CreateWebhookEndpoint registers a new webhook endpoint. 

POST /v1/billing/webhook-endpoints

func DeletePricingRule 

func DeletePricingRule(c *gin.Context)

DeletePricingRule removes a pricing rule by ID. 

DELETE /v1/billing/pricing-rules/:id

func DeleteSpendAlert added in v1.36.3 

func DeleteSpendAlert(c *gin.Context)

DeleteSpendAlert deletes a spend alert by ID. 

DELETE /v1/billing/spend-alerts/:id

func DeleteSubscriptionItem added in v1.34.0 

func DeleteSubscriptionItem(c *gin.Context)

DeleteSubscriptionItem removes an item from a subscription. 

DELETE /v1/billing/subscription-items/:id

func DeleteWebhookEndpoint added in v1.34.0 

func DeleteWebhookEndpoint(c *gin.Context)

DeleteWebhookEndpoint removes a webhook endpoint. 

DELETE /v1/billing/webhook-endpoints/:id

func Deposit 

func Deposit(c *gin.Context)

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 

func DetachPaymentMethod(c *gin.Context)

DetachPaymentMethod detaches (soft-deletes) a payment method. 

DELETE /v1/billing/payment-methods/:id

func FinalizeInvoice added in v1.34.0 

func FinalizeInvoice(c *gin.Context)

FinalizeInvoice transitions an invoice from draft to open. 

POST /v1/billing/invoices/:id/finalize

func GetBalance 

func GetBalance(c *gin.Context)

GetBalance returns the current balance for an IAM user. 

GET /v1/billing/balance?user=hanzo/alice&currency=usd

All amounts in cents. available = balance - holds.

func GetBalanceAll 

func GetBalanceAll(c *gin.Context)

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 

func GetBankTransferInstruction(c *gin.Context)

GetBankTransferInstruction returns a single bank transfer instruction by ID. 

GET /v1/billing/bank-transfer-instructions/:id

func GetBillingEvent added in v1.34.0 

func GetBillingEvent(c *gin.Context)

GetBillingEvent retrieves a single billing event. 

GET /v1/billing/events/:id

func GetBillingStatus added in v1.37.0 

func GetBillingStatus(c *gin.Context)

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 

func GetBillingSubscription(c *gin.Context)

GetBillingSubscription returns a single subscription. 

GET /v1/billing/subscriptions/:id

func GetCapabilities added in v1.34.0 

func GetCapabilities(c *gin.Context)

GetCapabilities returns the billing platform's supported features, payment methods, and currencies. 

GET /v1/billing/capabilities

func GetCreditBalance 

func GetCreditBalance(c *gin.Context)

GetCreditBalance returns the total available credit balance for a user. 

GET /v1/billing/credit-balance?userId=...

func GetCreditBalanceBreakdown added in v1.36.4 

func GetCreditBalanceBreakdown(c *gin.Context)

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 

func GetCreditNote(c *gin.Context)

GetCreditNote retrieves a credit note by ID. 

GET /v1/billing/credit-notes/:id

func GetCustomerBalance added in v1.34.0 

func GetCustomerBalance(c *gin.Context)

GetCustomerBalance retrieves the customer balance for a customer+currency. 

GET /v1/billing/customer-balance?customerId=...&currency=...

func GetDNSUsageSummary added in v1.36.4 

func GetDNSUsageSummary(c *gin.Context)

GetDNSUsageSummary returns a usage summary for DNS queries, zones, and records. 

GET /api/v1/dns/usage/summary?user={owner/name}&period=day|month

func GetDispute added in v1.34.0 

func GetDispute(c *gin.Context)

GetDispute retrieves a dispute by ID. 

GET /v1/billing/disputes/:id

func GetInvoice added in v1.34.0 

func GetInvoice(c *gin.Context)

GetInvoice returns a single billing invoice by ID. 

GET /v1/billing/invoices/:id

func GetMeter 

func GetMeter(c *gin.Context)

GetMeter returns a single meter by ID. 

GET /v1/billing/meters/:id

func GetMeterEventsSummary 

func GetMeterEventsSummary(c *gin.Context)

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 

func GetMyBalance(c *gin.Context)

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 /api/v1/billing/me/balance?currency=usd

func GetPaymentIntent added in v1.34.0 

func GetPaymentIntent(c *gin.Context)

GetPaymentIntent retrieves a payment intent by ID. 

GET /v1/billing/payment-intents/:id

func GetPaymentMethod added in v1.34.0 

func GetPaymentMethod(c *gin.Context)

GetPaymentMethod retrieves a payment method by ID. 

GET /v1/billing/payment-methods/:id

func GetPayout added in v1.34.0 

func GetPayout(c *gin.Context)

GetPayout retrieves a payout by ID. 

GET /v1/billing/payouts/:id

func GetPlan added in v1.36.3 

func GetPlan(c *gin.Context)

GetPlan returns a single plan by slug. 

GET /v1/billing/plans/:id

func GetRefund added in v1.34.0 

func GetRefund(c *gin.Context)

GetRefund retrieves a refund by ID. 

GET /v1/billing/refunds/:id

func GetSetupIntent added in v1.34.0 

func GetSetupIntent(c *gin.Context)

GetSetupIntent retrieves a setup intent by ID. 

GET /v1/billing/setup-intents/:id

func GetSubscriptionItem added in v1.34.0 

func GetSubscriptionItem(c *gin.Context)

GetSubscriptionItem retrieves a subscription item by ID. 

GET /v1/billing/subscription-items/:id

func GetSubscriptionSchedule added in v1.34.0 

func GetSubscriptionSchedule(c *gin.Context)

GetSubscriptionSchedule retrieves a subscription schedule by ID. 

GET /v1/billing/subscription-schedules/:id

func GetTier added in v1.36.4 

func GetTier(c *gin.Context)

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 (which for free-tier users includes the daily replenishing credit).

func GetUsage 

func GetUsage(c *gin.Context)

GetUsage returns usage transactions for an IAM user, filtered by tag "api-usage". 

GET /v1/billing/usage?user=hanzo/alice&currency=usd

func GetWebhookEndpoint added in v1.34.0 

func GetWebhookEndpoint(c *gin.Context)

GetWebhookEndpoint retrieves a webhook endpoint. 

GET /v1/billing/webhook-endpoints/:id

func GrantStarterCredit 

func GrantStarterCredit(c *gin.Context)

GrantStarterCredit creates a $5 USD starter credit for a new user. The credit expires after 30 days if unused. Tagged "starter-credit" so it can be identified in transaction history.

Requires the user to have at least one payment method on file. This prevents abuse from mass-created accounts with no payment verification. 

POST /v1/billing/credit

func HandleProviderWebhook added in v1.37.0 

func HandleProviderWebhook(c *gin.Context)

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 InvoicePreview 

func InvoicePreview(c *gin.Context)

InvoicePreview calculates an invoice preview: usage x pricing - credits. 

POST /v1/billing/invoice-preview

func ListAccountMembers added in v1.36.3 

func ListAccountMembers(c *gin.Context)

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 

func ListBalanceTransactions(c *gin.Context)

ListBalanceTransactions lists balance transactions for a customer. 

GET /v1/billing/balance-transactions?customerId=...

func ListBankTransferInstructions added in v1.34.0 

func ListBankTransferInstructions(c *gin.Context)

ListBankTransferInstructions lists bank transfer instructions, optionally filtered by customerId. 

GET /v1/billing/bank-transfer-instructions?customerId=...

func ListBillingAccounts added in v1.36.3 

func ListBillingAccounts(c *gin.Context)

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 

func ListBillingEvents(c *gin.Context)

ListBillingEvents lists billing events, optionally filtered by type or objectId. 

GET /v1/billing/events?type=...&objectId=...

func ListBillingSubscriptions added in v1.34.0 

func ListBillingSubscriptions(c *gin.Context)

ListBillingSubscriptions lists subscriptions for a user. 

GET /v1/billing/subscriptions?userId=...

func ListCreditGrants 

func ListCreditGrants(c *gin.Context)

ListCreditGrants lists credit grants for a user. 

GET /v1/billing/credit-grants?userId=...

func ListCreditNotes added in v1.34.0 

func ListCreditNotes(c *gin.Context)

ListCreditNotes lists credit notes, optionally filtered by invoiceId or customerId. 

GET /v1/billing/credit-notes?invoiceId=...&customerId=...

func ListDNSPlans added in v1.36.4 

func ListDNSPlans(c *gin.Context)

ListDNSPlans returns the available DNS plans. 

GET /api/v1/dns/plans

func ListDisputes added in v1.34.0 

func ListDisputes(c *gin.Context)

ListDisputes lists disputes. 

GET /v1/billing/disputes?paymentIntentId=...

func ListInvoices added in v1.34.0 

func ListInvoices(c *gin.Context)

ListInvoices lists billing invoices, optionally filtered by userId and status. 

GET /v1/billing/invoices?userId=...&status=...

func ListMeters 

func ListMeters(c *gin.Context)

ListMeters returns all meters for the organization. 

GET /v1/billing/meters

func ListPaymentIntents added in v1.34.0 

func ListPaymentIntents(c *gin.Context)

ListPaymentIntents lists payment intents, optionally filtered by customerId. 

GET /v1/billing/payment-intents?customerId=...

func ListPaymentMethods added in v1.34.0 

func ListPaymentMethods(c *gin.Context)

ListPaymentMethods lists payment methods for a customer. 

GET /v1/billing/payment-methods?customerId=...&type=...

func ListPayouts added in v1.34.0 

func ListPayouts(c *gin.Context)

ListPayouts lists payouts. 

GET /v1/billing/payouts

func ListPlans added in v1.36.3 

func ListPlans(c *gin.Context)

ListPlans returns the list of available plans, optionally filtered by category. Data is loaded at startup from embedded JSON plan definitions. 

GET /api/v1/billing/plans
GET /api/v1/billing/plans?category=dns

func ListPricingRules 

func ListPricingRules(c *gin.Context)

ListPricingRules lists pricing rules, optionally filtered by meter or plan. 

GET /v1/billing/pricing-rules?meterId=...&planId=...

func ListRefunds added in v1.34.0 

func ListRefunds(c *gin.Context)

ListRefunds lists refunds, optionally filtered by paymentIntentId or invoiceId. 

GET /v1/billing/refunds?paymentIntentId=...&invoiceId=...

func ListSpendAlerts added in v1.36.3 

func ListSpendAlerts(c *gin.Context)

ListSpendAlerts returns all spend alerts for the given user. 

GET /v1/billing/spend-alerts?user=:userId

func ListSubscriptionItems added in v1.34.0 

func ListSubscriptionItems(c *gin.Context)

ListSubscriptionItems lists items for a subscription. 

GET /v1/billing/subscription-items?subscriptionId=...

func ListSubscriptionSchedules added in v1.34.0 

func ListSubscriptionSchedules(c *gin.Context)

ListSubscriptionSchedules lists subscription schedules. 

GET /v1/billing/subscription-schedules?customerId=...&status=...

func ListTransactions added in v1.37.0 

func ListTransactions(c *gin.Context)

ListTransactions returns transactions for an IAM user, newest first. 

GET /v1/billing/transactions?user=hanzo/alice&limit=100&offset=0&currency=usd

Response: { "transactions": [...], "count": N, "user": "hanzo/alice" }

func ListWebhookEndpoints added in v1.34.0 

func ListWebhookEndpoints(c *gin.Context)

ListWebhookEndpoints lists all webhook endpoints. 

GET /v1/billing/webhook-endpoints

func PayInvoice added in v1.34.0 

func PayInvoice(c *gin.Context)

PayInvoice attempts to collect payment on an open invoice. 

POST /v1/billing/invoices/:id/pay

func PortalInvoices added in v1.34.0 

func PortalInvoices(c *gin.Context)

PortalInvoices returns the customer's invoice list. 

GET /v1/billing/portal/invoices?customerId=...

func PortalOverview added in v1.34.0 

func PortalOverview(c *gin.Context)

PortalOverview returns a billing summary for the authenticated customer. 

GET /v1/billing/portal/overview?customerId=...

func PortalPaymentMethods added in v1.34.0 

func PortalPaymentMethods(c *gin.Context)

PortalPaymentMethods returns the customer's payment methods. 

GET /v1/billing/portal/payment-methods?customerId=...

func PortalSubscriptions added in v1.34.0 

func PortalSubscriptions(c *gin.Context)

PortalSubscriptions returns the customer's subscriptions. 

GET /v1/billing/portal/subscriptions?customerId=...

func PostMyWelcome added in v1.42.0 

func PostMyWelcome(c *gin.Context)

PostMyWelcome grants the welcome credit (idempotent, tag-deduped) to the calling user. Unlike POST /billing/credit which requires an admin token AND a payment method on file, this endpoint is callable with just an IAM bearer token — 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 /api/v1/billing/me/welcome

func ReactivateBillingSubscription added in v1.34.0 

func ReactivateBillingSubscription(c *gin.Context)

ReactivateBillingSubscription reactivates a canceled subscription. 

POST /v1/billing/subscriptions/:id/reactivate

func ReconcileInboundTransfer added in v1.34.0 

func ReconcileInboundTransfer(c *gin.Context)

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 

func RecordDNSUsage(c *gin.Context)

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 /api/v1/dns/usage

func RecordMeterEvents 

func RecordMeterEvents(c *gin.Context)

RecordMeterEvents records one or more meter events (batch up to 100). 

POST /v1/billing/meter-events

func RecordUsage 

func RecordUsage(c *gin.Context)

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 

func Refund(c *gin.Context)

Refund creates a deposit tagged "refund" to correct an overcharge. The metadata links back to the original transaction for auditability. 

POST /v1/billing/refund

func ReleaseSubscriptionSchedule added in v1.34.0 

func ReleaseSubscriptionSchedule(c *gin.Context)

ReleaseSubscriptionSchedule releases a subscription schedule. 

POST /v1/billing/subscription-schedules/:id/release

func RemoveAccountMember added in v1.36.3 

func RemoveAccountMember(c *gin.Context)

RemoveAccountMember is a stub. Member removal is done via IAM. 

DELETE /v1/billing/accounts/:id/members/:memberId

func RemoveInvoiceLineItem added in v1.34.0 

func RemoveInvoiceLineItem(c *gin.Context)

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 

func RenewBillingSubscription(c *gin.Context)

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 RunBillingCycle added in v1.36.4 

func RunBillingCycle(c *gin.Context)

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 

func RunBillingCycleAllOrgs(c *gin.Context)

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 

func RunBillingCycleUser(c *gin.Context)

RunBillingCycleUser processes due subscriptions for a single user within the request's organization. 

POST /v1/billing/cycle/run-user

func SetDefaultPaymentMethod added in v1.34.0 

func SetDefaultPaymentMethod(c *gin.Context)

SetDefaultPaymentMethod sets the default payment method for a customer. 

POST /v1/billing/customers/:id/default-payment-method

func SubmitDisputeEvidence added in v1.34.0 

func SubmitDisputeEvidence(c *gin.Context)

SubmitDisputeEvidence submits evidence for a dispute. 

PATCH /v1/billing/disputes/:id

func TierCheck added in v1.36.4 

func TierCheck(c *gin.Context)

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 

func TokenizeCard(c *gin.Context)

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 

func Topup(c *gin.Context)

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 

func TopupWithToken(c *gin.Context)

TopupWithToken charges a Square Web Payments SDK nonce and credits user balance. Use this for one-time top-ups without saving a payment method first. 

POST /v1/billing/topup/token

Body: { sourceId, amountCents, userId?, currency? } Returns: { transactionId, balanceCents, status }

func UpcomingInvoice added in v1.34.0 

func UpcomingInvoice(c *gin.Context)

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 

func UpdateBillingSubscription(c *gin.Context)

UpdateBillingSubscription updates a subscription (plan change, quantity). 

PATCH /v1/billing/subscriptions/:id

func UpdateMemberRole added in v1.36.3 

func UpdateMemberRole(c *gin.Context)

UpdateMemberRole is a stub. Role updates are done via IAM. 

PATCH /v1/billing/accounts/:id/members/:memberId

func UpdatePaymentMethod added in v1.34.0 

func UpdatePaymentMethod(c *gin.Context)

UpdatePaymentMethod updates a payment method. 

PATCH /v1/billing/payment-methods/:id

func UpdateSpendAlert added in v1.36.3 

func UpdateSpendAlert(c *gin.Context)

UpdateSpendAlert updates title or threshold on an existing spend alert. 

PATCH /v1/billing/spend-alerts/:id

func UpdateSubscriptionItem added in v1.34.0 

func UpdateSubscriptionItem(c *gin.Context)

UpdateSubscriptionItem updates a subscription item (e.g. seat count). 

PATCH /v1/billing/subscription-items/:id

func UpdateSubscriptionSchedule added in v1.34.0 

func UpdateSubscriptionSchedule(c *gin.Context)

UpdateSubscriptionSchedule updates phases or end behavior. 

PATCH /v1/billing/subscription-schedules/:id

func UpdateWebhookEndpoint added in v1.34.0 

func UpdateWebhookEndpoint(c *gin.Context)

UpdateWebhookEndpoint updates a webhook endpoint configuration. 

PATCH /v1/billing/webhook-endpoints/:id

func VoidCreditGrant 

func VoidCreditGrant(c *gin.Context)

VoidCreditGrant voids a specific credit grant, making it unusable. 

POST /v1/billing/credit-grants/:id/void

func VoidCreditNote added in v1.34.0 

func VoidCreditNote(c *gin.Context)

VoidCreditNote voids a credit note. 

POST /v1/billing/credit-notes/:id/void

func VoidInvoice added in v1.34.0 

func VoidInvoice(c *gin.Context)

VoidInvoice voids a draft or open invoice. 

POST /v1/billing/invoices/:id/void

func Withdraw added in v1.37.0 

func Withdraw(c *gin.Context)

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 

func ZapDispatch(c *gin.Context)

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 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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.