billing

package
v1.35.0 Latest Latest
Warning

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

 Go to latest Published: Feb 24, 2026 License: MIT Imports: 40 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	StarterCreditCents = 500 // $5.00 USD
	StarterCreditDays  = 30  // expires in 30 days
	StarterCreditTag   = "starter-credit"
)

Starter credit constants.

Variables

This section is empty.

Functions

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 /api/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 /api/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 /api/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 /api/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 /api/v1/billing/subscriptions/:id/cancel

func CancelPaymentIntent added in v1.34.0 

func CancelPaymentIntent(c *gin.Context)

CancelPaymentIntent cancels a payment intent. 

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

func CancelPayout added in v1.34.0 

func CancelPayout(c *gin.Context)

CancelPayout cancels a pending payout. 

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

func CancelSetupIntent added in v1.34.0 

func CancelSetupIntent(c *gin.Context)

CancelSetupIntent cancels a setup intent. 

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

func CancelSubscriptionSchedule added in v1.34.0 

func CancelSubscriptionSchedule(c *gin.Context)

CancelSubscriptionSchedule cancels a subscription schedule. 

POST /api/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 /api/v1/billing/payment-intents/:id/capture

func CloseDispute added in v1.34.0 

func CloseDispute(c *gin.Context)

CloseDispute closes a dispute. 

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

func ConfirmPaymentIntent added in v1.34.0 

func ConfirmPaymentIntent(c *gin.Context)

ConfirmPaymentIntent confirms a payment intent. 

POST /api/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 /api/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 /api/v1/billing/bank-transfer-instructions

func CreateBillingSubscription added in v1.34.0 

func CreateBillingSubscription(c *gin.Context)

CreateBillingSubscription creates a new subscription and starts the billing lifecycle. 

POST /api/v1/billing/subscriptions

func CreateCreditGrant 

func CreateCreditGrant(c *gin.Context)

CreateCreditGrant creates a new credit grant for a user. 

POST /api/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 /api/v1/billing/credit-notes

func CreateInvoice added in v1.34.0 

func CreateInvoice(c *gin.Context)

CreateInvoice creates a new draft billing invoice. 

POST /api/v1/billing/invoices

func CreateMeter 

func CreateMeter(c *gin.Context)

CreateMeter creates a new usage meter definition. 

POST /api/v1/billing/meters

func CreatePaymentIntent added in v1.34.0 

func CreatePaymentIntent(c *gin.Context)

CreatePaymentIntent creates a new payment intent. 

POST /api/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 /api/v1/billing/payment-methods

func CreatePayout added in v1.34.0 

func CreatePayout(c *gin.Context)

CreatePayout creates a new outbound payout. 

POST /api/v1/billing/payouts

func CreatePricingRule 

func CreatePricingRule(c *gin.Context)

CreatePricingRule creates a new pricing rule for a meter. 

POST /api/v1/billing/pricing-rules

func CreateRefund added in v1.34.0 

func CreateRefund(c *gin.Context)

CreateRefund creates a full or partial refund. 

POST /api/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 /api/v1/billing/setup-intents

func CreateSubscriptionItem added in v1.34.0 

func CreateSubscriptionItem(c *gin.Context)

CreateSubscriptionItem adds an item to a subscription. 

POST /api/v1/billing/subscription-items

func CreateSubscriptionSchedule added in v1.34.0 

func CreateSubscriptionSchedule(c *gin.Context)

CreateSubscriptionSchedule creates a new subscription schedule. 

POST /api/v1/billing/subscription-schedules

func CreateWebhookEndpoint added in v1.34.0 

func CreateWebhookEndpoint(c *gin.Context)

CreateWebhookEndpoint registers a new webhook endpoint. 

POST /api/v1/billing/webhook-endpoints

func DeletePricingRule 

func DeletePricingRule(c *gin.Context)

DeletePricingRule removes a pricing rule by ID. 

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

func DeleteSubscriptionItem added in v1.34.0 

func DeleteSubscriptionItem(c *gin.Context)

DeleteSubscriptionItem removes an item from a subscription. 

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

func DeleteWebhookEndpoint added in v1.34.0 

func DeleteWebhookEndpoint(c *gin.Context)

DeleteWebhookEndpoint removes a webhook endpoint. 

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

func Deposit 

func Deposit(c *gin.Context)

Deposit creates a deposit (credit) transaction for an IAM user. 

POST /api/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 /api/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 /api/v1/billing/invoices/:id/finalize

func GetBalance 

func GetBalance(c *gin.Context)

GetBalance returns the current balance for an IAM user. 

GET /api/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 /api/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 /api/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 /api/v1/billing/events/:id

func GetBillingSubscription added in v1.34.0 

func GetBillingSubscription(c *gin.Context)

GetBillingSubscription returns a single subscription. 

GET /api/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 /api/v1/billing/capabilities

func GetCreditBalance 

func GetCreditBalance(c *gin.Context)

GetCreditBalance returns the total available credit balance for a user. 

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

func GetCreditNote added in v1.34.0 

func GetCreditNote(c *gin.Context)

GetCreditNote retrieves a credit note by ID. 

GET /api/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 /api/v1/billing/customer-balance?customerId=...&currency=...

func GetDispute added in v1.34.0 

func GetDispute(c *gin.Context)

GetDispute retrieves a dispute by ID. 

GET /api/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 /api/v1/billing/invoices/:id

func GetMeter 

func GetMeter(c *gin.Context)

GetMeter returns a single meter by ID. 

GET /api/v1/billing/meters/:id

func GetMeterEventsSummary 

func GetMeterEventsSummary(c *gin.Context)

GetMeterEventsSummary returns aggregated usage for a meter+user+period. 

GET /api/v1/billing/meter-events/summary?meterId=...&userId=...&periodStart=...&periodEnd=...

func GetPaymentIntent added in v1.34.0 

func GetPaymentIntent(c *gin.Context)

GetPaymentIntent retrieves a payment intent by ID. 

GET /api/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 /api/v1/billing/payment-methods/:id

func GetPayout added in v1.34.0 

func GetPayout(c *gin.Context)

GetPayout retrieves a payout by ID. 

GET /api/v1/billing/payouts/:id

func GetRefund added in v1.34.0 

func GetRefund(c *gin.Context)

GetRefund retrieves a refund by ID. 

GET /api/v1/billing/refunds/:id

func GetSetupIntent added in v1.34.0 

func GetSetupIntent(c *gin.Context)

GetSetupIntent retrieves a setup intent by ID. 

GET /api/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 /api/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 /api/v1/billing/subscription-schedules/:id

func GetUsage 

func GetUsage(c *gin.Context)

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

GET /api/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 /api/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. 

POST /api/v1/billing/credit

func InvoicePreview 

func InvoicePreview(c *gin.Context)

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

POST /api/v1/billing/invoice-preview

func ListBalanceTransactions added in v1.34.0 

func ListBalanceTransactions(c *gin.Context)

ListBalanceTransactions lists balance transactions for a customer. 

GET /api/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 /api/v1/billing/bank-transfer-instructions?customerId=...

func ListBillingEvents added in v1.34.0 

func ListBillingEvents(c *gin.Context)

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

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

func ListBillingSubscriptions added in v1.34.0 

func ListBillingSubscriptions(c *gin.Context)

ListBillingSubscriptions lists subscriptions for a user. 

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

func ListCreditGrants 

func ListCreditGrants(c *gin.Context)

ListCreditGrants lists credit grants for a user. 

GET /api/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 /api/v1/billing/credit-notes?invoiceId=...&customerId=...

func ListDisputes added in v1.34.0 

func ListDisputes(c *gin.Context)

ListDisputes lists disputes. 

GET /api/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 /api/v1/billing/invoices?userId=...&status=...

func ListMeters 

func ListMeters(c *gin.Context)

ListMeters returns all meters for the organization. 

GET /api/v1/billing/meters

func ListPaymentIntents added in v1.34.0 

func ListPaymentIntents(c *gin.Context)

ListPaymentIntents lists payment intents, optionally filtered by customerId. 

GET /api/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 /api/v1/billing/payment-methods?customerId=...&type=...

func ListPayouts added in v1.34.0 

func ListPayouts(c *gin.Context)

ListPayouts lists payouts. 

GET /api/v1/billing/payouts

func ListPricingRules 

func ListPricingRules(c *gin.Context)

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

GET /api/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 /api/v1/billing/refunds?paymentIntentId=...&invoiceId=...

func ListSubscriptionItems added in v1.34.0 

func ListSubscriptionItems(c *gin.Context)

ListSubscriptionItems lists items for a subscription. 

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

func ListSubscriptionSchedules added in v1.34.0 

func ListSubscriptionSchedules(c *gin.Context)

ListSubscriptionSchedules lists subscription schedules. 

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

func ListWebhookEndpoints added in v1.34.0 

func ListWebhookEndpoints(c *gin.Context)

ListWebhookEndpoints lists all webhook endpoints. 

GET /api/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 /api/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 /api/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 /api/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 /api/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 /api/v1/billing/portal/subscriptions?customerId=...

func ReactivateBillingSubscription added in v1.34.0 

func ReactivateBillingSubscription(c *gin.Context)

ReactivateBillingSubscription reactivates a canceled subscription. 

POST /api/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 /api/v1/billing/bank-transfer-instructions/reconciliation/match

func RecordMeterEvents 

func RecordMeterEvents(c *gin.Context)

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

POST /api/v1/billing/meter-events

func RecordUsage 

func RecordUsage(c *gin.Context)

RecordUsage records an API usage event as a Withdraw transaction. 

POST /api/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 /api/v1/billing/refund

func ReleaseSubscriptionSchedule added in v1.34.0 

func ReleaseSubscriptionSchedule(c *gin.Context)

ReleaseSubscriptionSchedule releases a subscription schedule. 

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

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 /api/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 /api/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 SetDefaultPaymentMethod added in v1.34.0 

func SetDefaultPaymentMethod(c *gin.Context)

SetDefaultPaymentMethod sets the default payment method for a customer. 

POST /api/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 /api/v1/billing/disputes/:id

func UpcomingInvoice added in v1.34.0 

func UpcomingInvoice(c *gin.Context)

UpcomingInvoice generates a preview of the next invoice for a subscription. 

GET /api/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 /api/v1/billing/subscriptions/:id

func UpdatePaymentMethod added in v1.34.0 

func UpdatePaymentMethod(c *gin.Context)

UpdatePaymentMethod updates a payment method. 

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

func UpdateSubscriptionItem added in v1.34.0 

func UpdateSubscriptionItem(c *gin.Context)

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

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

func UpdateSubscriptionSchedule added in v1.34.0 

func UpdateSubscriptionSchedule(c *gin.Context)

UpdateSubscriptionSchedule updates phases or end behavior. 

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

func UpdateWebhookEndpoint added in v1.34.0 

func UpdateWebhookEndpoint(c *gin.Context)

UpdateWebhookEndpoint updates a webhook endpoint configuration. 

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

func VoidCreditGrant 

func VoidCreditGrant(c *gin.Context)

VoidCreditGrant voids a specific credit grant, making it unusable. 

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

func VoidCreditNote added in v1.34.0 

func VoidCreditNote(c *gin.Context)

VoidCreditNote voids a credit note. 

POST /api/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 /api/v1/billing/invoices/:id/void

func ZapDispatch 

func ZapDispatch(c *gin.Context)

ZapDispatch is the single ZAP-over-HTTP endpoint for billing.

Types

This section is empty.

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.