Square Getting Started: Account Setup and First API Call (2026)

Getting started overview

Integrating with Square's APIs requires setting up a developer account, creating an application, and obtaining the necessary API credentials. This process enables access to Square's ecosystem, allowing developers to manage payments, customer data, and item catalogs programmatically. Square provides a sandbox environment for testing integrations without affecting live production data or incurring real transaction fees Square Sandbox for testing. The API itself is primarily RESTful, utilizing JSON for request and response bodies, and supports various programming languages through official SDKs Square SDKs overview.

The initial setup involves a few key steps:

1. Create a Square account and an application in the Developer Dashboard.
2. Generate personal access tokens or OAuth credentials for API authentication.
3. Configure your development environment and send a test API request.

This guide focuses on these foundational steps to help establish a working connection with the Square API.

Create an account and get keys

To begin using the Square API, you must first create a Square account. If you do not have an existing account, you can sign up through the official Square website Square signup page. After creating an account, navigate to the Square Developer Dashboard Square Developer Applications. Within the dashboard, create a new application.

Each application is assigned a unique Application ID. This ID is used to identify your application within the Square ecosystem. For API authentication, Square primarily uses access tokens. There are two main types:

• Personal Access Tokens: These are suitable for sandbox testing and internal tools. They grant direct access to your Square account's data. You can generate a personal access token directly from your application's settings in the Developer Dashboard Square Personal Access Token guide. It is crucial to treat these tokens as sensitive information, similar to passwords, and store them securely.
• OAuth Access Tokens: For production applications that interact with various Square seller accounts (e.g., a SaaS platform), OAuth is the recommended authentication method. OAuth allows sellers to grant your application specific permissions without sharing their Square account credentials. Setting up OAuth involves configuring redirect URLs and handling authorization flows Square OAuth API overview.

For initial testing and this getting started guide, a personal access token for the sandbox environment is sufficient. Ensure you select the 'Sandbox' environment when generating or using your token, as this protects your live production data.

Your first request

After obtaining your Application ID and a sandbox personal access token, you can make your first API call. A common first step is to retrieve a list of locations associated with your Square account. This verifies your credentials and connectivity. We will demonstrate this using Node.js, Python, and a generic curl command for direct HTTP requests.

Node.js example

First, install the Square Node.js SDK:

npm install square

Then, make the API call:

const { Client, Environments } = require('square');

const client = new Client({
  environment: Environments.Sandbox,
  accessToken: 'YOUR_SANDBOX_ACCESS_TOKEN',
});

const { locationsApi } = client;

async function listLocations() {
  try {
    const response = await locationsApi.listLocations();
    console.log(response.result.locations);
  } catch (error) {
    console.error('Error listing locations:', error.result);
  }
}

listLocations();

Replace 'YOUR_SANDBOX_ACCESS_TOKEN' with the personal access token you generated.

Python example

Install the Square Python SDK:

pip install square

Then, make the API call:

from square.client import Client

client = Client(
    environment="sandbox",
    access_token="YOUR_SANDBOX_ACCESS_TOKEN"
)

result = client.locations.list_locations()

if result.is_success():
    print(result.body)
elif result.is_error():
    print(result.errors)

Again, replace 'YOUR_SANDBOX_ACCESS_TOKEN' with your actual sandbox token.

cURL example (direct HTTP request)

For environments where an SDK is not immediately available or for debugging, you can use curl:

curl -X GET \
  https://connect.squareupsandbox.com/v2/locations \
  -H 'Square-Version: 2024-05-15' \
  -H 'Authorization: Bearer YOUR_SANDBOX_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Remember to substitute YOUR_SANDBOX_ACCESS_TOKEN. The Square-Version header specifies the API version; ensure it matches a recent version as documented by Square Square API versioning documentation.

A successful response will return a JSON object containing an array of your Square account's locations. If you encounter errors, verify your access token and ensure you are targeting the sandbox environment URL.

Common next steps

After successfully establishing API connectivity, developers typically proceed with more complex integrations. These often include:

• Processing Payments: Implementing logic to create and process payments using the Payments API for online or in-person transactions Square Payments API reference. This might involve tokenizing card information using Square's Web Payments SDK or integrating with Square Readers.
• Managing Catalogs: Utilizing the Catalog API to create, update, and manage items, categories, and inventory Square Catalog API documentation. This is essential for e-commerce platforms or POS integrations.
• Customer Management: Integrating the Customers API to store and retrieve customer information, including payment methods, for loyalty programs or personalized experiences Square Customers API reference.
• Webhooks and Event Notifications: Setting up webhooks to receive real-time notifications about events in your Square account, such as new orders, payment updates, or inventory changes Square Webhooks overview. This enables reactive and event-driven application architectures.
• Error Handling and Logging: Implementing robust error handling and logging mechanisms to diagnose issues and ensure application stability. Square's API responses include detailed error codes and messages that can be used for this purpose Square API error handling guide. Understanding common HTTP status codes is also critical for effective API interaction MDN HTTP Status Codes.
• Production Deployment: Migrating from the sandbox environment to production. This involves obtaining production access tokens (often via OAuth) and ensuring your application handles real-world transactions and data securely.

Troubleshooting the first call

If your first API call to Square returns an error, consider the following common issues and troubleshooting steps:

• Invalid Access Token: Double-check that the access token you are using is correct and has not expired. Ensure you are using a sandbox token for the sandbox environment, and a production token (typically from OAuth) for the production environment. Tokens are case-sensitive.
• Incorrect Environment URL: Verify that your API requests are directed to the correct environment URL. For sandbox testing, use https://connect.squareupsandbox.com. For production, use https://connect.squareup.com.
• Missing or Incorrect Headers: Ensure all required HTTP headers are present and correctly formatted. This includes Authorization: Bearer YOUR_ACCESS_TOKEN and Content-Type: application/json for most requests. The Square-Version header is also crucial for API stability.
• Permissions Errors: Your access token might not have the necessary permissions (scopes) to access the requested resource. For example, listing locations requires the LOCATIONS_READ permission Square OAuth permissions reference. Check the permissions associated with your access token in the Developer Dashboard.
• Network Connectivity: Confirm that your development environment has a stable internet connection and is not blocked by firewalls or proxy settings from reaching Square's API endpoints.
• SDK Configuration: If using an SDK, ensure it's initialized with the correct environment and access token. Refer to the specific SDK's documentation for initialization details.
• API Version Mismatch: The Square-Version header in your request dictates which API version you're interacting with. If the version is very old or unsupported, it might lead to errors. Always use a supported, recent API version Square API versioning.
• Review Error Response: Square's API provides detailed error responses, including an errors array with specific error codes and descriptive messages. Parse these responses to understand the root cause of the issue Square API error handling.