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

Getting started overview

Integrating with Square's APIs allows developers to extend Square's payment and business management functionality into custom applications. The process generally involves setting up a developer account, creating an application in the Developer Dashboard, and obtaining API credentials for authentication. Developers can then use Square's SDKs or direct HTTP requests to interact with the API, initially within a sandbox environment for testing.

Key steps to get started with Square's APIs include:

1. Create a Square account: Sign up for a free Square account, which provides access to the Developer Dashboard.
2. Create an application: Generate a new application within the Developer Dashboard to obtain application IDs and access tokens.
3. Configure credentials: Retrieve your application's access token and location ID, which are necessary for authenticating API requests.
4. Set up a development environment: Choose an SDK (Java, PHP, Python, Ruby, C#, Node.js) or prepare for direct HTTP requests.
5. Make your first API call: Use the sandbox environment to test a basic API request, such as retrieving a list of locations.

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

Create an account and get keys

To begin using Square's APIs, you need a Square account. This account provides access to the Square Developer Dashboard, where you manage your applications and API credentials. Creating an account is free and does not require immediate payment setup.

1. Sign up for a Square account

Navigate to the Square signup page and complete the registration process. You will need to provide basic business information. Once signed up, you can access the Developer Dashboard.

2. Create a new application

Within the Developer Dashboard, applications serve as containers for your API integrations. Each application has its own set of credentials. To create one:

1. Log in to the Square Developer Dashboard.
2. Click the + New Application button.
3. Provide a name for your application (e.g., "My First Integration") and click Save.

3. Retrieve API credentials

After creating an application, you will need two key pieces of information to authenticate your API requests: an access token and a location ID. These are found on your application's settings page in the Developer Dashboard.

• Access Token: This token authenticates your application to the Square API. It grants permissions to perform actions on behalf of your Square account. You will find both a Sandbox access token and a Production access token. For initial testing, use the Sandbox token. Keep your access tokens secure, as they provide access to your Square data.
• Application ID: A unique identifier for your application.
• Location ID: Each Square account can have multiple business locations. API requests often require a specific location ID to operate on data associated with that location. You can find your location IDs in the Developer Dashboard under your application's credentials.

For more detailed instructions on managing credentials, refer to the Square application credentials guide.

Your first request

After obtaining your Sandbox Access Token and a Location ID, you can make your first API call. This example demonstrates retrieving a list of locations associated with your Square account using cURL. This request will be made against the Square Sandbox environment to avoid affecting live data.

Before making the request, ensure you have the following:

• Your Sandbox Access Token (e.g., EAAAEP-YourSandboxAccessToken-EAAAE)
• A valid Location ID from your Sandbox account (e.g., L1234567890ABC)

Example: List Locations using cURL

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

Replace EAAAEP-YourSandboxAccessToken-EAAAE with your actual Sandbox Access Token. The Square-Version header specifies the API version your application is designed to use. You can find the current recommended API version in the Square documentation.

A successful response will return a JSON array of location objects:

{
  "locations": [
    {
      "id": "L1234567890ABC",
      "name": "Main Location",
      "address": {
        "address_line_1": "123 Main St",
        "locality": "Anytown",
        "administrative_district_level_1": "CA",
        "postal_code": "90210",
        "country": "US"
      },
      "timezone": "America/Los_Angeles",
      "currency": "USD",
      "status": "ACTIVE",
      "created_at": "2023-01-01T12:00:00Z"
    }
    // ... other locations
  ]
}

This confirms that your API credentials are set up correctly and you can communicate with the Square API.

For developers using an SDK, the process is similar. For example, using the Node.js SDK:

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

const client = new Client({
  environment: Environment.Sandbox,
  accessToken: 'EAAAEP-YourSandboxAccessToken-EAAAE',
});

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

listLocations();

Remember to install the Square SDK for Node.js using npm install square.

Common next steps

Once you've successfully made your first API call, consider these next steps to further your integration:

1. Explore the API Reference: Review the Square API Reference to understand the available endpoints and data models. Common starting points include Payments, Customers, and Orders APIs.
2. Use Square SDKs: While cURL is useful for testing, using one of Square's official SDKs (Java, PHP, Python, Ruby, C#, Node.js) can streamline development by handling authentication, request signing, and response parsing. Refer to the Square SDK overview for installation and usage guides.
3. Implement Webhooks: Set up webhooks to receive real-time notifications about events in your Square account, such as new payments or updated orders. This is crucial for building reactive applications. The Square Webhooks documentation provides details on configuration.
4. Error Handling: Implement robust error handling in your application. The Square error handling guide describes common error codes and how to interpret them.
5. Switch to Production: After thorough testing in the sandbox, switch your application's access token and environment to production. This involves generating a production access token in the Developer Dashboard and updating your application's configuration. This transition is documented in the Square production access tokens guide.
6. Review PCI DSS Compliance: If your application handles payment card data, understand your responsibilities regarding PCI DSS compliance. Square's APIs are designed to help you meet these requirements, but specific implementation details can affect your compliance posture.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Invalid Access Token: Ensure you are using the correct Sandbox Access Token. Production tokens will not work in the Sandbox environment, and vice-versa. Double-check for typos or leading/trailing spaces.
• Incorrect API Version: Verify that the Square-Version header matches a supported API version. An outdated or incorrect version can lead to unexpected responses. Consult the Square API versions documentation.
• Network Issues: Check your internet connection and any firewall settings that might block outgoing requests.
• HTTP Status Codes: Pay attention to the HTTP status code returned in the API response. Common errors include:
• 401 Unauthorized: Indicates an issue with your access token (missing, invalid, or expired).
• 403 Forbidden: Your application's permissions might not allow the requested action, or the access token is incorrect for the environment.
• 404 Not Found: The endpoint URL might be incorrect, or the resource you're trying to access doesn't exist.
• 500 Internal Server Error: A problem on Square's side. While rare, it's good to have retry logic.
• Error Response Body: Square API error responses typically include a JSON body with details about the error, including a category, code, and detail field. Analyze these fields for specific guidance on resolving the issue. For a comprehensive list of errors, refer to the Square API error codes.
• Sandbox vs. Production Environment: Always ensure your API calls are directed to the correct environment (connect.squareupsandbox.com for sandbox, connect.squareup.com for production).