Skip to main content

​
Introduction

The Square Go SDK provides a comprehensive set of API clients for interacting with Square’s various services. The SDK is organized into domain-specific clients, each handling a particular aspect of the Square platform.

​
Client Architecture

The SDK uses a modular architecture where the main Client type provides access to all resource-specific clients. Each resource client is responsible for operations related to a specific Square API domain.

​
Main Client

The root Client type serves as the entry point to all Square APIs: 
import (
    "github.com/square/square-go-sdk/v3/client"
    "github.com/square/square-go-sdk/v3/option"
)

// Initialize with access token
client := client.NewClient(
    option.WithToken("your-access-token"),
)

// Access resource clients
payments := client.Payments
customers := client.Customers

​
Available API Clients

The SDK provides clients for the following Square APIs:

​
Payments & Transactions

Payments

Process payments and manage payment methods

Refunds

Handle payment refunds and cancellations

Checkout

Create online checkout experiences

Terminal

Manage in-person terminal transactions

​
Customer Management

Customers

Manage customer profiles and data

Cards

Handle customer payment cards

Loyalty

Administer loyalty programs and rewards

Gift Cards

Manage gift card operations

​
Business Operations

Catalog

Manage products, items, and variations

Inventory

Track and manage inventory levels

Orders

Create and manage orders

Invoices

Generate and send invoices

​
Business Resources

Locations

Manage business locations

Merchants

Access merchant information

Team Members

Manage staff and permissions

Labor

Handle employee scheduling and timekeeping

​
Financial Operations

Bank Accounts

Manage linked bank accounts

Payouts

Track settlement payouts

Disputes

Handle payment disputes and chargebacks

Cash Drawers

Manage cash drawer operations

​
Additional Services

Bookings

Manage appointments and bookings

Subscriptions

Handle recurring subscription billing

Sites

Manage Square Online sites

Webhooks

Configure webhook subscriptions

​
Integration & Tools

OAuth

Handle OAuth authentication flows

Events

Subscribe to Square events

Devices

Manage device codes and hardware

Snippets

Embed Square functionality in websites

​
Client Organization

All clients follow a consistent pattern:
  1. Initialization: Each client is automatically initialized when you create the main Client
  2. Methods: Clients expose methods corresponding to Square API endpoints
  3. Context Support: All methods accept a context.Context for cancellation and timeouts
  4. Options: Methods accept optional RequestOption parameters for customization
  5. Raw Response: Each client includes a WithRawResponse variant for accessing full HTTP responses

​
Example Usage

import (
    "context"
    "github.com/square/square-go-sdk/v3/client"
    "github.com/square/square-go-sdk/v3/option"
)

func main() {
    // Create client
    client := client.NewClient(
        option.WithToken("your-access-token"),
    )
    
    // Use a specific API client
    ctx := context.Background()
    
    // List customers
    customersPage, err := client.Customers.List(
        ctx,
        &square.ListCustomersRequest{},
    )
    if err != nil {
        // Handle error
    }
    
    // Create a payment
    payment, err := client.Payments.Create(
        ctx,
        &square.CreatePaymentRequest{
            SourceID:     square.String("card-token"),
            IdempotencyKey: square.String("unique-key"),
            AmountMoney: &square.Money{
                Amount:   square.Int64(1000),
                Currency: square.CurrencyUsd.Ptr(),
            },
        },
    )
}

​
Error Handling

All client methods return standard Go errors. The SDK includes error types for common failure scenarios: 
response, err := client.Payments.Create(ctx, request)
if err != nil {
    // Handle error - check for specific error types
    // or examine the error message
    return err
}

​
Pagination

Many list operations return paginated results using the core.Page type: 
page, err := client.Customers.List(ctx, &square.ListCustomersRequest{})
if err != nil {
    return err
}

// Iterate through results
for _, customer := range page.Results() {
    // Process customer
}

// Get next page if available
if !page.Done() {
    nextPage, err := page.GetNext(ctx)
    // Process next page
}

​
Next Steps

Client Configuration

Learn how to initialize and configure the main client

Authentication

Set up authentication for your application

Request Options

Customize individual requests

Error Handling

Handle errors and edge cases

Build docs developers (and LLMs) love

Get started for freeTalk to us