Square API Essential Guide

Aug 1, 2024 • 6 minute read

What type of API does Square provide?

Square primarily offers a REST API. Applications can manage Square resources like payments, orders, and catalog items by making HTTPS requests to URLs representing those resources.

Square also provides a GraphQL API. It supports query operations only, not mutations or subscriptions. It allows retrieving data that would normally require multiple REST API calls in a single query. It's accessible via two endpoints - one for production and one for sandbox testing. It has some limitations compared to the REST API, like not supporting all custom attributes.

The GraphQL API is more limited in scope than the REST API, but can be more efficient for certain types of data retrieval.

Does the Square API have webhooks?

Yes, the official Square API does have webhooks. Here are the key points about Square's webhook functionality:

Webhook Support

Square offers webhooks that allow you to subscribe to real-time notifications about events in a Square account.
Webhooks replace the need for regular API polling by providing instant, real-time notifications when events occur.

Event Types

You can subscribe to a wide variety of event types, including but not limited to:

Payment events (e.g., payment.created)
Order events (e.g., order.updated)
Invoice events (e.g., invoice.created)
Booking events (e.g., booking.created)
Card events (e.g., card.disabled)
Customer events (e.g., customer.created)

Subscribing to Events

There are two main ways to subscribe to webhook events:

Using the Developer Dashboard
Programmatically using the Webhook Subscriptions API

Key Considerations

Webhooks require a notification URL that Square will send POST requests to when events occur.
You need to respond with a 2xx HTTP status code to acknowledge receipt of the event notification.
Square provides an SLA where most event notifications arrive in under 60 seconds.
You can use the ListWebhookEventTypes endpoint to see all available event types you can subscribe to.

Best Practices

Use webhooks for real-time updates to avoid unnecessary API polling.
Implement proper error handling and retries in your webhook endpoint.
Verify the authenticity of webhook notifications using the provided signature key.
Consider using the Events API as a complementary or backup method to retrieve events.

In summary, Square's webhook system provides a robust way to receive real-time notifications about various events in a Square account, allowing for more efficient and responsive integrations.

Rate Limits and other limitations

Based on the search results provided, here are the key points regarding API rate limits for Square:

No Official Public Disclosure of Specific Limits

Square does not publicly disclose specific rate limit numbers for their API. As stated by a Square representative:

"At this time we don't disclose the limits. If you follow our guidance on how to handle rate limits you'll be just fine."

Recommendations for Handling Rate Limits

Square recommends the following approach for dealing with rate limits:

Implement a retry mechanism with an exponential backoff schedule
Add some randomness to the retry timing to avoid a "thundering herd effect"
Monitor responses for 429 RATE_LIMITED errors
When rate limited, resend requests at an increasingly slower rate

General Rate Limit Information

While specific numbers are not provided, some general information is available:

Rate limits are in place but not documented
The Create Order endpoint has a stricter rate limit of 100 requests per hour per website when using API Key authentication (this does not apply for OAuth)
Rate limits may vary by endpoint

Best Practices

Implement proper error handling for rate limit errors (429 responses)
Use exponential backoff and jitter in retry logic
Consider using Square's SDKs which may have built-in retry logic

Key Considerations

Rate limits help protect Square's infrastructure and ensure fair usage across all developers
While specific limits are not disclosed, following Square's guidance on handling rate limits should prevent most issues
If you have concerns about your specific use case, you may be able to contact Square support for more details

In summary, while Square does not publicly disclose specific API rate limits, they provide guidance on how to properly handle rate limiting through retry mechanisms and proper error handling. By following these best practices, most applications should be able to work within Square's rate limits effectively.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Square API:

Latest Version

The most recent version of the Square API is 2024-07-17.

Key Points

Square uses a date-based versioning scheme in the format YYYY-MM-DD for their API versions.
The latest version (2024-07-17) was released on July 17, 2024.
Square typically updates their API and SDK versions on a monthly basis.

Version Management

Each application created in the Developer Dashboard has a default API version, which can be viewed or updated on the Credentials page.
Developers can override the default version by explicitly specifying an API version in the Square-Version header in their requests.
This allows developers to test different API versions before upgrading.

SDK Versioning

Square SDKs follow a Semantic Versioning scheme (MAJOR.MINOR.PATCH).
Some SDKs (Java, Ruby, Python, PHP) include the Square API version in their version number.
SDK releases typically coincide with the release of a Square API version, but can be updated independently.

Best Practices

Check the release notes for each API version to decide whether to upgrade.
Test migrations by explicitly specifying the preferred Square-Version in your requests before fully upgrading.
Upgrade the SDK version if you want to use functionality added in a newer Square API version.

It's important to stay updated with the latest version to access new features, bug fixes, and improvements. However, always test thoroughly before upgrading in a production environment.

How to get a Square developer account and API Keys?

Create a Square Developer Account

Go to the Square Developer sign-up page at https://developer.squareup.com/us/en/signup.
If you already have a Square account, sign in with those credentials. Otherwise, create a new account.
Provide the following information:
- Your name
- Email address
- Password
- Country
Agree to Square's Terms, including the Privacy Policy and E-Sign Consent.
Enter a business name. If you work for a Square merchant, use their name. Otherwise, use your own software development business name.
Provide an application name. This is the name of your project and doesn't need to match your final application branding.
Optionally, provide information about:
- Your use case
- Programming language you plan to use
- Target audience
You can skip these optional steps if you're not sure yet.

Access the Developer Dashboard

Once you complete the sign-up process:

Square will open your new application in the Developer Dashboard.
You can now explore Square APIs using the Square Sandbox and begin development.
If you signed in with an existing Square account, you can access the Developer Dashboard from the Account menu.

Key Points to Consider

When you're ready to take payments in the production environment, you must activate your Square account at squareup.com/activation.
The Developer Dashboard provides you with credentials for both production applications and testing in the Square Sandbox.
To access resources in your own account, you'll use a personal access token.
To manage resources in other Square accounts, you'll need to use OAuth to request permissions from the account owner.

What can you do with the Square API?

Here's a list of data models you can interact with using the Square API, along with what is possible for each:

Customers

Create, retrieve, update, and delete customer profiles
Search for customers using supported query filters
Manage customer group memberships
Add custom attributes to customer profiles
Synchronize customer data with the Customer Directory using webhooks

Orders

Retrieve sales data for a Square seller
Itemize payments
Push orders to Point of Sale (POS) systems
Create and manage orders

Catalog

Programmatically manage a Square seller's products and services
Create, update, and delete catalog items, including products, services, and pricing
Manage item variations, modifiers, and categories

Bookings

Create and manage bookings for Square sellers
Define appointment segments and availability
Manage booking schedules and resources

Payments

Process payments
Retrieve payment details
Refund payments
Handle various payment methods, including ACH, Afterpay, and more

Locations

Retrieve information about a seller's business locations
Manage location-specific settings and data

Team Members

Manage employee information and permissions
Create and update team member profiles

Inventory

Track and manage inventory levels
Adjust inventory counts
Retrieve inventory information

Loyalty

Create and manage loyalty programs
Track customer loyalty points and rewards

Merchants

Retrieve merchant account information
Manage merchant settings

Subscriptions

Create and manage recurring payment plans
Handle subscription billing and invoicing

Disputes

Manage payment disputes and chargebacks
Submit evidence for disputes

Gift Cards

Create and manage gift card programs
Process gift card transactions

Custom Attributes

Add custom fields to various Square objects
Define and manage custom attribute definitions

Webhooks

Set up and manage webhook subscriptions
Receive real-time notifications for various events

Each of these data models offers a range of operations, typically including create, read, update, and delete (CRUD) functionality, as well as specialized actions specific to the model. The Square API provides a comprehensive set of tools for managing various aspects of a business, from customer relationships to financial transactions and inventory management.