Skip to main content

​
Installation

Install the FlexPrice Go SDK using go get: 
go get github.com/flexprice/flexprice-go/v2
Requirements:
  • Go 1.20 or higher
  • Go modules enabled

​
Quick Start

Initialize the client and ingest an event: 
package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/flexprice/flexprice-go/v2"
	"github.com/flexprice/flexprice-go/v2/models/types"
	"github.com/joho/godotenv"
)

func main() {
	godotenv.Load()

	apiKey := os.Getenv("FLEXPRICE_API_KEY")
	apiHost := os.Getenv("FLEXPRICE_API_HOST")
	if apiHost == "" {
		apiHost = "https://us.api.flexprice.io/v1"
	}
	if apiKey == "" {
		log.Fatal("Set FLEXPRICE_API_KEY in .env or environment")
	}

	client := flexprice.New(apiHost, flexprice.WithSecurity(apiKey))
	ctx := context.Background()

	customerID := fmt.Sprintf("customer-%d", time.Now().Unix())

	// Ingest an event
	req := types.DtoIngestEventRequest{
		EventName:          "api_request",
		ExternalCustomerID: customerID,
		Properties:         map[string]string{"endpoint": "/api/v1/resource", "method": "POST"},
	}

	resp, err := client.Events.IngestEvent(ctx, req)
	if err != nil {
		log.Fatalf("IngestEvent error: %v", err)
	}

	if resp != nil && resp.RawResponse != nil && resp.RawResponse.StatusCode == 202 {
		fmt.Println("Event ingested successfully (202 Accepted)")
	}
}

​
Initialization

Create a FlexPrice client with your API key: 
import "github.com/flexprice/flexprice-go/v2"

// Basic initialization
client := flexprice.New(
	"https://us.api.flexprice.io/v1",
	flexprice.WithSecurity(os.Getenv("FLEXPRICE_API_KEY")),
)
The base URL must include /v1 and have no trailing slash: https://us.api.flexprice.io/v1

​
Creating a Customer

import "github.com/flexprice/flexprice-go/v2/models/types"

customerReq := types.DtoCreateCustomerRequest{
	ExternalID: "customer-123",
	Email:      "user@example.com",
	Name:       "Example Customer",
}

customer, err := client.Customers.CreateCustomer(ctx, customerReq)
if err != nil {
	log.Fatalf("Failed to create customer: %v", err)
}

fmt.Printf("Created customer: %s\n", customer.ID)

​
Ingesting Events

​
Single Event

req := types.DtoIngestEventRequest{
	EventName:          "api_request",
	ExternalCustomerID: "customer-123",
	Properties: map[string]string{
		"endpoint": "/api/data",
		"method":   "GET",
		"status":   "200",
	},
	Source: "backend_api",
}

resp, err := client.Events.IngestEvent(ctx, req)
if err != nil {
	log.Fatalf("Event ingestion failed: %v", err)
}

​
High-Volume Events (Async Client)

For high-throughput event ingestion, use the async client with automatic batching: 
// Configure async client
asyncConfig := flexprice.DefaultAsyncConfig()
asyncConfig.Debug = true
asyncConfig.BatchSize = 100
asyncConfig.FlushInterval = 5 * time.Second

asyncClient := client.NewAsyncClientWithConfig(asyncConfig)
defer asyncClient.Close() // Flush remaining events

// Simple event ingestion
err := asyncClient.Enqueue(
	"api_request",
	"customer-123",
	map[string]interface{}{
		"path":   "/api/resource",
		"method": "POST",
		"status": 201,
	},
)
if err != nil {
	log.Printf("Enqueue error: %v", err)
}

// Event with full options
err = asyncClient.EnqueueWithOptions(flexprice.EventOptions{
	EventName:          "file_upload",
	ExternalCustomerID: "customer-123",
	Properties: map[string]interface{}{
		"file_size_bytes": 1048576,
		"file_type":       "pdf",
	},
	Source:    "upload_service",
	Timestamp: time.Now().Format(time.RFC3339),
})
The async client batches events and sends them in the background. Always call Close() before your application exits to ensure all events are flushed.

​
Error Handling

resp, err := client.Events.IngestEvent(ctx, req)
if err != nil {
	// Handle SDK or network errors
	log.Printf("Error: %v", err)
	return
}

if resp.RawResponse.StatusCode != 202 {
	// Handle unexpected status codes
	log.Printf("Unexpected status: %d", resp.RawResponse.StatusCode)
}

​
Common Operations

params := types.ListCustomersRequest{
	PageSize: flexprice.Int64(50),
}

customers, err := client.Customers.ListCustomers(ctx, params)
if err != nil {
	log.Fatalf("List customers error: %v", err)
}

for _, customer := range customers.Customers {
	fmt.Printf("Customer: %s (%s)\n", customer.Name, customer.ExternalID)
}

​
Configuration Options

client := flexprice.New(
	"https://us.api.flexprice.io/v1",
	flexprice.WithSecurity(apiKey),
	// Add custom options here
)

// Async client configuration
asyncConfig := flexprice.DefaultAsyncConfig()
asyncConfig.BatchSize = 200          // Events per batch
asyncConfig.FlushInterval = 10 * time.Second  // Max time before flush
asyncConfig.MaxRetries = 3           // Retry failed batches
asyncConfig.Debug = true             // Enable debug logging

asyncClient := client.NewAsyncClientWithConfig(asyncConfig)

​
Best Practices

1

Use environment variables

Store API keys in environment variables, never hardcode them:
apiKey := os.Getenv("FLEXPRICE_API_KEY")
2

Use async client for high volume

For applications ingesting thousands of events per second, use the async client with batching
3

Always call Close()

When using the async client, defer Close() to ensure all events are flushed:
defer asyncClient.Close()
4

Handle context properly

Pass context for cancellation and timeouts:
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

​
Troubleshooting

Ensure FLEXPRICE_API_KEY is set and the key is active. Keys are for server-side use only.
Use https://us.api.flexprice.io/v1 (include /v1, no trailing slash)
Event ingestion returns 202 Accepted. Check:
  • EventName is provided
  • ExternalCustomerID exists
  • Properties is a valid map
Ensure you call asyncClient.Close() before application exit to flush remaining events

​
Next Steps

API Reference

Complete FlexPrice API documentation

Go SDK Examples

Sample code and integration examples

Go Package Docs

Full Go SDK reference on pkg.go.dev