Initialize the Go SDK

The Go SDK lives in the repository module at github.com/meterry-com/meterry-go/pkg/sdk. It is intended for trusted server-side services such as API gateways, agent runtimes, workflow engines, and backend jobs.

Use the SDK to:

• ingest raw usage events into extractor rule sets;
• manage extractor rules, pricing rules, accounts, wallets, vouchers, subject routes, and usage-control rules;
• query usage events, usage details, aggregate usage, and chart-ready series;
• verify Meterry webhook signatures.

Install

go get github.com/meterry-com/meterry-go

Import the SDK and shared request/response types:

import (
  "github.com/meterry-com/meterry-go/pkg/sdk"
  "github.com/meterry-com/meterry-go/pkg/types"
)

The SDK uses github.com/shopspring/decimal for money-sensitive values such as wallet credits, debits, voucher amounts, and credit limits.

Create a Client

Create a client with the Meterry base URL and a server-side API key.

client, err := sdk.NewClient(sdk.Config{
  BaseURL: "http://127.0.0.1:8080",
  APIKey:  "<api-key>",
})
if err != nil {
  return err
}

sdk.MustNewClient is available for startup code that should fail fast on invalid configuration.

client := sdk.MustNewClient(sdk.Config{
  BaseURL: "https://billing.example.com",
  APIKey:  os.Getenv("BILLING_API_KEY"),
})

Configuration

Field	Description
BaseURL	Required. Meterry API origin, including scheme and host.
APIKey	Optional in the type, but required for authenticated API calls. Sent as Authorization: Bearer <api-key>.
TenantID	Enables admin/service-key paths under /admin/v1/tenants/:tenant_id. Use this for tenant-scoped management operations with a service key.
HTTPClient	Custom *http.Client. Defaults to a 10-second timeout.
UserAgent	Custom user agent. Defaults to edgefn-billing-go-sdk.

Path Modes

Most application integrations should pass projectID to project-scoped methods such as usage ingest and project usage queries.

When TenantID is set, Manager and tenant-scoped query calls use admin paths:

client := sdk.MustNewClient(sdk.Config{
  BaseURL:  "https://billing.example.com",
  APIKey:   os.Getenv("BILLING_SERVICE_KEY"),
  TenantID: "tenant_001",
})

For service-key ingest, pass a projectID; the SDK requires it when TenantID is configured so usage is written into the correct project boundary.

Client Areas

The root client exposes three API clients:

Client	Purpose
client.Ingest	Submit usage events to extractor rule sets.
client.Manager	Manage rules, accounts, wallets, vouchers, subject routes, and usage controls.
client.Query	Query analytics, usage events, usage details, and chart series.

Webhook verification is exposed as package-level helpers such as sdk.VerifyWebhookRequest.

Error Handling

Non-2xx API responses are returned as *sdk.APIError.

if err != nil {
  var apiErr *sdk.APIError
  if errors.As(err, &apiErr) {
    log.Printf("billing API status=%d message=%s body=%s", apiErr.StatusCode, apiErr.Message, apiErr.Body)
    return err
  }
  return err
}