Meteroid Go SDK

The official Go SDK for Meteroid, the open-source billing and pricing platform. Meteroid manages subscriptions, usage-based billing and metering, invoicing and revenue analytics; this library calls its REST API and verifies its webhooks, against Meteroid Cloud (https://api.meteroid.com) or a self-hosted instance.

Website · Documentation · API reference · Meteroid on GitHub

Requires Go 1.23 or later.

go get github.com/meteroid-oss/meteroid-go

Every method of the API is listed in api.md.

Usage

import meteroid "github.com/meteroid-oss/meteroid-go"

client := meteroid.New("your-api-key", nil)

addOn, err := client.AddOns().Retrieve(ctx, "addon_id")
if err != nil {
	return err
}
fmt.Println(addOn)

Every API area hangs off the client as an accessor method, and every method takes a context.Context first. Required parameters are arguments; optional ones go in an options struct whose fields are pointers (meteroid.Ptr(v)), nil to send none. Request bodies are structs of the package:

onboardingLinkResponse, err := client.Connect().CreateOnboardingLink(ctx, "id", meteroid.CreateOnboardingLinkRequest{RedirectURL: "redirect_url"})

Models keep the properties this SDK version does not know in ExtraFields, and send them back.

Environment

New("", nil) reads the token from METEROID_API_KEY, and METEROID_BASE_URL overrides the default server. Explicit arguments win: meteroid.New(token, &meteroid.Options{ServerURL: "https://..."}). The default server, meteroid.DefaultServerURL, is https://api.meteroid.com.

Errors

Every error is a meteroid.SDKError. A non-2xx response is an *meteroid.APIError, whose Body is the error body decoded as the schema the operation declares (else plain JSON); a timeout is a *TimeoutError, a failed connection a *TransportError, an undecodable response a *DecodeError:

_, err := client.AddOns().Retrieve(ctx, "addon_id")
var apiErr *meteroid.APIError
switch {
case errors.Is(err, meteroid.ErrNotFound):
	// ...
case errors.As(err, &apiErr):
	log.Printf("status %d, request %s", apiErr.StatusCode, apiErr.RequestID())
}

Pagination

A list method returns its first page, a *meteroid.AddOnsListPage. The page embeds the decoded AddOnListResponse response, so its fields read directly on the page, and holds its Items; HasNextPage() and NextPage(ctx) step to the next page, nil after the last one. A response field named like one of these members stays reachable through the embedded response, page.AddOnListResponse:

page, err := client.AddOns().List(ctx, nil)
for page != nil && err == nil {
	// page.PaginationMeta.TotalPages, page.Items, page.HasNextPage()
	page, err = page.NextPage(ctx)
}

Its ...AutoPaging twin returns an *AutoPager[T] over every item, fetching further pages on demand:

for addOn, err := range client.AddOns().ListAutoPaging(ctx, nil).All() {
	if err != nil {
		return err
	}
	fmt.Println(addOn)
}

Without range, loop on the pager's Next(), read Current(), then check Err().

Raw responses

WithResponseInto gives the *http.Response of a call, for its status and headers:

var resp *http.Response
addOn, err := client.AddOns().Retrieve(ctx, "addon_id", meteroid.WithResponseInto(&resp))
log.Print(resp.Header.Get("X-Request-Id"))

Retries and timeouts

Connection errors, timeouts, 408, 429 and 5xx responses are retried twice with jittered backoff, honoring Retry-After and retry-after-ms, when the request is idempotent or carries an Idempotency-Key. Each attempt times out after DefaultTimeout. Options sets them for the client (MaxRetries, Timeout), and request options for one call: meteroid.WithMaxRetries(0), meteroid.WithTimeout(time.Minute), meteroid.WithIdempotencyKey(key), meteroid.WithHeader(name, value). Options.Logger logs every attempt at debug level.

addOn, err := client.AddOns().Retrieve(ctx, "addon_id", meteroid.WithMaxRetries(0), meteroid.WithTimeout(5*time.Second))

• Source: https://github.com/meteroid-oss/meteroid-go
• License: Apache-2.0

Generated by perseid.