### Basic Production Setup

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Example of initializing the Paddle client for production.

```go
import (
    "os"
    paddle "github.com/PaddleHQ/paddle-go-sdk/v5"
)

func main() {
    client, err := paddle.New(os.Getenv("PADDLE_API_KEY"))
    if err != nil {
        panic(err)
    }
    
    // Use client
}
```

--------------------------------

### New() example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Example of initializing the SDK for the production environment.

```go
import (
    paddle "github.com/PaddleHQ/paddle-go-sdk/v5"
)

client, err := paddle.New(
    os.Getenv("PADDLE_API_KEY"),
    paddle.WithBaseURL(paddle.ProductionBaseURL),
)
if err != nil {
    log.Fatalf("Failed to initialize SDK: %v", err)
}
```

--------------------------------

### NewSandbox() example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Example of initializing the SDK for the sandbox environment.

```go
client, err := paddle.NewSandbox(
    os.Getenv("PADDLE_SANDBOX_API_KEY"),
)
if err != nil {
    log.Fatalf("Failed to initialize sandbox SDK: %v", err)
}
```

--------------------------------

### Sandbox Development Setup

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Example of initializing the Paddle client for sandbox development.

```go
func main() {
    client, err := paddle.NewSandbox(os.Getenv("PADDLE_SANDBOX_API_KEY"))
    if err != nil {
        panic(err)
    }
}
```

--------------------------------

### Overview Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Example of initializing the Paddle SDK with functional options.

```Go
client, err := paddle.New(
    apiKey,
    paddle.WithBaseURL(paddle.SandboxBaseURL),
    paddle.WithClient(customHTTPClient),
)
```

--------------------------------

### WithClient() example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Example of using WithClient() to set a custom HTTP client.

```go
customHTTPClient := &http.Client{
    Timeout: 30 * time.Second,
}

client, err := paddle.New(
    apiKey,
    paddle.WithClient(customHTTPClient),
)
```

--------------------------------

### Complete Initialization Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

An example demonstrating how to initialize the SDK for production and use its client to list products.

```go
package main

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

    paddle "github.com/PaddleHQ/paddle-go-sdk/v5"
)

func main() {
    // Initialize for production
    client, err := paddle.New(
        os.Getenv("PADDLE_API_KEY"),
        paddle.WithBaseURL(paddle.ProductionBaseURL),
    )
    if err != nil {
        log.Fatalf("Failed to initialize SDK: %v", err)
    }

    // Use the client
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    products, err := client.ListProducts(ctx, &paddle.ListProductsRequest{})
    if err != nil {
        log.Fatalf("Failed to list products: %v", err)
    }

    // Iterate through results
    err = products.Iter(ctx, func(p *paddle.Product) (bool, error) {
        log.Printf("Product: %s", p.ID)
        return true, nil
    })
}
```

--------------------------------

### Base URLs usage example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Examples of using base URLs with New().

```go
// Explicitly set production (redundant with New())
client, err := paddle.New(apiKey, paddle.WithBaseURL(paddle.ProductionBaseURL))

// Switch to sandbox
client, err := paddle.New(apiKey, paddle.WithBaseURL(paddle.SandboxBaseURL))
```

--------------------------------

### WithBaseURL() example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Example of using WithBaseURL() to set the sandbox base URL.

```go
client, err := paddle.New(apiKey, paddle.WithBaseURL(paddle.SandboxBaseURL))
```

--------------------------------

### WithAPIKey() example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Example of using WithAPIKey() to set the API key.

```go
client, err := paddle.New(
    "your_api_key",
    paddle.WithAPIKey("another_api_key"), // Overrides first argument
)
```

--------------------------------

### Install Paddle Go SDK

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/README.md

Command to install the Paddle Go SDK using go get.

```bash
go get github.com/PaddleHQ/paddle-go-sdk
```

--------------------------------

### GetCustomerAuthToken Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/customers-client.md

Example of how to generate an authentication token for a customer.

```go
authToken, err := client.GetCustomerAuthToken(ctx, &paddle.GetCustomerAuthTokenRequest{
    CustomerID: "ctm_123",
})
if err != nil {
    log.Fatal(err)
}
log.Printf("Token: %s, Expires: %s", authToken.CustomerAuthToken, authToken.ExpiresAt)
```

--------------------------------

### WithClient Example (With Proxy)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Setting a custom HTTP client with a proxy.

```Go
// With proxy
proxyURL, _ := url.Parse("http://proxy.example.com:8080")
transport := &http.Transport{
    Proxy: http.ProxyURL(proxyURL),
}
customClient := &http.Client{
    Transport: transport,
}
client, err := paddle.New(apiKey, paddle.WithClient(customClient))
```

--------------------------------

### CreateCustomer Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/customers-client.md

Creates a new customer.

```go
customer, err := client.CreateCustomer(ctx, &paddle.CreateCustomerRequest{
    Email: "newcustomer@example.com",
    Name:  paddle.String("John Doe"),
    CustomData: paddle.CustomData{
        "account_type": "premium",
    },
})
if err != nil {
    log.Fatal(err)
}
log.Printf("Created customer: %s", customer.ID)
```

--------------------------------

### ListCreditBalances Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/customers-client.md

Example of how to list credit balances for a customer, filtering by currency codes, and iterating through the results.

```go
balances, err := client.ListCreditBalances(ctx, &paddle.ListCreditBalancesRequest{
    CustomerID: "ctm_123",
    CurrencyCode: []string{"USD", "EUR"},
})
if err != nil {
    log.Fatal(err)
}

err = balances.Iter(ctx, func(cb *paddle.CreditBalance) (bool, error) {
    log.Printf("Currency: %s, Available: %s", cb.CurrencyCode, cb.Balance.Available)
    return true, nil
})
```

--------------------------------

### WithBaseURL Example (Production)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Setting the base URL to the production environment.

```Go
// Production (default)
client, err := paddle.New(apiKey, paddle.WithBaseURL(paddle.ProductionBaseURL))
```

--------------------------------

### WithBaseURL Example (Sandbox)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Setting the base URL to the sandbox environment.

```Go
// Sandbox
client, err := paddle.New(apiKey, paddle.WithBaseURL(paddle.SandboxBaseURL))
```

--------------------------------

### GetPrice Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/prices-client.md

Example usage of the GetPrice method to retrieve a price and its associated product.

```go
price, err := client.GetPrice(ctx, &paddle.GetPriceRequest{
    PriceID:        "pri_123",
    IncludeProduct: true,
})
if err != nil {
    log.Fatal(err)
}
log.Printf("Price: %s, Product: %s", price.ID, price.Product.Name)
```

--------------------------------

### CreateProduct() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/products-client.md

Creates a new product in your catalog.

```go
product, err := client.CreateProduct(ctx, &paddle.CreateProductRequest{
    Name:        "Starter Plan",
    TaxCategory: paddle.TaxCategoryStandard,
    Description: paddle.String("Basic subscription plan"),
    ImageURL:    paddle.String("https://example.com/image.png"),
    CustomData: paddle.CustomData{
        "tier": "basic",
    },
})
if err != nil {
    log.Fatal(err)
}
log.Printf("Created product: %s", product.ID)
```

--------------------------------

### Get a Resource

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/README.md

Example of retrieving a specific product by its ID.

```go
product, err := client.GetProduct(ctx, &paddle.GetProductRequest{
    ProductID: "pro_123",
})
```

--------------------------------

### Res.Value() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

An example demonstrating how to retrieve the item value using Res.Value().

```go
res := collection.Next(ctx)
if res.Ok() {
    product := res.Value()
    log.Printf("Product: %s", product.Name)
}
```

--------------------------------

### Get an entity

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/README.md

Example of retrieving a specific product using the GetProduct function.

```go
product, err := client.GetProduct(ctx, &paddle.GetProductRequest{
    ProductID: productID, 
    IncludePrices: true
})
if err != nil {
    panic(err)
}
fmt.Printf("%+v\n", product)
```

--------------------------------

### WithBaseURL Example (Custom)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Setting a custom base URL for testing.

```Go
// Custom (for testing)
client, err := paddle.New(apiKey, paddle.WithBaseURL("http://localhost:8080"))
```

--------------------------------

### Res.Ok() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

An example demonstrating the use of Res.Ok() to check for the end of a collection during iteration.

```go
for {
    res := collection.Next(ctx)
    if !res.Ok() {
        break // End of collection
    }
    item := res.Value()
}
```

--------------------------------

### IterErr Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

An example demonstrating how to use IterErr to iterate through customers and process each one, stopping on error.

```go
err = customers.IterErr(ctx, func(c *paddle.Customer) error {
    log.Printf("Customer: %s", c.Email)
    
    // Process customer
    if err := processCustomer(c); err != nil {
        return err // Stop on error
    }
    
    return nil // Continue
})
if err != nil {
    return err
}
```

--------------------------------

### Update Product Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/products-client.md

An example of how to use the UpdateProduct method to partially update a product's name, description, and status.

```go
product, err := client.UpdateProduct(ctx, &paddle.UpdateProductRequest{
    ProductID: "pro_123",
    Name: paddle.NewPatchField("Updated Product Name"),
    Description: paddle.NewPatchField(paddle.String("New description")),
    Status: paddle.NewPatchField(paddle.Status("archived")),
})
if err != nil {
    log.Fatal(err)
}
log.Printf("Updated product: %s", product.ID)
```

--------------------------------

### Complete Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

This example shows three methods for iterating through collections: using `Iter` for simple iteration, `IterErr` for early exit with error handling, and manual iteration with `Next`.

```go
package main

import (
    "context"
    "log"
    "os"
    "time"
    
    paddle "github.com/PaddleHQ/paddle-go-sdk/v5"
)

func main() {
    client, err := paddle.New(os.Getenv("PADDLE_API_KEY"))
    if err != nil {
        log.Fatal(err)
    }
    
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    
    // Method 1: Using Iter with manual continue/stop logic
    products, err := client.ListProducts(ctx, &paddle.ListProductsRequest{
        PerPage: paddle.Int(25),
    })
    if err != nil {
        log.Fatal(err)
    }
    
    err = products.Iter(ctx, func(p *paddle.Product) (bool, error) {
        log.Printf("Product: %s ($%s)", p.Name, p.ID)
        return true, nil // Continue to next
    })
    if err != nil {
        log.Fatal(err)
    }
    
    // Method 2: Using IterErr with early exit
    customers, err := client.ListCustomers(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    
    targetEmail := "user@example.com"
    err = customers.IterErr(ctx, func(c *paddle.Customer) error {
        if c.Email == targetEmail {
            log.Printf("Found customer: %s", c.ID)
            return paddle.ErrStopIteration
        }
        return nil
    })
    if err != nil {
        log.Fatal(err)
    }
    
    // Method 3: Manual iteration with Next
    prices, err := client.ListPrices(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    
    count := 0
    for {
        res := prices.Next(ctx)
        if !res.Ok() {
            if err := res.Err(); err != nil {
                log.Fatal(err)
            }
            break
        }
        
        price := res.Value()
        log.Printf("Price: %s (%s %s)", price.ID, price.UnitPrice.Amount, price.UnitPrice.CurrencyCode)
        count++
    }
    
    log.Printf("Total prices: %d", count)
}
```

--------------------------------

### Usage of Base URL Constants

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Examples demonstrating how to use base URL constants when creating a client.

```go
// Explicit production
client, err := paddle.New(apiKey, paddle.WithBaseURL(paddle.ProductionBaseURL))

// Explicit sandbox
client, err := paddle.New(apiKey, paddle.WithBaseURL(paddle.SandboxBaseURL))

// Implicit based on constructor
client, err := paddle.New(apiKey)                    // 
client, err := paddle.NewSandbox(apiKey)            // 
```

--------------------------------

### Money Struct Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/types.md

Example of creating a Money struct.

```go
price := Money{
    Amount:       "2999",
    CurrencyCode: paddle.CurrencyCodeUSD,
}
```

--------------------------------

### UpdateCustomer Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/customers-client.md

Example of how to update a customer's name and locale using the UpdateCustomer method.

```go
customer, err := client.UpdateCustomer(ctx, &paddle.UpdateCustomerRequest{
    CustomerID: "ctm_123",
    Name: paddle.NewPatchField("Jane Doe"),
    Locale: paddle.NewPatchField("en-GB"),
})
if err != nil {
    log.Fatal(err)
}
log.Printf("Updated customer: %s", customer.Name)
```

--------------------------------

### ListCustomers Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/customers-client.md

Lists all customers with optional filtering and pagination.

```go
customers, err := client.ListCustomers(ctx, &paddle.ListCustomersRequest{
    Email:   []string{"user@example.com"},
    PerPage: paddle.Int(25),
})
if err != nil {
    log.Fatal(err)
}

err = customers.Iter(ctx, func(c *paddle.Customer) (bool, error) {
    log.Printf("Customer: %s - %s", c.ID, c.Email)
    return true, nil
})
```

--------------------------------

### SDK Initialization - Production Setup

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Initializes the Paddle client for production using an API key.

```go
client, err := paddle.New(os.Getenv("PADDLE_API_KEY"))
```

--------------------------------

### WithClient Example (Custom Timeout)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Setting a custom HTTP client with a timeout.

```Go
// Custom timeout
customClient := &http.Client{
    Timeout: 30 * time.Second,
}
client, err := paddle.New(apiKey, paddle.WithClient(customClient))
```

--------------------------------

### WithAPIKey Example (Primary Method)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Setting the API key as the first argument to New().

```Go
// Primary method - pass as first argument
client, err := paddle.New(os.Getenv("PADDLE_API_KEY"))
```

--------------------------------

### Testing with Mock Client

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Example of using a mock HTTP client for testing purposes.

```go
import "testing"

func TestWithMockClient(t *testing.T) {
    mockClient := &MockHTTPClient{
        // Configure mock responses
    }
    
    client, err := paddle.New(
        "test_key",
        paddle.WithBaseURL("http://localhost:9999"),
        paddle.WithClient(mockClient),
    )
    if err != nil {
        t.Fatal(err)
    }
    
    // Test with mock client
}
```

--------------------------------

### WithClient Example (With Custom Headers)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Setting a custom HTTP client with custom headers using a middleware wrapper.

```Go
// With custom headers (using middleware wrapper)
type HeaderRoundTripper struct {
    rt http.RoundTripper
}

func (h *HeaderRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
    req.Header.Set("X-Custom-Header", "value")
    return h.rt.RoundTrip(req)
}

transport := &http.Transport{}
client := &http.Client{
    Transport: &HeaderRoundTripper{rt: transport},
}
sdkClient, err := paddle.New(apiKey, paddle.WithClient(client))
```

--------------------------------

### SDK Initialization - Sandbox Setup

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Initializes the Paddle client for sandbox environment using a sandbox API key.

```go
client, err := paddle.NewSandbox(os.Getenv("PADDLE_SANDBOX_API_KEY"))
```

--------------------------------

### Create Resources

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/README.md

Example of creating a new product resource.

```go
product, err := client.CreateProduct(ctx, &paddle.CreateProductRequest{
    Name:        "My Product",
    TaxCategory: paddle.TaxCategoryStandard,
})
```

--------------------------------

### WithAPIKey Example (Alternative)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Setting the API key using the WithAPIKey option.

```Go
// Alternative - use option
client, err := paddle.New(
    "default_key",
    paddle.WithAPIKey(os.Getenv("PADDLE_API_KEY")),
)
```

--------------------------------

### UpdatePrice Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/prices-client.md

Example usage of the UpdatePrice method to update a price's name, description, and status.

```go
price, err := client.UpdatePrice(ctx, &paddle.UpdatePriceRequest{
    PriceID:     "pri_123",
    Name:        paddle.NewPatchField("Annual Plan"),
    Description: paddle.NewPatchField("Yearly subscription"),
    Status:      paddle.NewPatchField(paddle.StatusArchived),
})
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Complete Webhook Handler Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/webhook-verifier.md

A complete example demonstrating how to set up a webhook handler using the Paddle Go SDK, including signature verification, timestamp tolerance, JSON unmarshalling, and asynchronous processing.

```go
package main

import (
    "context"
    "encoding/json"
    "io"
    "log"
    "net/http"
    "os"
    "time"

    paddle "github.com/PaddleHQ/paddle-go-sdk/v5"
)

func main() {
    verifier := paddle.NewWebhookVerifier(
        os.Getenv("WEBHOOK_SECRET_KEY"),
        paddle.VerifierWithTimestampTolerance(5 * time.Minute),
    )

    handler := verifier.Middleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Read body
        body, _ := io.ReadAll(r.Body)
        defer r.Body.Close()

        // Unmarshal notification
        var notification paddle.Notification
        if err := json.Unmarshal(body, &notification); err != nil {
            http.Error(w, "Invalid JSON", http.StatusBadRequest)
            return
        }

        // Check if already processed (idempotency)
        if isProcessed(notification.ID) {
            w.WriteHeader(http.StatusOK)
            return
        }

        // Process notification
        log.Printf("Processing event: %s", notification.Type)

        // Store notification for processing
        storeForProcessing(notification)

        // Respond immediately
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusOK)
        w.Write([]byte(`{"success": true}`))
    }))

    http.Handle("/webhooks", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

func isProcessed(id string) bool {
    // Check if notification has been processed
    return false
}

func storeForProcessing(n paddle.Notification) {
    // Store for async processing
}
```

--------------------------------

### Duration Struct Examples

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/types.md

Examples of creating Duration structs for monthly and biannual billing.

```go
monthly := &Duration{
    Interval:  "month",
    Frequency: 1,
}

biannual := &Duration{
    Interval:  "year",
    Frequency: 2,
}
```

--------------------------------

### ListProducts() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/products-client.md

Lists all products, optionally filtering by status, tax category, or type. Returns a paginated collection.

```go
products, err := client.ListProducts(ctx, &paddle.ListProductsRequest{
    PerPage:        paddle.Int(10),
    IncludePrices:  true,
    Status:         []string{"active"},
})
if err != nil {
    log.Fatal(err)
}

// Iterate through products
err = products.Iter(ctx, func(p *paddle.Product) (bool, error) {
    log.Printf("Product: %s - %s", p.ID, p.Name)
    return true, nil
})
```

--------------------------------

### GetProduct() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/products-client.md

Retrieves a single product by ID.

```go
product, err := client.GetProduct(ctx, &paddle.GetProductRequest{
    ProductID:    "pro_123",
    IncludePrices: true,
})
if err != nil {
    log.Fatal(err)
}
log.Printf("Product: %s with %d prices", product.ID, len(product.Prices))
```

--------------------------------

### ErrStopIteration Usage Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

An example demonstrating the usage of ErrStopIteration with IterErr to break out of iteration cleanly.

```go
err = collection.IterErr(ctx, func(item T) error {
    if shouldStop(item) {
        return paddle.ErrStopIteration
    }
    return nil
})
// err is nil (not an error)
```

--------------------------------

### IterErr Stop Gracefully Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

An example showing how to use IterErr to stop iteration gracefully by returning ErrStopIteration.

```go
err = customers.IterErr(ctx, func(c *paddle.Customer) error {
    if c.Email == "target@example.com" {
        log.Printf("Found: %s", c.ID)
        return paddle.ErrStopIteration // Graceful stop
    }
    return nil // Continue
})
// err will be nil (ErrStopIteration is converted to success)
```

--------------------------------

### Initialize Paddle Client

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/README.md

Example of initializing a new Paddle client with an API key.

```go
import (
    paddle "github.com/PaddleHQ/paddle-go-sdk/v5"
)

client, err := paddle.New(
    os.Getenv("PADDLE_API_KEY"),
    paddle.WithBaseURL(paddle.ProductionBaseURL),
)
```

--------------------------------

### Custom HTTP Configuration

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Example of configuring a custom HTTP client with specific settings.

```go
import (
    "net/http"
    "time"
)

func main() {
    httpClient := &http.Client{
        Timeout: 30 * time.Second,
        Transport: &http.Transport{
            MaxIdleConns:        100,
            MaxIdleConnsPerHost: 10,
            IdleConnTimeout:     90 * time.Second,
        },
    }
    
    client, err := paddle.New(
        os.Getenv("PADDLE_API_KEY"),
        paddle.WithClient(httpClient),
    )
    if err != nil {
        panic(err)
    }
}
```

--------------------------------

### Environment-Specific Setup

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Function to create a Paddle client based on the specified environment (production, sandbox, test).

```go
import "os"

func createPaddleClient(env string) (*paddle.SDK, error) {
    var apiKey, baseURL string
    
    switch env {
    case "production":
        apiKey = os.Getenv("PADDLE_API_KEY")
        baseURL = paddle.ProductionBaseURL
    case "sandbox":
        apiKey = os.Getenv("PADDLE_SANDBOX_API_KEY")
        baseURL = paddle.SandboxBaseURL
    case "test":
        apiKey = "test_key"
        baseURL = "http://localhost:8080"
    default:
        return nil, errors.New("unknown environment")
    }
    
    return paddle.New(
        apiKey,
        paddle.WithBaseURL(baseURL),
    )
}
```

--------------------------------

### Discount Types

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Examples of common discount type constants.

```go
paddle.DiscountTypePercentage    // "percentage"
paddle.DiscountTypeFlat          // "flat"
paddle.DiscountTypeFlatPerSeat   // "flat_per_seat"
```

--------------------------------

### GetCustomer Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/customers-client.md

Retrieves a single customer by ID.

```go
customer, err := client.GetCustomer(ctx, &paddle.GetCustomerRequest{
    CustomerID: "ctm_123",
})
if err != nil {
    log.Fatal(err)
}
log.Printf("Customer: %s", customer.Email)
```

--------------------------------

### Collection Modes

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Examples of common collection mode constants.

```go
paddle.CollectionModeAutomatic  // "automatic"
paddle.CollectionModeManual     // "manual"
```

--------------------------------

### VerifierWithTimestampTolerance Example Usage

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/webhook-verifier.md

Example demonstrating how to use VerifierWithTimestampTolerance to allow up to 5 minutes of clock skew.

```go
// Allow up to 5 minutes of clock skew
verifier := paddle.NewWebhookVerifier(
    secretKey,
    paddle.VerifierWithTimestampTolerance(5 * time.Minute),
)

ok, err := verifier.Verify(req)
if errors.Is(err, paddle.ErrReplayAttack) {
    log.Println("Webhook timestamp too old or far in future")
    return
}
```

--------------------------------

### Rate Limiting Handling

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Example of how to handle rate-limited responses (HTTP 429) by implementing exponential backoff.

```go
import (
    "errors"
    "time"
    paddle "github.com/PaddleHQ/paddle-go-sdk/v5"
)

for attempt := 0; attempt < 3; attempt++ {
    result, err := client.ListProducts(ctx, req)
    
    if errors.Is(err, paddle.ErrTooManyRequests) {
        // Implement exponential backoff
        backoff := time.Duration(math.Pow(2, float64(attempt))) * time.Second
        time.Sleep(backoff)
        continue
    }
    
    if err != nil {
        return nil, err
    }
    
    return result, nil
}
```

--------------------------------

### Currency Codes

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Examples of common currency code constants.

```go
paddle.CurrencyCodeUSD  // "USD"
paddle.CurrencyCodeEUR  // "EUR"
paddle.CurrencyCodeGBP  // "GBP"
// ... and many more
```

--------------------------------

### PtrTo Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/types.md

Shows how to use the PtrTo function to create pointers for optional fields.

```go
description := paddle.PtrTo("Product description")
name := paddle.PtrTo("Product Name")
```

--------------------------------

### List all entities

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/README.md

Example of listing products using the ListProducts function and iterating through the results.

```go
products, err := client.ListProducts(ctx, &paddle.ListProductsRequest{IncludePrices: true})
if err != nil {
    panic(err)
}

err = products.Iter(ctx, func(p *paddle.Product) (bool, error) {
    // Do something with the product
    fmt.Printf("%+v\n", p)
    return true, nil
})
if err != nil {
    panic(err)
}
```

--------------------------------

### Create an entity

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/README.md

Example of creating a new product using the CreateProduct function.

```go
product, err := client.CreateProduct(ctx, &paddle.CreateProductRequest{
    Name:        "Test Product - GO SDK",
    TaxCategory: paddle.TaxCategoryStandard,
})
if err != nil {
    panic(err)
}
fmt.Printf("%+v\n", product)
```

--------------------------------

### Iter() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

Iterates through all items in the collection, calling a function for each result.

```go
products, err := client.ListProducts(ctx, nil)
if err != nil {
    return err
}

err = products.Iter(ctx, func(p *paddle.Product) (bool, error) {
    log.Printf("Product: %s (%s)", p.Name, p.ID)
    
    // Continue to next item
    return true, nil
})
if err != nil {
    return err
}
```

--------------------------------

### Use as HTTP Middleware

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Example of using the `paddle.NewWebhookVerifier().Middleware()` to verify incoming webhooks.

```go
handler := paddle.NewWebhookVerifier(secret).Middleware(
    http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Webhook verified
        w.WriteHeader(http.StatusOK)
    }),
)

http.Handle("/webhooks", handler)
```

--------------------------------

### Tax Categories

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Examples of common tax category constants.

```go
paddle.TaxCategoryStandard         // "standard"
paddle.TaxCategoryDigitalServices  // "digital_services"
paddle.TaxCategoryEBooks           // "ebooks"
// ... and more
```

--------------------------------

### Next() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

Returns the next result from the collection, fetching the next page if necessary.

```go
for {
    res := collection.Next(ctx)
    if !res.Ok() {
        if err := res.Err(); err != nil {
            return err
        }
        break // No more results
    }
    
    product := res.Value()
    log.Printf("Product: %s", product.Name)
}
```

--------------------------------

### CustomData Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/types.md

Illustrates adding custom data to a customer creation request.

```go
customer, err := client.CreateCustomer(ctx, &CreateCustomerRequest{
    Email: "user@example.com",
    CustomData: paddle.CustomData{
        "account_tier": "premium",
        "signup_date": "2024-01-15",
        "referrer_id": "ref_123",
    },
})
```

--------------------------------

### Collection Iteration Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/types.md

Shows how to iterate through all pages of a collection using the Iter method.

```go
products, err := client.ListProducts(ctx, &ListProductsRequest{})
if err != nil {
    return err
}

// Iterate through all pages
err = products.Iter(ctx, func(p *Product) (bool, error) {
    log.Printf("Product: %s", p.Name)
    return true, nil // Continue iteration
})
```

--------------------------------

### Replay Notification

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Example of replaying a notification using `client.ReplayNotification()`.

```go
result, err := client.ReplayNotification(ctx, &paddle.ReplayNotificationRequest{
    NotificationID: "ntf_123",
})
```

--------------------------------

### Create Report Request (Products and Prices)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/UPGRADING.md

Example of how to create a report request for products and prices in v0.6.0, reflecting the updated Reports API integration.

```go
res, err := client.CreateReport(ctx,
	paddle.NewCreateReportRequestProductsAndPricesReport(&paddle.ProductsAndPricesReport{
		Type: paddle.ReportTypeProductsPricesProductsPrices,
		Filters: []paddle.ReportFiltersProductPrices{
			paddle.ReportFiltersProductPrices{
				Name:  paddle.FilterNameProductPricesPriceStatus,
				Value: []string{"archived"},
			},
			paddle.ReportFiltersProductPrices{
				Name:  paddle.FilterNameProductPricesProductStatus,
				Value: []string{"archived"},
			},
		},
	}),
)
```

--------------------------------

### PerPage() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

Returns the number of items returned per page in the current collection.

```go
products, err := client.ListProducts(ctx, &paddle.ListProductsRequest{
    PerPage: paddle.Int(25),
})
if err != nil {
    return err
}

log.Printf("Items per page: %d", products.PerPage())
```

--------------------------------

### Verify Webhook

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/README.md

Example of how to verify an incoming webhook using the Paddle Go SDK.

```go
verifier := paddle.NewWebhookVerifier(webhookSecret)

handler := verifier.Middleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    // Webhook is verified at this point
    w.WriteHeader(http.StatusOK)
}))

http.Handle("/webhooks", handler)
```

--------------------------------

### Iter() Stop Iteration Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

Demonstrates how to stop iteration using the Iter() method.

```go
err = products.Iter(ctx, func(p *paddle.Product) (bool, error) {
    if p.Name == "Target Product" {
        log.Printf("Found: %s", p.ID)
        return false, nil // Stop iteration
    }
    return true, nil
})
```

--------------------------------

### PatchField Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/types.md

Demonstrates creating a PATCH request with optional fields using NewPatchField and NewNullPatchField.

```go
req := &paddle.UpdateProductRequest{
    ProductID: "pro_123",
    Name: paddle.NewPatchField("Updated Name"),
    Description: paddle.NewPatchField(paddle.String("New desc")),
    Status: paddle.NewNullPatchField[paddle.Status](), // Set to null
}
```

--------------------------------

### Res Iteration Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/types.md

Demonstrates iterating through a collection using Res to check for success, errors, and retrieve values.

```go
for {
    res := collection.Next(ctx)
    if !res.Ok() {
        if err := res.Err(); err != nil {
            return err
        }
        break
    }
    
    product := res.Value()
    log.Printf("Product: %s", product.Name)
}
```

--------------------------------

### TrialPeriod Type Change Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/UPGRADING.md

Illustrates the change in the TrialPeriod property for Price entities from Duration to TrialPeriod in v5.0.0.

```go
// Before (v4.x)
TrialPeriod: &paddle.Duration{
    Interval:  paddle.IntervalMonth,
    Frequency: 1,
}

// After (v5.0)
TrialPeriod: &paddle.TrialPeriod{
    Interval:               paddle.IntervalMonth,
    Frequency:              1,
    RequiresPaymentMethod: true, // defaults to true if omitted or set to true to be explicit
}
```

--------------------------------

### Res.Err() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

An example showing how to use Res.Err() to check for iteration errors.

```go
for {
    res := collection.Next(ctx)
    if !res.Ok() {
        if err := res.Err(); err != nil {
            log.Printf("Iteration error: %v", err)
            return err
        }
        break // Normal end
    }
    item := res.Value()
}
```

--------------------------------

### Import Paths

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/README.md

Provides an example of the main import path for the SDK and lists some of the commonly used exported types and functions.

```go
import paddle "github.com/PaddleHQ/paddle-go-sdk/v5"

// All types available directly:
// paddle.SDK
// paddle.Product, paddle.Customer, paddle.Price
// paddle.CreateProductRequest, paddle.ListProductsRequest
// paddle.Status, paddle.TaxCategory, paddle.CurrencyCode
// paddle.ErrNotFound, paddle.ErrForbidden
// paddle.NewWebhookVerifier
// paddle.PatchField, paddle.CustomData
// etc.
```

--------------------------------

### Enum Type Upgrade Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/UPGRADING.md

Demonstrates the correct way to use constants for enum types after the v0.5.0 update, specifically for the 'Status' field in UpdatePriceRequest.

```go
// Instead of this
priceUpdate := &paddle.UpdatePriceRequest{Status: paddle.NewPatchField("archived")}

// paddle.Status can be passed using paddle.StatusArchived
priceUpdate := &paddle.UpdatePriceRequest{Status: paddle.NewPatchField(paddle.StatusArchived)}
```

--------------------------------

### CustomData Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/README.md

Shows how to attach arbitrary metadata to entities using the CustomData field during customer creation.

```go
customer, err := client.CreateCustomer(ctx, &paddle.CreateCustomerRequest{
    Email: "user@example.com",
    CustomData: paddle.CustomData{
        "account_tier": "premium",
        "signup_date":  "2024-01-15",
    },
})
```

--------------------------------

### Products - Create Product

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Creates a new product with a name, tax category, and description.

```go
product, err := client.CreateProduct(ctx, &paddle.CreateProductRequest{
    Name:        "Starter Plan",
    TaxCategory: paddle.TaxCategoryStandard,
    Description: paddle.String("Basic subscription"),
})
```

--------------------------------

### Base URLs constants

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Constants for production and sandbox base URLs.

```go
const (
    ProductionBaseURL = "https://api.paddle.com"
    SandboxBaseURL    = "https://sandbox-api.paddle.com"
)
```

--------------------------------

### Accessing Sub-clients

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Demonstrates how to access various resource clients (e.g., Products, Customers) directly from the initialized SDK client.

```go
client, err := paddle.New(apiKey)

// Access sub-clients directly (embedded)
products, err := client.ListProducts(ctx, nil)
customers, err := client.ListCustomers(ctx, nil)
transactions, err := client.ListTransactions(ctx, nil)

// All 23 resource clients available:
// client.ProductsClient
// client.PricesClient
// client.TransactionsClient
// client.CustomersClient
// ... and more
```

--------------------------------

### Products - List Products with Prices

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Lists products and includes their associated prices in the response.

```go
products, err := client.ListProducts(ctx, &paddle.ListProductsRequest{
    IncludePrices: true,
})
```

--------------------------------

### Environment Variables Initialization

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Initializing the SDK using environment variables for configuration.

```Go
import "os"

// API Key
apiKey := os.Getenv("PADDLE_API_KEY")

// Base URL (optional)
baseURL := os.Getenv("PADDLE_API_BASE_URL")
if baseURL == "" {
    baseURL = paddle.ProductionBaseURL
}

// Initialize
client, err := paddle.New(
    apiKey,
    paddle.WithBaseURL(baseURL),
)
```

--------------------------------

### HasMore() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

Returns whether there are more pages of results to be fetched.

```go
prices, err := client.ListPrices(ctx, &paddle.ListPricesRequest{PerPage: paddle.Int(50)})
if err != nil {
    return err
}

if prices.HasMore() {
    log.Println("More results available on next page")
}
```

--------------------------------

### Iteration with Filtering

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/README.md

Example of iterating through a collection with a filter condition.

```go
err = collection.Iter(ctx, func(item *Entity) (bool, error) {
    if shouldInclude(item) {
        process(item)
    }
    return true, nil // Continue
})
```

--------------------------------

### Accessing Methods

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Each sub-client is embedded, so methods are accessible directly on the SDK instance.

```go
// Instead of: client.ProductsClient.ListProducts()
// Use:
products, err := client.ListProducts(ctx, &paddle.ListProductsRequest{})
```

--------------------------------

### Customers - Create Customer

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Creates a new customer with an email and name.

```go
customer, err := client.CreateCustomer(ctx, &paddle.CreateCustomerRequest{
    Email: "user@example.com",
    Name:  paddle.String("John Doe"),
})
```

--------------------------------

### Early Exit from Iteration

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/README.md

Example of how to stop iteration early using paddle.ErrStopIteration.

```go
err = collection.IterErr(ctx, func(item *Entity) error {
    if isTarget(item) {
        return paddle.ErrStopIteration
    }
    return nil
})
```

--------------------------------

### SDK Initialization - With Custom HTTP Client

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Initializes the Paddle client with a custom HTTP client, allowing for timeout configuration.

```go
httpClient := &http.Client{Timeout: 30 * time.Second}
client, err := paddle.New(apiKey, paddle.WithClient(httpClient))
```

--------------------------------

### Status Values

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Examples of common status value constants.

```go
paddle.StatusActive    // "active"
paddle.StatusArchived  // "archived"
```

--------------------------------

### New() function signature

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Creates a new Paddle SDK instance configured for the production environment.

```go
func New(apiKey string, opts ...Option) (*SDK, error)
```

--------------------------------

### Initialize SDK

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/README.md

Initializes the Paddle SDK with an API key.

```go
import paddle "github.com/PaddleHQ/paddle-go-sdk/v5"

client, err := paddle.New(apiKey)
if err != nil {
    panic(err)
}
```

--------------------------------

### WithClient() function signature

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Sets a custom HTTP client for making requests to Paddle API.

```go
func WithClient(c client.HTTPDoer) Option
```

--------------------------------

### WithBaseURL() function signature

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Sets the base URL for API requests.

```go
func WithBaseURL(baseURL string) Option
```

--------------------------------

### NewSandbox() function signature

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Creates a new Paddle SDK instance configured for the sandbox environment.

```go
func NewSandbox(apiKey string, opts ...Option) (*SDK, error)
```

--------------------------------

### Configuration Validation

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/configuration.md

Illustrates how the SDK validates configuration during initialization and potential error handling.

```go
client, err := paddle.New(apiKey, opts...)
if err != nil {
    // Handle invalid configuration
    // Common reasons:
    // - Invalid base URL format
    // - Missing API key
}
```

--------------------------------

### WithAPIKey() function signature

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

Sets the API key for authentication.

```go
func WithAPIKey(apiKey string) Option
```

--------------------------------

### Update an entity

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/README.md

Example of updating an existing product using the UpdateProduct function.

```go
product, err := client.UpdateProduct(ctx, &paddle.UpdateProductRequest{
    ProductID: product.ID,
    Name:      paddle.NewPatchField("Test Product - GO SDK Updated"),
})
if err != nil {
    panic(err)
}
fmt.Printf("%+v\n", product)
```

--------------------------------

### Base URLs Initialization

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/README.md

Shows how to initialize the SDK client for production or sandbox environments, and how to explicitly set the base URL if needed.

```go
const (
    ProductionBaseURL = "https://api.paddle.com"
    SandboxBaseURL    = "https://sandbox-api.paddle.com"
)

// Auto-detected by New() and NewSandbox()
client, err := paddle.New(apiKey)              // → Production
client, err := paddle.NewSandbox(apiKey)      // → Sandbox

// Or explicitly set:
client, err := paddle.New(apiKey, 
    paddle.WithBaseURL(paddle.SandboxBaseURL),
)
```

--------------------------------

### SDK Structure

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/sdk-initialization.md

The SDK type embeds 23 specialized sub-clients, each providing operations for a specific resource.

```go
type SDK struct {
    *ProductsClient
    *PricesClient
    *TransactionsClient
    *PricingPreviewClient
    *AdjustmentsClient
    *CustomersClient
    *AddressesClient
    *BusinessesClient
    *PaymentMethodsClient
    *CustomerPortalSessionsClient
    *NotificationSettingsClient
    *EventTypesClient
    *EventsClient
    *NotificationsClient
    *NotificationLogsClient
    *SimulationTypesClient
    *SimulationsClient
    *SimulationRunsClient
    *SimulationRunEventsClient
    *IPAddressesClient
    *MetricsClient
    *DiscountsClient
    *DiscountGroupsClient
    *SubscriptionsClient
    *ReportsClient
    *ClientTokensClient
}
```

--------------------------------

### EstimatedTotal() Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/collection-pagination.md

Returns the estimated total number of items in the entire collection (across all pages).

```go
customers, err := client.ListCustomers(ctx, nil)
if err != nil {
    return err
}

log.Printf("Total customers: ~%d", customers.EstimatedTotal())
```

--------------------------------

### File Organization

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/INDEX.md

Directory structure of the Paddle Go SDK project.

```text
/workspace/home/output/
├── INDEX.md                          ← You are here
├── README.md                          (Main overview)
├── quick-reference.md                 (Copy-paste patterns)
├── sdk-initialization.md              (SDK setup)
├── configuration.md                   (Configuration options)
├── types.md                           (Type definitions)
├── errors.md                          (Error reference)
└── api-reference/
    ├── README.md                      (API index)
    ├── products-client.md
    ├── prices-client.md
    ├── customers-client.md
    ├── collection-pagination.md
    └── webhook-verifier.md
```

--------------------------------

### ListPrices()

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/prices-client.md

Lists all prices with optional filtering by product, status, or type. Returns a paginated collection.

```Go
func (c *PricesClient) ListPrices(ctx context.Context, req *ListPricesRequest) (res *Collection[*Price], err error)
```

```Go
prices, err := client.ListPrices(ctx, &paddle.ListPricesRequest{
    ProductID:     []string{"pro_123"},
    Recurring:     paddle.Bool(true),
    PerPage:       paddle.Int(50),
    IncludeProduct: true,
})
if err != nil {
    log.Fatal(err)
}

err = prices.Iter(ctx, func(p *paddle.Price) (bool, error) {
    log.Printf("Price: %s - %s %s", p.ID, p.UnitPrice.Amount, p.UnitPrice.CurrencyCode)
    return true, nil
})
```

--------------------------------

### CreatePrice()

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/prices-client.md

Creates a new price for a product.

```Go
func (c *PricesClient) CreatePrice(ctx context.Context, req *CreatePriceRequest) (res *Price, err error)
```

```Go
price, err := client.CreatePrice(ctx, &paddle.CreatePriceRequest{
    ProductID:   "pro_123",
    Description: "Monthly subscription",
    Name:        paddle.String("Monthly Plan"),
    UnitPrice: paddle.Money{
        Amount:       "2999",
        CurrencyCode: paddle.CurrencyCodeUSD,
    },
    BillingCycle: &paddle.Duration{
        Interval:  "month",
        Frequency: 1,
    },
    TaxMode: paddle.TaxModeAccountSetting,
})
if err != nil {
    log.Fatal(err)
}
log.Printf("Created price: %s", price.ID)
```

--------------------------------

### Conditional Updates

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/README.md

Example of performing a conditional update on a product, setting specific fields and nullifying others.

```go
req := &paddle.UpdateProductRequest{
    ProductID: "pro_123",
    Name: paddle.NewPatchField("New Name"),
    Status: paddle.NewNullPatchField[paddle.Status](), // Set to null
}

updated, err := client.UpdateProduct(ctx, req)
```

--------------------------------

### Create Customer

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/README.md

Creates a new customer with an email and name.

```go
customer, err := client.CreateCustomer(ctx, &paddle.CreateCustomerRequest{
    Email: "user@example.com",
    Name:  paddle.String("John Doe"),
})
if err != nil {
    return err
}
```

--------------------------------

### Request with Deadline

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Setting a deadline for a request using `context.WithDeadline()`.

```go
deadline := time.Now().Add(5 * time.Second)
ctx, cancel := context.WithDeadline(context.Background(), deadline)
defer cancel()

product, err := client.GetProduct(ctx, req)
```

--------------------------------

### Prices - Create Monthly Price

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Creates a monthly recurring price for a product.

```go
price, err := client.CreatePrice(ctx, &paddle.CreatePriceRequest{
    ProductID:   "pro_123",
    Description: "Monthly subscription",
    UnitPrice: paddle.Money{
        Amount:       "2999",
        CurrencyCode: paddle.CurrencyCodeUSD,
    },
    BillingCycle: &paddle.Duration{
        Interval:  "month",
        Frequency: 1,
    },
})
```

--------------------------------

### Checking for Specific Errors

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/errors.md

Example of how to check for specific error types using errors.Is.

```go
import paddle "github.com/PaddleHQ/paddle-go-sdk/v5"
import errors "errors"
import log "log"

result, err := client.GetProduct(ctx, &paddle.GetProductRequest{ProductID: "pro_123"})
if err != nil && errors.Is(err, paddle.ErrNotFound) {
    log.Println("Product not found")
}
```

--------------------------------

### Customers - List Customers

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Lists customers with pagination.

```go
customers, err := client.ListCustomers(ctx, &paddle.ListCustomersRequest{
    PerPage: paddle.Int(25),
})
```

--------------------------------

### NewWebhookVerifier Example

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/api-reference/webhook-verifier.md

Creates a new WebhookVerifier with a secret key and optional configuration, including timestamp validation.

```go
verifier := paddle.NewWebhookVerifier(
    os.Getenv("WEBHOOK_SECRET_KEY"),
)

// With timestamp validation
verifier := paddle.NewWebhookVerifier(
    os.Getenv("WEBHOOK_SECRET_KEY"),
    paddle.VerifierWithTimestampTolerance(5 * time.Minute),
)
```

--------------------------------

### List Events

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

How to list events using the `client.ListEvents()` method.

```go
events, err := client.ListEvents(ctx, &paddle.ListEventsRequest{
    PerPage: paddle.Int(100),
})
```

--------------------------------

### Customers - Get Customer Auth Token (for Paddle.js)

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Retrieves an authentication token for a customer, intended for use with Paddle.js.

```go
authToken, err := client.GetCustomerAuthToken(ctx, &paddle.GetCustomerAuthTokenRequest{
    CustomerID: "ctm_123",
})
// Use authToken.CustomerAuthToken with Paddle.js
```

--------------------------------

### Common Operations - Create Resource

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/quick-reference.md

Creates a new product with specified name and tax category.

```go
product, err := client.CreateProduct(ctx, &paddle.CreateProductRequest{
    Name:        "Product Name",
    TaxCategory: paddle.TaxCategoryStandard,
})
```

--------------------------------

### Initialize Client

Source: https://github.com/paddlehq/paddle-go-sdk/blob/main/_autodocs/README.md

Initializes the Paddle client with an API key and handles potential errors.

```go
import paddle "github.com/PaddleHQ/paddle-go-sdk/v5"

client, err := paddle.New(os.Getenv("PADDLE_API_KEY"))
if err != nil {
    panic(err)
}
```