Skip to main content
The Merchants API provides access to information about Square merchants. Use this API to retrieve details about the merchant associated with an access token.

​
Overview

The Merchants client provides methods to:
  • List merchants associated with an access token
  • Retrieve a specific merchant by ID

​
Client Initialization

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

client := square.NewClient(
    &core.RequestOptions{
        Token: "YOUR_ACCESS_TOKEN",
    },
)

​
Methods

​
List Merchants

Returns details about the merchant associated with the provided access token. The access token is tied to a single merchant, so this endpoint returns a list with one Merchant object.
merchants/client/client.go
request := &square.ListMerchantsRequest{
    Cursor: square.Int(1),
}

response, err := client.Merchants.List(context.TODO(), request)
if err != nil {
    // Handle error
}

for _, merchant := range response.Merchant {
    fmt.Printf("Merchant: %s (ID: %s)\n", *merchant.BusinessName, *merchant.ID)
}
​
cursor
*int
The cursor generated by a previous response for pagination
​
merchant
[]*Merchant
Array of merchant objects (typically contains one merchant)

​
Get Merchant

Retrieves details for a specific merchant by ID. You can use “me” as the merchant ID to retrieve information about the merchant associated with the access token.
merchants/client/client.go
request := &square.GetMerchantsRequest{
    MerchantID: "me", // or a specific merchant ID
}

response, err := client.Merchants.Get(context.TODO(), request)
if err != nil {
    // Handle error
}

merchant := response.Merchant
fmt.Printf("Business: %s\n", *merchant.BusinessName)
fmt.Printf("Country: %s\n", merchant.Country)
fmt.Printf("Main Location: %s\n", *merchant.MainLocationID)
​
merchantID
string
required
The ID of the merchant to retrieve. Use “me” to retrieve the merchant associated with the current access token.
​
merchant
Merchant
The requested merchant object

​
Response Types

​
Merchant

Represents a business that sells with Square.
​
id
string
The Square-issued ID of the merchant
​
business_name
string
The name of the merchant’s overall business
​
country
Country
required
The country code associated with the merchant (ISO 3166 format)
​
language_code
string
The language preferences of the merchant in BCP 47 format
​
currency
Currency
The currency associated with the merchant (ISO 4217 format)
​
status
MerchantStatus
The merchant’s current status
  • ACTIVE: The merchant is active
  • INACTIVE: The merchant is inactive
​
main_location_id
string
The ID of the main Location for this merchant. See Main Location for more details.
​
created_at
string
The timestamp when the merchant was created, in RFC 3339 format

​
Use Cases

​
Get Current Merchant Information

// Retrieve information about the merchant associated with your access token
request := &square.GetMerchantsRequest{
    MerchantID: "me",
}

response, err := client.Merchants.Get(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Business Name: %s\n", *response.Merchant.BusinessName)
fmt.Printf("Main Location: %s\n", *response.Merchant.MainLocationID)

​
List All Merchants (OAuth)

// When using OAuth, list the merchant that granted access
request := &square.ListMerchantsRequest{}

response, err := client.Merchants.List(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

if len(response.Merchant) > 0 {
    merchant := response.Merchant[0]
    fmt.Printf("Connected to: %s\n", *merchant.BusinessName)
}

​
Error Handling

response, err := client.Merchants.Get(context.TODO(), request)
if err != nil {
    // Check for API errors
    if response != nil && len(response.Errors) > 0 {
        for _, e := range response.Errors {
            fmt.Printf("Error: %s - %s\n", e.Category, e.Detail)
        }
    }
    return err
}

​
Important Notes

The access token used to connect your application to a Square seller is associated with a single merchant. This means ListMerchants always returns a list with only one merchant object.
Use the main_location_id field to quickly access the merchant’s primary location without having to list all locations.

Build docs developers (and LLMs) love

Get started for freeTalk to us