Go SDK

go get github.com/alguna-io/alguna-go

import (
	alguna "github.com/alguna-io/alguna-go"
	"github.com/alguna-io/alguna-go/client"
	"github.com/alguna-io/alguna-go/option"
)

// With no options, the client reads the API key from ALGUNA_API_KEY.
c := client.NewAlguna(
	option.WithAPIVersion("2026-04-01"), // recommended: pin the version you integrate against
)

ctx := context.Background()

// 1. Create a customer
customer, err := c.Customers.Create(ctx, &alguna.CreateCustomerRequest{
	Name:     "Acme Corp",
	Currency: "USD",
	Contacts: []*alguna.ContactRequest{
		{Email: "billing@acme.com", IsPrimary: true},
	},
})
if err != nil {
	return err
}

// 2. Create a product and start a subscription
product, err := c.Products.Create(ctx, &alguna.CreateProductRequest{
	Name:             "Platform Fee",
	FeeType:          alguna.PricingClassFixed,
	BillingFrequency: alguna.BillingFrequencyRecurring.Ptr(),
	PaymentTerms:     alguna.BillingDirectionAdvance,
})
if err != nil {
	return err
}

subscription, err := c.Subscriptions.Create(ctx, &alguna.CreateSubscriptionRequest{
	CustomerID: customer.ID,
	Currency:   alguna.String("USD"),
	Items: []*alguna.CreateSubscriptionItemInput{
		{
			ProductID: alguna.String(product.ID),
			Price: &alguna.PriceInput{
				Type:              alguna.PricingTypeFixed,
				FeeType:           alguna.PricingClassFixed,
				BillingDirection:  alguna.BillingDirectionAdvance,
				BillingFrequency:  alguna.BillingFrequencyRecurring.Ptr(),
				BillingInterval:   alguna.BillingIntervalMonthly.Ptr(),
				FixedPricingModel: &alguna.FixedPricingModelInput{PricePerUnit: "99.00", Units: 1},
			},
		},
	},
	Contract: &alguna.ContractInput{
		PeriodType:     alguna.String("fixed"),
		DurationMonths: alguna.Int64(12),
		StartDate:      alguna.Time(time.Date(2026, 7, 1, 0, 0, 0, 0, time.UTC)),
	},
	AutoActivate: alguna.Bool(true),
})
if err != nil {
	return err
}
fmt.Println(subscription.ID)

// 3. Issue a one-off invoice
invoice, err := c.Invoices.Create(ctx, &alguna.CreateInvoiceRequest{
	CustomerID: alguna.String(customer.ID),
	Currency:   alguna.String("USD"),
	LineItems: []*alguna.CreateInvoiceLineItemRequest{
		{Description: alguna.String("Onboarding"), UnitPrice: "500.00", Quantity: "1"},
	},
})
if err != nil {
	return err
}
fmt.Println(invoice.ID)

// 4. Open a customer portal session so the customer can pay and manage billing
session, err := c.Portal.CreateSession(ctx, &alguna.CreateCustomerPortalSessionRequest{
	CustomerID: alguna.String(customer.ID),
})
if err != nil {
	return err
}
fmt.Println(session.URL) // send the customer here

page, err := c.Customers.List(ctx, &alguna.ListCustomersRequest{Limit: alguna.Int(100)})
if err != nil {
	return err
}
iter := page.Iterator()
for iter.Next(ctx) {
	fmt.Println(iter.Current().ID)
}
if err := iter.Err(); err != nil {
	return err
}

pdf, err := c.Invoices.GeneratePdf(ctx, invoice.ID)
if err != nil {
	return err
}
file, err := os.Create("invoice.pdf")
if err != nil {
	return err
}
defer file.Close()
if _, err := io.Copy(file, pdf); err != nil {
	return err
}

_, err := c.Customers.Get(ctx, "cus_missing")
var notFound *alguna.NotFoundError
var apiErr *core.APIError
switch {
case errors.As(err, &notFound):
	fmt.Println("no such customer:", notFound.Body.Detail)
case errors.As(err, &apiErr):
	fmt.Println(apiErr.StatusCode, apiErr.Header.Get("X-Request-Id"), err)
case err != nil:
	return err
}

created, err := c.Customers.Create(ctx,
	&alguna.CreateCustomerRequest{Name: "Acme Corp", Currency: "USD"},
	option.WithIdempotencyKey(alguna.String("signup-1234")),
)
if err != nil {
	return err
}
fmt.Println(created.ID)

c := client.NewAlguna(option.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}))

// Each attempt may take 10 s; the call, with its retries, at most 25 s.
ctx, cancel := context.WithTimeout(ctx, 25*time.Second)
defer cancel()
customer, err := c.Customers.Get(ctx, "cus_123")
if err != nil {
	return err
}
fmt.Println(customer.ID)

c := client.NewAlguna(
	option.WithAPIKey(os.Getenv("ALGUNA_SANDBOX_API_KEY")),    // default: ALGUNA_API_KEY
	option.WithAPIVersion("2026-04-01"),                       // default: the version this SDK release targets
	option.WithBaseURL("https://api.sandbox.alguna.io"),       // default: https://api.alguna.io
	option.WithHTTPHeader(http.Header{"X-Trace-Id": {"abc"}}), // sent on every request
	option.WithMaxAttempts(3),                                 // see Idempotency and retries
)